Diffstat (limited to 'microkde/kdecore/kstringhandler.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | microkde/kdecore/kstringhandler.h | 417 |
1 files changed, 417 insertions, 0 deletions
diff --git a/microkde/kdecore/kstringhandler.h b/microkde/kdecore/kstringhandler.h new file mode 100644 index 0000000..d07b1e2 --- a/dev/null +++ b/microkde/kdecore/kstringhandler.h | |||
@@ -0,0 +1,417 @@ | |||
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 | |||
5 | This library is free software; you can redistribute it and/or | ||
6 | modify it under the terms of the GNU Library General Public | ||
7 | License version 2 as published by the Free Software Foundation. | ||
8 | |||
9 | This library is distributed in the hope that it will be useful, | ||
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | Library General Public License for more details. | ||
13 | |||
14 | You should have received a copy of the GNU Library General Public License | ||
15 | along with this library; see the file COPYING.LIB. If not, write to | ||
16 | the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
17 | Boston, MA 02111-1307, USA. | ||
18 | */ | ||
19 | #ifndef KSTRINGHANDLER_H | ||
20 | #define KSTRINGHANDLER_H | ||
21 | |||
22 | #include <stdlib.h> // for atoi() | ||
23 | #include <qstring.h> | ||
24 | #include <qstringlist.h> | ||
25 | #include <qregexp.h> // for the word ranges | ||
26 | #include <qfontmetrics.h> | ||
27 | |||
28 | /** | ||
29 | * This class contains utility functions for handling strings. | ||
30 | * | ||
31 | * This class is @em not a substitute for the @ref QString class. What | ||
32 | * I tried to do with this class is provide an easy way to | ||
33 | * cut/slice/splice words inside sentences in whatever order desired. | ||
34 | * While the main focus of this class are words (ie characters | ||
35 | * separated by spaces/tabs), the two core functions here (@ref split() | ||
36 | * and @ref join() ) will function given any char to use as a separator. | ||
37 | * This will make it easy to redefine what a 'word' means in the | ||
38 | * future if needed. | ||
39 | * | ||
40 | * I freely stole some of the function names from python. I also think | ||
41 | * some of these were influenced by mIRC (yes, believe it if you will, I | ||
42 | * used to write a LOT of scripts in mIRC). | ||
43 | * | ||
44 | * The ranges are a fairly powerful way of getting/stripping words from | ||
45 | * a string. These ranges function, for the large part, as they would in | ||
46 | * python. See the @ref word(const QString&, int) and @ref remword(const QString&, int) functions for more detail. | ||
47 | * | ||
48 | * This class contains no data members of it own. All strings are cut | ||
49 | * on the fly and returned as new qstrings/qstringlists. | ||
50 | * | ||
51 | * Quick example on how to use: | ||
52 | * | ||
53 | * <pre> | ||
54 | * KStringHandler kstr; | ||
55 | * QString line = "This is a test of the strings"; | ||
56 | * | ||
57 | * cout << "1> " << kstr.word( line , "4:" ) << "\n"; | ||
58 | * cout << "2> " << kstr.remrange( line , "2:5" ) << "\n"; | ||
59 | * cout << "2> " << kstr.reverse( line ) << "\n"; | ||
60 | * cout << "2> " << kstr.center( kstr.word( line , 4 ) , 15 ) << "\n"; | ||
61 | * </pre> | ||
62 | * | ||
63 | * and so forth. | ||
64 | * | ||
65 | * @short Class for manipulating words and sentences in strings | ||
66 | * @author Ian Zepp <icszepp@islc.net> | ||
67 | */ | ||
68 | class KStringHandler | ||
69 | { | ||
70 | public: | ||
71 | /** Returns the nth word in the string if found | ||
72 | * Returns a EMPTY (not null) string otherwise. | ||
73 | * Note that the FIRST index is 0. | ||
74 | * @param text the string to search for the words | ||
75 | * @param pos the position of the word to search | ||
76 | * @return the word, or an empty string if not found | ||
77 | */ | ||
78 | //US static QString word( const QString &text , uint pos ); | ||
79 | |||
80 | /** Returns a range of words from that string. | ||
81 | * Ie: | ||
82 | * @li "0" returns the very first word | ||
83 | * @li "0:" returns the first to the last word | ||
84 | * @li "0:3" returns the first to fourth words | ||
85 | * @li ":3" returns everything up to the fourth word | ||
86 | * | ||
87 | * If you grok python, you're set. | ||
88 | * @param text the string to search for the words | ||
89 | * @param range the words to return (see description) | ||
90 | * @return the words, or an empty string if not found | ||
91 | */ | ||
92 | //US static QString word( const QString &text , const char *range ); | ||
93 | |||
94 | /** Inserts a word into the string, and returns | ||
95 | * a new string with the word included. the first | ||
96 | * index is zero (0). If there are not @p pos words in the original | ||
97 | * string, the new word will be appended to the end. | ||
98 | * @param text the original text | ||
99 | * @param word the word to insert | ||
100 | * @param pos the position (in words) for the new word | ||
101 | * @return the resulting string | ||
102 | */ | ||
103 | //US static QString insword( const QString &text , const QString &word , uint pos ); | ||
104 | |||
105 | /** Replaces a word in the string, and returns | ||
106 | * a new string with the word included. the first | ||
107 | * index is zero (0). If there are not @p pos words in the original | ||
108 | * string, the new word will be appended to the end. | ||
109 | * @param text the original text | ||
110 | * @param word the word to insert | ||
111 | * @param pos the position (in words) for the new word | ||
112 | * @return the resulting string | ||
113 | */ | ||
114 | //US static QString setword( const QString &text , const QString &word , uint pos ); | ||
115 | |||
116 | /** Removes a word or ranges of words from the string, | ||
117 | * and returns a new string. The ranges definitions | ||
118 | * follow the definitions for the word() function. | ||
119 | * | ||
120 | * @li "0" removes the very first word | ||
121 | * @li "0:" removes the first the the last word | ||
122 | * @li "0:3" removes the first to fourth words | ||
123 | * @li ":3" removes everything up to the fourth word | ||
124 | * @param text the original text | ||
125 | * @param range the words to remove (see description) | ||
126 | * @return the resulting string | ||
127 | */ | ||
128 | //US static QString remrange( const QString &text , const char *range ); | ||
129 | |||
130 | |||
131 | /** Removes a word at the given index, and returns a | ||
132 | * new string. The first index is zero (0). | ||
133 | * @param text the original text | ||
134 | * @param pos the position (in words) of thw word to delete | ||
135 | * @return the resulting string | ||
136 | */ | ||
137 | //US static QString remword( const QString &text , uint pos ); | ||
138 | |||
139 | /** Removes a matching word from the string, and returns | ||
140 | * a new string. Note that only ONE match is removed. | ||
141 | * @param text the original text | ||
142 | * @param word the word to remove | ||
143 | * @return the resulting string | ||
144 | */ | ||
145 | //US static QString remword( const QString &text , const QString &word ); | ||
146 | |||
147 | /** Capitalizes each word in the string | ||
148 | * "hello there" becomes "Hello There" (string) | ||
149 | * @param text the text to capitalize | ||
150 | * @return the resulting string | ||
151 | */ | ||
152 | //US static QString capwords( const QString &text ); | ||
153 | |||
154 | /** Capitalizes each word in the list | ||
155 | * [hello, there] becomes [Hello, There] (list) | ||
156 | * @param list the list to capitalize | ||
157 | * @return the resulting list | ||
158 | */ | ||
159 | //US static QStringList capwords( const QStringList &list ); | ||
160 | |||
161 | /** Reverses the order of the words in a string | ||
162 | * "hello there" becomes "there hello" (string) | ||
163 | * @param text the text to reverse | ||
164 | * @return the resulting string | ||
165 | */ | ||
166 | //US static QString reverse( const QString &text ); | ||
167 | |||
168 | /** Reverses the order of the words in a list | ||
169 | * [hello, there] becomes [there, hello] (list) | ||
170 | * @param list the list to reverse | ||
171 | * @return the resulting list | ||
172 | */ | ||
173 | //US static QStringList reverse( const QStringList &list ); | ||
174 | |||
175 | /** Left-justifies a string and returns a string at least 'width' characters | ||
176 | * wide. | ||
177 | * If the string is longer than the @p width, the original | ||
178 | * string is returned. It is never truncated. | ||
179 | * @param text the text to justify | ||
180 | * @param width the desired width of the new string | ||
181 | * @return the resulting string | ||
182 | */ | ||
183 | //US static QString ljust( const QString &text , uint width ); | ||
184 | |||
185 | /** Right-justifies a string and returns a string at least 'width' characters | ||
186 | * wide. | ||
187 | * If the string is longer than the @p width, the original | ||
188 | * string is returned. It is never truncated. | ||
189 | * @param text the text to justify | ||
190 | * @param width the desired width of the new string | ||
191 | * @return the resulting string | ||
192 | */ | ||
193 | //US static QString rjust( const QString &text , uint width ); | ||
194 | |||
195 | /** Centers a string and returns a string at least 'width' characters | ||
196 | * wide. | ||
197 | * If the string is longer than the @p width, the original | ||
198 | * string is returned. It is never truncated. | ||
199 | * @param text the text to justify | ||
200 | * @param width the desired width of the new string | ||
201 | * @return the resulting string | ||
202 | */ | ||
203 | //US static QString center( const QString &text , uint width ); | ||
204 | |||
205 | /** Substitute characters at the beginning of a string by "...". | ||
206 | * @param str is the string to modify | ||
207 | * @param maxlen is the maximum length the modified string will have | ||
208 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
209 | * @return the modified string | ||
210 | */ | ||
211 | //US static QString lsqueeze( const QString & str, uint maxlen = 40 ); | ||
212 | |||
213 | /** Substitute characters at the beginning of a string by "...". Similar to | ||
214 | * method above, except that it truncates based on pixel width rather than | ||
215 | * the number of characters | ||
216 | * @param name is the string to modify | ||
217 | * @param fontMetrics is the font metrics to use to calculate character sizes | ||
218 | * @param maxlen is the maximum length in ems the modified string will have | ||
219 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
220 | * @return the modified string | ||
221 | * @since 3.2 | ||
222 | */ | ||
223 | //US static QString lEmSqueeze( const QString & name, | ||
224 | //US const QFontMetrics& fontMetrics, | ||
225 | //US uint maxlen = 30 ); | ||
226 | |||
227 | /** Substitute characters at the beginning of a string by "...". Similar to | ||
228 | * method above, except that maxlen is the width in pixels to truncate to | ||
229 | * @param name is the string to modify | ||
230 | * @param fontMetrics is the font metrics to use to calculate character sizes | ||
231 | * @param maxPixels is the maximum pixel length the modified string will have | ||
232 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
233 | * @return the modified string | ||
234 | * @since 3.2 | ||
235 | */ | ||
236 | //US static QString lPixelSqueeze( const QString & name, | ||
237 | //US const QFontMetrics& fontMetrics, | ||
238 | //US uint maxPixels ); | ||
239 | |||
240 | /** Substitute characters at the middle of a string by "...". | ||
241 | * @param str is the string to modify | ||
242 | * @param maxlen is the maximum length the modified string will have | ||
243 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
244 | * @return the modified string | ||
245 | */ | ||
246 | //US static QString csqueeze( const QString & str, uint maxlen = 40 ); | ||
247 | |||
248 | /** Substitute characters in the middle of a string by "...". Similar to | ||
249 | * method above, except that it truncates based on pixel width rather than | ||
250 | * the number of characters | ||
251 | * @param name is the string to modify | ||
252 | * @param fontMetrics is the font metrics to use to calculate character sizes | ||
253 | * @param maxlen is the maximum length in ems the modified string will have | ||
254 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
255 | * @return the modified string | ||
256 | * @since 3.2 | ||
257 | */ | ||
258 | //US static QString cEmSqueeze( const QString & name, | ||
259 | //US const QFontMetrics& fontMetrics, | ||
260 | //US uint maxlen = 30 ); | ||
261 | |||
262 | /** Substitute characters in the middle of a string by "...". Similar to | ||
263 | * method above, except that maxlen is the width in pixels to truncate to | ||
264 | * @param name is the string to modify | ||
265 | * @param fontMetrics is the font metrics to use to calculate character sizes | ||
266 | * @param maxPixels is the maximum pixel length the modified string will have | ||
267 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
268 | * @return the modified string | ||
269 | * @since 3.2 | ||
270 | */ | ||
271 | //US static QString cPixelSqueeze( const QString & name, | ||
272 | //US const QFontMetrics& fontMetrics, | ||
273 | //US uint maxPixels ); | ||
274 | |||
275 | /** Substitute characters at the end of a string by "...". | ||
276 | * @param str is the string to modify | ||
277 | * @param maxlen is the maximum length the modified string will have | ||
278 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
279 | * @return the modified string | ||
280 | */ | ||
281 | static QString rsqueeze( const QString & str, uint maxlen = 40 ); | ||
282 | |||
283 | /** Substitute characters at the end of a string by "...". Similar to | ||
284 | * method above, except that it truncates based on pixel width rather than | ||
285 | * the number of characters | ||
286 | * @param name is the string to modify | ||
287 | * @param fontMetrics is the font metrics to use to calculate character sizes | ||
288 | * @param maxlen is the maximum length in ems the modified string will have | ||
289 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
290 | * @return the modified string | ||
291 | * @since 3.2 | ||
292 | */ | ||
293 | //US static QString rEmSqueeze( const QString & name, | ||
294 | //US const QFontMetrics& fontMetrics, | ||
295 | //US uint maxlen = 30 ); | ||
296 | |||
297 | /** Substitute characters at the end of a string by "...". Similar to | ||
298 | * method above, except that maxlen is the width in pixels to truncate to | ||
299 | * @param name is the string to modify | ||
300 | * @param fontMetrics is the font metrics to use to calculate character sizes | ||
301 | * @param maxPixels is the maximum pixel length the modified string will have | ||
302 | * If the original string is shorter than "maxlen", it is returned verbatim | ||
303 | * @return the modified string | ||
304 | * @since 3.2 | ||
305 | */ | ||
306 | //US static QString rPixelSqueeze( const QString & name, | ||
307 | //US const QFontMetrics& fontMetrics, | ||
308 | //US uint maxPixels ); | ||
309 | |||
310 | /** | ||
311 | * Match a filename. | ||
312 | * @param filename is the real decoded filename (or dirname | ||
313 | * without trailing '/'). | ||
314 | * @param pattern is a pattern like *.txt, *.tar.gz, Makefile.*, etc. | ||
315 | * Patterns with two asterisks like "*.*pk" are not supported. | ||
316 | * @return true if the given filename matches the given pattern | ||
317 | */ | ||
318 | //US static bool matchFileName( const QString& filename, const QString& pattern ); | ||
319 | |||
320 | /** | ||
321 | * Split a QString into a QStringList in a similar fashion to the static | ||
322 | * QStringList function in Qt, except you can specify a maximum number | ||
323 | * of tokens. If max is specified (!= 0) then only that number of tokens | ||
324 | * will be extracted. The final token will be the remainder of the string. | ||
325 | * | ||
326 | * Example: | ||
327 | * <pre> | ||
328 | * perlSplit("__", "some__string__for__you__here", 4) | ||
329 | * QStringList contains: "some", "string", "for", "you__here" | ||
330 | * </pre> | ||
331 | * | ||
332 | * @param sep is the string to use to delimit s. | ||
333 | * @param s is the input string | ||
334 | * @param max is the maximum number of extractions to perform, or 0. | ||
335 | * @return A QStringList containing tokens extracted from s. | ||
336 | */ | ||
337 | //US static QStringList perlSplit | ||
338 | //US (const QString & sep, const QString & s, uint max = 0); | ||
339 | |||
340 | /** | ||
341 | * Split a QString into a QStringList in a similar fashion to the static | ||
342 | * QStringList function in Qt, except you can specify a maximum number | ||
343 | * of tokens. If max is specified (!= 0) then only that number of tokens | ||
344 | * will be extracted. The final token will be the remainder of the string. | ||
345 | * | ||
346 | * Example: | ||
347 | * <pre> | ||
348 | * perlSplit(' ', "kparts reaches the parts other parts can't", 3) | ||
349 | * QStringList contains: "kparts", "reaches", "the parts other parts can't" | ||
350 | * </pre> | ||
351 | * | ||
352 | * @param sep is the character to use to delimit s. | ||
353 | * @param s is the input string | ||
354 | * @param max is the maximum number of extractions to perform, or 0. | ||
355 | * @return A QStringList containing tokens extracted from s. | ||
356 | */ | ||
357 | //US static QStringList perlSplit | ||
358 | //US (const QChar & sep, const QString & s, uint max = 0); | ||
359 | |||
360 | /** | ||
361 | * Split a QString into a QStringList in a similar fashion to the static | ||
362 | * QStringList function in Qt, except you can specify a maximum number | ||
363 | * of tokens. If max is specified (!= 0) then only that number of tokens | ||
364 | * will be extracted. The final token will be the remainder of the string. | ||
365 | * | ||
366 | * Example: | ||
367 | * <pre> | ||
368 | * perlSplit(QRegExp("[! ]", "Split me up ! I'm bored ! OK ?", 3) | ||
369 | * QStringList contains: "Split", "me", "up ! I'm bored, OK ?" | ||
370 | * </pre> | ||
371 | * | ||
372 | * @param sep is the regular expression to use to delimit s. | ||
373 | * @param s is the input string | ||
374 | * @param max is the maximum number of extractions to perform, or 0. | ||
375 | * @return A QStringList containing tokens extracted from s. | ||
376 | */ | ||
377 | //US static QStringList perlSplit | ||
378 | //US (const QRegExp & sep, const QString & s, uint max = 0); | ||
379 | |||
380 | /** | ||
381 | * This method auto-detects URLs in strings, and adds HTML markup to them | ||
382 | * so that richtext or HTML-enabled widgets (such as KActiveLabel) | ||
383 | * will display the URL correctly. | ||
384 | * @param text the string which may contain URLs | ||
385 | * @return the resulting text | ||
386 | * @since 3.1 | ||
387 | */ | ||
388 | //US static QString tagURLs( const QString& text ); | ||
389 | |||
390 | /** | ||
391 | Obscure string by using a simple symmetric encryption. Applying the | ||
392 | function to a string obscured by this function will result in the original | ||
393 | string. | ||
394 | |||
395 | The function can be used to obscure passwords stored to configuration | ||
396 | files. Note that this won't give you any more security than preventing | ||
397 | that the password is directly copied and pasted. | ||
398 | |||
399 | @param str string to be obscured | ||
400 | @return obscured string | ||
401 | @since 3.2 | ||
402 | */ | ||
403 | static QString obscure( const QString &str ); | ||
404 | |||
405 | #ifdef KDE_NO_COMPAT | ||
406 | private: | ||
407 | #endif | ||
408 | /** | ||
409 | * @deprecated Use @see matchFileName () instead. | ||
410 | */ | ||
411 | /*US static bool matchFilename( const QString& filename, const QString& pattern ) | ||
412 | { | ||
413 | return matchFileName (filename, pattern); | ||
414 | }; | ||
415 | */ | ||
416 | }; | ||
417 | #endif | ||