File indexing completed on 2024-04-28 03:53:48
0001 /* 0002 This file is part of the KDE libraries 0003 0004 SPDX-FileCopyrightText: 1999 Ian Zepp <icszepp@islc.net> 0005 SPDX-FileCopyrightText: 2000 Rik Hemsley (rikkus) <rik@kde.org> 0006 SPDX-FileCopyrightText: 2006 Dominic Battre <dominic@battre.de> 0007 SPDX-FileCopyrightText: 2006 Martin Pool <mbp@canonical.com> 0008 0009 SPDX-License-Identifier: LGPL-2.0-only 0010 */ 0011 #ifndef KSTRINGHANDLER_H 0012 #define KSTRINGHANDLER_H 0013 0014 #include <kcoreaddons_export.h> 0015 0016 #include <QStringList> 0017 #include <qnamespace.h> 0018 0019 class QChar; 0020 class QRegularExpression; 0021 class QString; 0022 0023 /** 0024 * This namespace contains utility functions for handling strings. 0025 * 0026 * The functions here are intended to provide an easy way to 0027 * cut/slice/splice words inside sentences in whatever order desired. 0028 * While the main focus of KStringHandler is words (ie characters 0029 * separated by spaces/tabs), the two core functions here (split() 0030 * and join()) will allow you to use any character as a separator 0031 * This will make it easy to redefine what a 'word' means in the 0032 * future if needed. 0033 * 0034 * The function names and calling styles are based on python and mIRC's 0035 * scripting support. 0036 * 0037 * The ranges are a fairly powerful way of getting/stripping words from 0038 * a string. These ranges function, for the large part, as they would in 0039 * python. See the word(const QString&, int) and remword(const QString&, int) 0040 * functions for more detail. 0041 * 0042 * The methods here are completely stateless. All strings are cut 0043 * on the fly and returned as new qstrings/qstringlists. 0044 * 0045 * @short Namespace for manipulating words and sentences in strings 0046 * @author Ian Zepp <icszepp@islc.net> 0047 * @see KShell 0048 */ 0049 namespace KStringHandler 0050 { 0051 /** Capitalizes each word in the string 0052 * "hello there" becomes "Hello There" (string) 0053 * @param text the text to capitalize 0054 * @return the resulting string 0055 */ 0056 KCOREADDONS_EXPORT QString capwords(const QString &text); 0057 0058 /** Capitalizes each word in the list 0059 * [hello, there] becomes [Hello, There] (list) 0060 * @param list the list to capitalize 0061 * @return the resulting list 0062 */ 0063 KCOREADDONS_EXPORT QStringList capwords(const QStringList &list); 0064 0065 /** Substitute characters at the beginning of a string by "...". 0066 * @param str is the string to modify 0067 * @param maxlen is the maximum length the modified string will have 0068 * If the original string is shorter than "maxlen", it is returned verbatim 0069 * @return the modified string 0070 */ 0071 KCOREADDONS_EXPORT QString lsqueeze(const QString &str, int maxlen = 40); 0072 0073 /** Substitute characters at the middle of a string by "...". 0074 * @param str is the string to modify 0075 * @param maxlen is the maximum length the modified string will have 0076 * If the original string is shorter than "maxlen", it is returned verbatim 0077 * @return the modified string 0078 */ 0079 KCOREADDONS_EXPORT QString csqueeze(const QString &str, int maxlen = 40); 0080 0081 /** Substitute characters at the end of a string by "...". 0082 * @param str is the string to modify 0083 * @param maxlen is the maximum length the modified string will have 0084 * If the original string is shorter than "maxlen", it is returned verbatim 0085 * @return the modified string 0086 */ 0087 KCOREADDONS_EXPORT QString rsqueeze(const QString &str, int maxlen = 40); 0088 0089 /** 0090 * Split a string into a QStringList in a similar fashion to the static 0091 * QStringList function in Qt, except you can specify a maximum number 0092 * of tokens. If max is specified (!= 0) then only that number of tokens 0093 * will be extracted. The final token will be the remainder of the string. 0094 * 0095 * Example: 0096 * @code 0097 * perlSplit("__", "some__string__for__you__here", 4) 0098 * QStringList contains: "some", "string", "for", "you__here" 0099 * @endcode 0100 * 0101 * @param sep is the string to use to delimit @p str 0102 * @param str the string to split 0103 * @param max the maximum number of extractions to perform, or 0 0104 * @return A QStringList containing tokens extracted from @p str 0105 * 0106 * @since 5.87 0107 */ 0108 KCOREADDONS_EXPORT QStringList perlSplit(const QStringView sep, const QStringView str, int max); 0109 0110 /** 0111 * Split a QString into a QStringList in a similar fashion to the static 0112 * QStringList function in Qt, except you can specify a maximum number 0113 * of tokens. If max is specified (!= 0) then only that number of tokens 0114 * will be extracted. The final token will be the remainder of the string. 0115 * 0116 * Example: 0117 * \code 0118 * perlSplit("__", "some__string__for__you__here", 4) 0119 * QStringList contains: "some", "string", "for", "you__here" 0120 * \endcode 0121 * 0122 * @param sep is the string to use to delimit s. 0123 * @param s is the input string 0124 * @param max is the maximum number of extractions to perform, or 0. 0125 * @return A QStringList containing tokens extracted from s. 0126 */ 0127 KCOREADDONS_EXPORT QStringList perlSplit(const QString &sep, const QString &s, int max = 0); 0128 0129 /** 0130 * Split a QString into a QStringList in a similar fashion to the static 0131 * QStringList function in Qt, except you can specify a maximum number 0132 * of tokens. If max is specified (!= 0) then only that number of tokens 0133 * will be extracted. The final token will be the remainder of the string. 0134 * 0135 * Example: 0136 * \code 0137 * perlSplit(' ', "kparts reaches the parts other parts can't", 3) 0138 * QStringList contains: "kparts", "reaches", "the parts other parts can't" 0139 * \endcode 0140 * 0141 * @param sep is the character to use to delimit s. 0142 * @param s is the input string 0143 * @param max is the maximum number of extractions to perform, or 0. 0144 * @return A QStringList containing tokens extracted from s. 0145 */ 0146 KCOREADDONS_EXPORT QStringList perlSplit(const QChar &sep, const QString &s, int max = 0); 0147 0148 /** 0149 * Split a QString into a QStringList in a similar fashion to the static 0150 * QStringList function in Qt, except you can specify a maximum number 0151 * of tokens. If max is specified (!= 0) then only that number of tokens 0152 * will be extracted. The final token will be the remainder of the string. 0153 * 0154 * Example: 0155 * \code 0156 * perlSplit(QRegularExpression("[! ]"), "Split me up ! I'm bored ! OK ?", 3) 0157 * QStringList contains: "Split", "me", "up ! I'm bored ! OK ?" 0158 * \endcode 0159 * 0160 * @param sep is the regular expression to use to delimit s. 0161 * @param s is the input string 0162 * @param max is the maximum number of extractions to perform, or 0. 0163 * @return A QStringList containing tokens extracted from s. 0164 * 0165 * @since 5.67 0166 */ 0167 KCOREADDONS_EXPORT QStringList perlSplit(const QRegularExpression &sep, const QString &s, int max = 0); 0168 0169 /** 0170 * This method auto-detects URLs in strings, and adds HTML markup to them 0171 * so that richtext or HTML-enabled widgets will display the URL correctly. 0172 * @param text the string which may contain URLs 0173 * @return the resulting text 0174 */ 0175 KCOREADDONS_EXPORT QString tagUrls(const QString &text); 0176 0177 /** 0178 Obscure string by using a simple symmetric encryption. Applying the 0179 function to a string obscured by this function will result in the original 0180 string. 0181 0182 The function can be used to obscure passwords stored to configuration 0183 files. Note that this won't give you any more security than preventing 0184 that the password is directly copied and pasted. 0185 0186 @param str string to be obscured 0187 @return obscured string 0188 */ 0189 KCOREADDONS_EXPORT QString obscure(const QString &str); 0190 0191 /** 0192 Preprocesses the given string in order to provide additional line breaking 0193 opportunities for QTextLayout. 0194 0195 This is done by inserting ZWSP (Zero-width space) characters in the string 0196 at points that wouldn't normally be considered word boundaries by QTextLayout, 0197 but where wrapping the text will produce good results. 0198 0199 Examples of such points includes after punctuation signs, underscores and 0200 dashes, that aren't followed by spaces. 0201 0202 @since 4.4 0203 */ 0204 KCOREADDONS_EXPORT QString preProcessWrap(const QString &text); 0205 0206 /** 0207 Returns the length that reflects the density of information in the text. In 0208 general the character from CJK languages are assigned with weight 2, while 0209 other Latin characters are assigned with 1. 0210 0211 @since 5.41 0212 */ 0213 KCOREADDONS_EXPORT int logicalLength(const QString &text); 0214 0215 } 0216 #endif