File indexing completed on 2024-05-12 11:48:04
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 QRegExp; 0021 class QRegularExpression; 0022 class QString; 0023 0024 /** 0025 * This namespace contains utility functions for handling strings. 0026 * 0027 * The functions here are intended to provide an easy way to 0028 * cut/slice/splice words inside sentences in whatever order desired. 0029 * While the main focus of KStringHandler is words (ie characters 0030 * separated by spaces/tabs), the two core functions here (split() 0031 * and join()) will allow you to use any character as a separator 0032 * This will make it easy to redefine what a 'word' means in the 0033 * future if needed. 0034 * 0035 * The function names and calling styles are based on python and mIRC's 0036 * scripting support. 0037 * 0038 * The ranges are a fairly powerful way of getting/stripping words from 0039 * a string. These ranges function, for the large part, as they would in 0040 * python. See the word(const QString&, int) and remword(const QString&, int) 0041 * functions for more detail. 0042 * 0043 * The methods here are completely stateless. All strings are cut 0044 * on the fly and returned as new qstrings/qstringlists. 0045 * 0046 * @short Namespace for manipulating words and sentences in strings 0047 * @author Ian Zepp <icszepp@islc.net> 0048 * @see KShell 0049 */ 0050 namespace KStringHandler 0051 { 0052 /** Capitalizes each word in the string 0053 * "hello there" becomes "Hello There" (string) 0054 * @param text the text to capitalize 0055 * @return the resulting string 0056 */ 0057 KCOREADDONS_EXPORT QString capwords(const QString &text); 0058 0059 /** Capitalizes each word in the list 0060 * [hello, there] becomes [Hello, There] (list) 0061 * @param list the list to capitalize 0062 * @return the resulting list 0063 */ 0064 KCOREADDONS_EXPORT QStringList capwords(const QStringList &list); 0065 0066 /** Substitute characters at the beginning of a string by "...". 0067 * @param str is the string to modify 0068 * @param maxlen is the maximum length the modified string will have 0069 * If the original string is shorter than "maxlen", it is returned verbatim 0070 * @return the modified string 0071 */ 0072 KCOREADDONS_EXPORT QString lsqueeze(const QString &str, int maxlen = 40); 0073 0074 /** Substitute characters at the middle of a string by "...". 0075 * @param str is the string to modify 0076 * @param maxlen is the maximum length the modified string will have 0077 * If the original string is shorter than "maxlen", it is returned verbatim 0078 * @return the modified string 0079 */ 0080 KCOREADDONS_EXPORT QString csqueeze(const QString &str, int maxlen = 40); 0081 0082 /** Substitute characters at the end of a string by "...". 0083 * @param str is the string to modify 0084 * @param maxlen is the maximum length the modified string will have 0085 * If the original string is shorter than "maxlen", it is returned verbatim 0086 * @return the modified string 0087 */ 0088 KCOREADDONS_EXPORT QString rsqueeze(const QString &str, int maxlen = 40); 0089 0090 /** 0091 * Split a string into a QStringList in a similar fashion to the static 0092 * QStringList function in Qt, except you can specify a maximum number 0093 * of tokens. If max is specified (!= 0) then only that number of tokens 0094 * will be extracted. The final token will be the remainder of the string. 0095 * 0096 * Example: 0097 * @code 0098 * perlSplit("__", "some__string__for__you__here", 4) 0099 * QStringList contains: "some", "string", "for", "you__here" 0100 * @endcode 0101 * 0102 * @param sep is the string to use to delimit @p str 0103 * @param str the string to split 0104 * @param max the maximum number of extractions to perform, or 0 0105 * @return A QStringList containing tokens extracted from @p str 0106 * 0107 * @since 5.87 0108 */ 0109 KCOREADDONS_EXPORT QStringList perlSplit(const QStringView sep, const QStringView str, int max); 0110 0111 /** 0112 * Split a QString into a QStringList in a similar fashion to the static 0113 * QStringList function in Qt, except you can specify a maximum number 0114 * of tokens. If max is specified (!= 0) then only that number of tokens 0115 * will be extracted. The final token will be the remainder of the string. 0116 * 0117 * Example: 0118 * \code 0119 * perlSplit("__", "some__string__for__you__here", 4) 0120 * QStringList contains: "some", "string", "for", "you__here" 0121 * \endcode 0122 * 0123 * @param sep is the string to use to delimit s. 0124 * @param s is the input string 0125 * @param max is the maximum number of extractions to perform, or 0. 0126 * @return A QStringList containing tokens extracted from s. 0127 */ 0128 KCOREADDONS_EXPORT QStringList perlSplit(const QString &sep, const QString &s, int max = 0); 0129 0130 /** 0131 * Split a QString into a QStringList in a similar fashion to the static 0132 * QStringList function in Qt, except you can specify a maximum number 0133 * of tokens. If max is specified (!= 0) then only that number of tokens 0134 * will be extracted. The final token will be the remainder of the string. 0135 * 0136 * Example: 0137 * \code 0138 * perlSplit(' ', "kparts reaches the parts other parts can't", 3) 0139 * QStringList contains: "kparts", "reaches", "the parts other parts can't" 0140 * \endcode 0141 * 0142 * @param sep is the character to use to delimit s. 0143 * @param s is the input string 0144 * @param max is the maximum number of extractions to perform, or 0. 0145 * @return A QStringList containing tokens extracted from s. 0146 */ 0147 KCOREADDONS_EXPORT QStringList perlSplit(const QChar &sep, const QString &s, int max = 0); 0148 0149 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 67) 0150 /** 0151 * Split a QString into a QStringList in a similar fashion to the static 0152 * QStringList function in Qt, except you can specify a maximum number 0153 * of tokens. If max is specified (!= 0) then only that number of tokens 0154 * will be extracted. The final token will be the remainder of the string. 0155 * 0156 * Example: 0157 * \code 0158 * perlSplit(QRegExp("[! ]"), "Split me up ! I'm bored ! OK ?", 3) 0159 * QStringList contains: "Split", "me", "up ! I'm bored ! OK ?" 0160 * \endcode 0161 * 0162 * @param sep is the regular expression to use to delimit s. 0163 * @param s is the input string 0164 * @param max is the maximum number of extractions to perform, or 0. 0165 * @return A QStringList containing tokens extracted from s. 0166 * 0167 * @deprecated Since 5.67, use perlSplit(const QRegularExpression &sep, 0168 * const QString &s, int max = 0) instead. 0169 */ 0170 KCOREADDONS_EXPORT 0171 KCOREADDONS_DEPRECATED_VERSION(5, 67, "Use KStringHandler::perlSplit(const QRegularExpression &, const QString &, int)") 0172 QStringList perlSplit(const QRegExp &sep, const QString &s, int max = 0); 0173 #endif 0174 0175 /** 0176 * Split a QString into a QStringList in a similar fashion to the static 0177 * QStringList function in Qt, except you can specify a maximum number 0178 * of tokens. If max is specified (!= 0) then only that number of tokens 0179 * will be extracted. The final token will be the remainder of the string. 0180 * 0181 * Example: 0182 * \code 0183 * perlSplit(QRegularExpression("[! ]"), "Split me up ! I'm bored ! OK ?", 3) 0184 * QStringList contains: "Split", "me", "up ! I'm bored ! OK ?" 0185 * \endcode 0186 * 0187 * @param sep is the regular expression to use to delimit s. 0188 * @param s is the input string 0189 * @param max is the maximum number of extractions to perform, or 0. 0190 * @return A QStringList containing tokens extracted from s. 0191 * 0192 * @since 5.67 0193 */ 0194 KCOREADDONS_EXPORT QStringList perlSplit(const QRegularExpression &sep, const QString &s, int max = 0); 0195 0196 /** 0197 * This method auto-detects URLs in strings, and adds HTML markup to them 0198 * so that richtext or HTML-enabled widgets will display the URL correctly. 0199 * @param text the string which may contain URLs 0200 * @return the resulting text 0201 */ 0202 KCOREADDONS_EXPORT QString tagUrls(const QString &text); 0203 0204 /** 0205 Obscure string by using a simple symmetric encryption. Applying the 0206 function to a string obscured by this function will result in the original 0207 string. 0208 0209 The function can be used to obscure passwords stored to configuration 0210 files. Note that this won't give you any more security than preventing 0211 that the password is directly copied and pasted. 0212 0213 @param str string to be obscured 0214 @return obscured string 0215 */ 0216 KCOREADDONS_EXPORT QString obscure(const QString &str); 0217 0218 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 112) 0219 /** 0220 Guess whether a string is UTF8 encoded. 0221 0222 @param str the string to check 0223 @return true if UTF8. If false, the string is probably in Local8Bit. 0224 @deprecated Since 5.112, no known users. 0225 */ 0226 KCOREADDONS_EXPORT 0227 KCOREADDONS_DEPRECATED_VERSION(5, 112, "No known users") 0228 bool isUtf8(const char *str); 0229 #endif 0230 0231 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 112) 0232 /** 0233 Construct QString from a c string, guessing whether it is UTF8- or 0234 Local8Bit-encoded. 0235 0236 @param str the input string 0237 @return the (hopefully correctly guessed) QString representation of @p str 0238 @see KEncodingProber 0239 @deprecated Since 5.112, no known users. 0240 */ 0241 KCOREADDONS_EXPORT 0242 KCOREADDONS_DEPRECATED_VERSION(5, 112, "No known users") 0243 QString from8Bit(const char *str); 0244 #endif 0245 0246 /** 0247 Preprocesses the given string in order to provide additional line breaking 0248 opportunities for QTextLayout. 0249 0250 This is done by inserting ZWSP (Zero-width space) characters in the string 0251 at points that wouldn't normally be considered word boundaries by QTextLayout, 0252 but where wrapping the text will produce good results. 0253 0254 Examples of such points includes after punctuation signs, underscores and 0255 dashes, that aren't followed by spaces. 0256 0257 @since 4.4 0258 */ 0259 KCOREADDONS_EXPORT QString preProcessWrap(const QString &text); 0260 0261 /** 0262 Returns the length that reflects the density of information in the text. In 0263 general the character from CJK languages are assigned with weight 2, while 0264 other Latin characters are assigned with 1. 0265 0266 @since 5.41 0267 */ 0268 KCOREADDONS_EXPORT int logicalLength(const QString &text); 0269 0270 } 0271 #endif