1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1999 Ian Zepp (icszepp@islc.net) |
3 | Copyright (C) 2000 Rik Hemsley (rikkus) <rik@kde.org> |
4 | Copyright (C) 2006 by Dominic Battre <dominic@battre.de> |
5 | Copyright (C) 2006 by Martin Pool <mbp@canonical.com> |
6 | |
7 | This library is free software; you can redistribute it and/or |
8 | modify it under the terms of the GNU Library General Public |
9 | License version 2 as published by the Free Software Foundation. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | #ifndef KSTRINGHANDLER_H |
22 | #define KSTRINGHANDLER_H |
23 | |
24 | #include <kdecore_export.h> |
25 | |
26 | #include <QtCore/qnamespace.h> |
27 | |
28 | class QChar; |
29 | class QRegExp; |
30 | class QString; |
31 | class QStringList; |
32 | |
33 | /** |
34 | * This namespace contains utility functions for handling strings. |
35 | * |
36 | * The functions here are intended to provide an easy way to |
37 | * cut/slice/splice words inside sentences in whatever order desired. |
38 | * While the main focus of KStringHandler is words (ie characters |
39 | * separated by spaces/tabs), the two core functions here (split() |
40 | * and join()) will allow you to use any character as a separator |
41 | * This will make it easy to redefine what a 'word' means in the |
42 | * future if needed. |
43 | * |
44 | * The function names and calling styles are based on python and mIRC's |
45 | * scripting support. |
46 | * |
47 | * The ranges are a fairly powerful way of getting/stripping words from |
48 | * a string. These ranges function, for the large part, as they would in |
49 | * python. See the word(const QString&, int) and remword(const QString&, int) |
50 | * functions for more detail. |
51 | * |
52 | * The methods here are completely stateless. All strings are cut |
53 | * on the fly and returned as new qstrings/qstringlists. |
54 | * |
55 | * @short Namespace for manipulating words and sentences in strings |
56 | * @author Ian Zepp <icszepp@islc.net> |
57 | * @see KShell |
58 | */ |
59 | namespace KStringHandler |
60 | { |
61 | |
62 | /** Capitalizes each word in the string |
63 | * "hello there" becomes "Hello There" (string) |
64 | * @param text the text to capitalize |
65 | * @return the resulting string |
66 | */ |
67 | KDECORE_EXPORT QString capwords( const QString &text ); |
68 | |
69 | /** Capitalizes each word in the list |
70 | * [hello, there] becomes [Hello, There] (list) |
71 | * @param list the list to capitalize |
72 | * @return the resulting list |
73 | */ |
74 | KDECORE_EXPORT QStringList capwords( const QStringList &list ); |
75 | |
76 | /** Substitute characters at the beginning of a string by "...". |
77 | * @param str is the string to modify |
78 | * @param maxlen is the maximum length the modified string will have |
79 | * If the original string is shorter than "maxlen", it is returned verbatim |
80 | * @return the modified string |
81 | */ |
82 | KDECORE_EXPORT QString lsqueeze( const QString & str, int maxlen = 40 ); |
83 | |
84 | /** Substitute characters at the middle of a string by "...". |
85 | * @param str is the string to modify |
86 | * @param maxlen is the maximum length the modified string will have |
87 | * If the original string is shorter than "maxlen", it is returned verbatim |
88 | * @return the modified string |
89 | */ |
90 | KDECORE_EXPORT QString csqueeze( const QString & str, int maxlen = 40 ); |
91 | |
92 | /** Substitute characters at the end of a string by "...". |
93 | * @param str is the string to modify |
94 | * @param maxlen is the maximum length the modified string will have |
95 | * If the original string is shorter than "maxlen", it is returned verbatim |
96 | * @return the modified string |
97 | */ |
98 | KDECORE_EXPORT QString rsqueeze( const QString & str, int maxlen = 40 ); |
99 | |
100 | /** |
101 | * Split a QString into a QStringList in a similar fashion to the static |
102 | * QStringList function in Qt, except you can specify a maximum number |
103 | * of tokens. If max is specified (!= 0) then only that number of tokens |
104 | * will be extracted. The final token will be the remainder of the string. |
105 | * |
106 | * Example: |
107 | * \code |
108 | * perlSplit("__", "some__string__for__you__here", 4) |
109 | * QStringList contains: "some", "string", "for", "you__here" |
110 | * \endcode |
111 | * |
112 | * @param sep is the string to use to delimit s. |
113 | * @param s is the input string |
114 | * @param max is the maximum number of extractions to perform, or 0. |
115 | * @return A QStringList containing tokens extracted from s. |
116 | */ |
117 | KDECORE_EXPORT QStringList perlSplit( const QString & sep, |
118 | const QString & s, |
119 | int max = 0 ); |
120 | |
121 | /** |
122 | * Split a QString into a QStringList in a similar fashion to the static |
123 | * QStringList function in Qt, except you can specify a maximum number |
124 | * of tokens. If max is specified (!= 0) then only that number of tokens |
125 | * will be extracted. The final token will be the remainder of the string. |
126 | * |
127 | * Example: |
128 | * \code |
129 | * perlSplit(' ', "kparts reaches the parts other parts can't", 3) |
130 | * QStringList contains: "kparts", "reaches", "the parts other parts can't" |
131 | * \endcode |
132 | * |
133 | * @param sep is the character to use to delimit s. |
134 | * @param s is the input string |
135 | * @param max is the maximum number of extractions to perform, or 0. |
136 | * @return A QStringList containing tokens extracted from s. |
137 | */ |
138 | KDECORE_EXPORT QStringList perlSplit( const QChar & sep, |
139 | const QString & s, |
140 | int max = 0 ); |
141 | |
142 | /** |
143 | * Split a QString into a QStringList in a similar fashion to the static |
144 | * QStringList function in Qt, except you can specify a maximum number |
145 | * of tokens. If max is specified (!= 0) then only that number of tokens |
146 | * will be extracted. The final token will be the remainder of the string. |
147 | * |
148 | * Example: |
149 | * \code |
150 | * perlSplit(QRegExp("[! ]"), "Split me up ! I'm bored ! OK ?", 3) |
151 | * QStringList contains: "Split", "me", "up ! I'm bored ! OK ?" |
152 | * \endcode |
153 | * |
154 | * @param sep is the regular expression to use to delimit s. |
155 | * @param s is the input string |
156 | * @param max is the maximum number of extractions to perform, or 0. |
157 | * @return A QStringList containing tokens extracted from s. |
158 | */ |
159 | KDECORE_EXPORT QStringList perlSplit( const QRegExp & sep, |
160 | const QString & s, |
161 | int max = 0); |
162 | |
163 | /** |
164 | * This method auto-detects URLs in strings, and adds HTML markup to them |
165 | * so that richtext or HTML-enabled widgets will display the URL correctly. |
166 | * @param text the string which may contain URLs |
167 | * @return the resulting text |
168 | */ |
169 | KDECORE_EXPORT QString tagUrls( const QString& text ); |
170 | |
171 | /** |
172 | Obscure string by using a simple symmetric encryption. Applying the |
173 | function to a string obscured by this function will result in the original |
174 | string. |
175 | |
176 | The function can be used to obscure passwords stored to configuration |
177 | files. Note that this won't give you any more security than preventing |
178 | that the password is directly copied and pasted. |
179 | |
180 | @param str string to be obscured |
181 | @return obscured string |
182 | */ |
183 | KDECORE_EXPORT QString obscure( const QString &str ); |
184 | |
185 | |
186 | /** |
187 | Guess whether a string is UTF8 encoded. |
188 | |
189 | @param str the string to check |
190 | @return true if UTF8. If false, the string is probably in Local8Bit. |
191 | */ |
192 | KDECORE_EXPORT bool isUtf8( const char *str ); |
193 | |
194 | /** |
195 | Construct QString from a c string, guessing whether it is UTF8- or |
196 | Local8Bit-encoded. |
197 | |
198 | @param str the input string |
199 | @return the (hopefully correctly guessed) QString representation of @p str |
200 | @see KEncodingDetector |
201 | |
202 | */ |
203 | KDECORE_EXPORT QString from8Bit( const char *str ); |
204 | |
205 | /** |
206 | Does a natural comparing of the strings. A negative value is returned if \a a |
207 | is smaller than \a b. A positive value is returned if \a a is greater than \a b. 0 |
208 | is returned if both values are equal. |
209 | |
210 | @param a first string to compare |
211 | @param b second string to compare |
212 | @param caseSensitivity whether to use case sensitive compare or not |
213 | |
214 | @since 4.1 |
215 | */ |
216 | KDECORE_EXPORT int naturalCompare( const QString& a, const QString& b, Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive ); |
217 | |
218 | /** |
219 | Preprocesses the given string in order to provide additional line breaking |
220 | opportunities for QTextLayout. |
221 | |
222 | This is done by inserting ZWSP (Zero-width space) characters in the string |
223 | at points that wouldn't normally be considered word boundaries by QTextLayout, |
224 | but where wrapping the text will produce good results. |
225 | |
226 | Examples of such points includes after punctuation signs, underscores and |
227 | dashes, that aren't followed by spaces. |
228 | |
229 | @since 4.4 |
230 | */ |
231 | KDECORE_EXPORT QString preProcessWrap( const QString& text ); |
232 | } |
233 | #endif |
234 | |