KCoreAddons

kstringhandler.h
1 /*
2  This file is part of the KDE libraries
3 
4  SPDX-FileCopyrightText: 1999 Ian Zepp <[email protected]>
5  SPDX-FileCopyrightText: 2000 Rik Hemsley (rikkus) <[email protected]>
6  SPDX-FileCopyrightText: 2006 Dominic Battre <[email protected]>
7  SPDX-FileCopyrightText: 2006 Martin Pool <[email protected]>
8 
9  SPDX-License-Identifier: LGPL-2.0-only
10 */
11 #ifndef KSTRINGHANDLER_H
12 #define KSTRINGHANDLER_H
13 
14 #include <kcoreaddons_export.h>
15 
16 #include <QStringList>
17 #include <qnamespace.h>
18 
19 class QChar;
20 class QRegExp;
21 class QRegularExpression;
22 class QString;
23 
24 /**
25  * This namespace contains utility functions for handling strings.
26  *
27  * The functions here are intended to provide an easy way to
28  * cut/slice/splice words inside sentences in whatever order desired.
29  * While the main focus of KStringHandler is words (ie characters
30  * separated by spaces/tabs), the two core functions here (split()
31  * and join()) will allow you to use any character as a separator
32  * This will make it easy to redefine what a 'word' means in the
33  * future if needed.
34  *
35  * The function names and calling styles are based on python and mIRC's
36  * scripting support.
37  *
38  * The ranges are a fairly powerful way of getting/stripping words from
39  * a string. These ranges function, for the large part, as they would in
40  * python. See the word(const QString&, int) and remword(const QString&, int)
41  * functions for more detail.
42  *
43  * The methods here are completely stateless. All strings are cut
44  * on the fly and returned as new qstrings/qstringlists.
45  *
46  * @short Namespace for manipulating words and sentences in strings
47  * @author Ian Zepp <[email protected]>
48  * @see KShell
49  */
50 namespace KStringHandler
51 {
52 /** Capitalizes each word in the string
53  * "hello there" becomes "Hello There" (string)
54  * @param text the text to capitalize
55  * @return the resulting string
56  */
57 KCOREADDONS_EXPORT QString capwords(const QString &text);
58 
59 /** Capitalizes each word in the list
60  * [hello, there] becomes [Hello, There] (list)
61  * @param list the list to capitalize
62  * @return the resulting list
63  */
64 KCOREADDONS_EXPORT QStringList capwords(const QStringList &list);
65 
66 /** Substitute characters at the beginning of a string by "...".
67  * @param str is the string to modify
68  * @param maxlen is the maximum length the modified string will have
69  * If the original string is shorter than "maxlen", it is returned verbatim
70  * @return the modified string
71  */
72 KCOREADDONS_EXPORT QString lsqueeze(const QString &str, int maxlen = 40);
73 
74 /** Substitute characters at the middle of a string by "...".
75  * @param str is the string to modify
76  * @param maxlen is the maximum length the modified string will have
77  * If the original string is shorter than "maxlen", it is returned verbatim
78  * @return the modified string
79  */
80 KCOREADDONS_EXPORT QString csqueeze(const QString &str, int maxlen = 40);
81 
82 /** Substitute characters at the end of a string by "...".
83  * @param str is the string to modify
84  * @param maxlen is the maximum length the modified string will have
85  * If the original string is shorter than "maxlen", it is returned verbatim
86  * @return the modified string
87  */
88 KCOREADDONS_EXPORT QString rsqueeze(const QString &str, int maxlen = 40);
89 
90 /**
91  * Split a QString into a QStringList in a similar fashion to the static
92  * QStringList function in Qt, except you can specify a maximum number
93  * of tokens. If max is specified (!= 0) then only that number of tokens
94  * will be extracted. The final token will be the remainder of the string.
95  *
96  * Example:
97  * \code
98  * perlSplit("__", "some__string__for__you__here", 4)
99  * QStringList contains: "some", "string", "for", "you__here"
100  * \endcode
101  *
102  * @param sep is the string to use to delimit s.
103  * @param s is the input string
104  * @param max is the maximum number of extractions to perform, or 0.
105  * @return A QStringList containing tokens extracted from s.
106  */
107 KCOREADDONS_EXPORT QStringList perlSplit(const QString &sep, const QString &s, int max = 0);
108 
109 /**
110  * Split a QString into a QStringList in a similar fashion to the static
111  * QStringList function in Qt, except you can specify a maximum number
112  * of tokens. If max is specified (!= 0) then only that number of tokens
113  * will be extracted. The final token will be the remainder of the string.
114  *
115  * Example:
116  * \code
117  * perlSplit(' ', "kparts reaches the parts other parts can't", 3)
118  * QStringList contains: "kparts", "reaches", "the parts other parts can't"
119  * \endcode
120  *
121  * @param sep is the character to use to delimit s.
122  * @param s is the input string
123  * @param max is the maximum number of extractions to perform, or 0.
124  * @return A QStringList containing tokens extracted from s.
125  */
126 KCOREADDONS_EXPORT QStringList perlSplit(const QChar &sep, const QString &s, int max = 0);
127 
128 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 67)
129 /**
130  * Split a QString into a QStringList in a similar fashion to the static
131  * QStringList function in Qt, except you can specify a maximum number
132  * of tokens. If max is specified (!= 0) then only that number of tokens
133  * will be extracted. The final token will be the remainder of the string.
134  *
135  * Example:
136  * \code
137  * perlSplit(QRegExp("[! ]"), "Split me up ! I'm bored ! OK ?", 3)
138  * QStringList contains: "Split", "me", "up ! I'm bored ! OK ?"
139  * \endcode
140  *
141  * @param sep is the regular expression to use to delimit s.
142  * @param s is the input string
143  * @param max is the maximum number of extractions to perform, or 0.
144  * @return A QStringList containing tokens extracted from s.
145  *
146  * @deprecated Since 5.67, use perlSplit(const QRegularExpression &sep,
147  * const QString &s, int max = 0) instead.
148  */
149 KCOREADDONS_DEPRECATED_VERSION(5, 67, "Use KStringHandler::perlSplit(const QRegularExpression &, const QString &, int)")
150 KCOREADDONS_EXPORT QStringList perlSplit(const QRegExp &sep, const QString &s, int max = 0);
151 #endif
152 
153 /**
154  * Split a QString into a QStringList in a similar fashion to the static
155  * QStringList function in Qt, except you can specify a maximum number
156  * of tokens. If max is specified (!= 0) then only that number of tokens
157  * will be extracted. The final token will be the remainder of the string.
158  *
159  * Example:
160  * \code
161  * perlSplit(QRegularExpression("[! ]"), "Split me up ! I'm bored ! OK ?", 3)
162  * QStringList contains: "Split", "me", "up ! I'm bored ! OK ?"
163  * \endcode
164  *
165  * @param sep is the regular expression to use to delimit s.
166  * @param s is the input string
167  * @param max is the maximum number of extractions to perform, or 0.
168  * @return A QStringList containing tokens extracted from s.
169  *
170  * @since 5.67
171  */
172 KCOREADDONS_EXPORT QStringList perlSplit(const QRegularExpression &sep, const QString &s, int max = 0);
173 
174 /**
175  * This method auto-detects URLs in strings, and adds HTML markup to them
176  * so that richtext or HTML-enabled widgets will display the URL correctly.
177  * @param text the string which may contain URLs
178  * @return the resulting text
179  */
180 KCOREADDONS_EXPORT QString tagUrls(const QString &text);
181 
182 /**
183  Obscure string by using a simple symmetric encryption. Applying the
184  function to a string obscured by this function will result in the original
185  string.
186 
187  The function can be used to obscure passwords stored to configuration
188  files. Note that this won't give you any more security than preventing
189  that the password is directly copied and pasted.
190 
191  @param str string to be obscured
192  @return obscured string
193 */
194 KCOREADDONS_EXPORT QString obscure(const QString &str);
195 
196 /**
197  Guess whether a string is UTF8 encoded.
198 
199  @param str the string to check
200  @return true if UTF8. If false, the string is probably in Local8Bit.
201  */
202 KCOREADDONS_EXPORT bool isUtf8(const char *str);
203 
204 /**
205  Construct QString from a c string, guessing whether it is UTF8- or
206  Local8Bit-encoded.
207 
208  @param str the input string
209  @return the (hopefully correctly guessed) QString representation of @p str
210  @see KEncodingProber
211 
212  */
213 KCOREADDONS_EXPORT QString from8Bit(const char *str);
214 
215 /**
216  Preprocesses the given string in order to provide additional line breaking
217  opportunities for QTextLayout.
218 
219  This is done by inserting ZWSP (Zero-width space) characters in the string
220  at points that wouldn't normally be considered word boundaries by QTextLayout,
221  but where wrapping the text will produce good results.
222 
223  Examples of such points includes after punctuation signs, underscores and
224  dashes, that aren't followed by spaces.
225 
226  @since 4.4
227 */
228 KCOREADDONS_EXPORT QString preProcessWrap(const QString &text);
229 
230 /**
231  Returns the length that reflects the density of information in the text. In
232  general the character from CJK languages are assigned with weight 2, while
233  other Latin characters are assigned with 1.
234 
235  @since 5.41
236 */
237 KCOREADDONS_EXPORT int logicalLength(const QString &text);
238 
239 }
240 #endif
KCOREADDONS_EXPORT int logicalLength(const QString &text)
Returns the length that reflects the density of information in the text.
KCOREADDONS_EXPORT QString from8Bit(const char *str)
Construct QString from a c string, guessing whether it is UTF8- or Local8Bit-encoded.
KCOREADDONS_EXPORT QString rsqueeze(const QString &str, int maxlen=40)
Substitute characters at the end of a string by "...".
This namespace contains utility functions for handling strings.
KCOREADDONS_EXPORT QString preProcessWrap(const QString &text)
Preprocesses the given string in order to provide additional line breaking opportunities for QTextLay...
KCOREADDONS_EXPORT bool isUtf8(const char *str)
Guess whether a string is UTF8 encoded.
KCOREADDONS_EXPORT QString csqueeze(const QString &str, int maxlen=40)
Substitute characters at the middle of a string by "...".
KCOREADDONS_EXPORT QStringList perlSplit(const QString &sep, const QString &s, int max=0)
Split a QString into a QStringList in a similar fashion to the static QStringList function in Qt...
KCOREADDONS_EXPORT QString capwords(const QString &text)
Capitalizes each word in the string "hello there" becomes "Hello There" (string)
KCOREADDONS_EXPORT QString lsqueeze(const QString &str, int maxlen=40)
Substitute characters at the beginning of a string by "...".
KCOREADDONS_EXPORT QString obscure(const QString &str)
Obscure string by using a simple symmetric encryption.
KCOREADDONS_EXPORT QString tagUrls(const QString &text)
This method auto-detects URLs in strings, and adds HTML markup to them so that richtext or HTML-enabl...
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Apr 18 2021 23:02:02 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.