summaryrefslogtreecommitdiffstats
path: root/kdecore/kstringhandler.h
blob: 47075a0663e8ce779b3089326b419d8287591322 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
/* This file is part of the KDE libraries
   Copyright (C) 1999 Ian Zepp (icszepp@islc.net)
   Copyright (C) 2000 Rik Hemsley (rikkus) <rik@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/
#ifndef KSTRINGHANDLER_H
#define KSTRINGHANDLER_H

#include <tqstring.h>
#include <tqstringlist.h>
#include <tqregexp.h>            // for the word ranges
#include <tqfontmetrics.h>
#include "kdelibs_export.h"

/**
 * This class contains utility functions for handling strings.
 *
 * This class is @em not a substitute for the TQString class. What
 * I tried to do with this class is provide an easy way to
 * cut/slice/splice words inside sentences in whatever order desired.
 * While the main focus of this class are words (ie characters
 * separated by spaces/tabs), the two core functions here ( split()
 * and join() ) will function given any char to use as a separator.
 * This will make it easy to redefine what a 'word' means in the
 * future if needed.
 *
 * I freely stole some of the function names from python. I also think
 * some of these were influenced by mIRC (yes, believe it if you will, I
 * used to write a LOT of scripts in mIRC).
 *
 * The ranges are a fairly powerful way of getting/stripping words from
 * a string. These ranges function, for the large part, as they would in
 * python. See the word(const TQString&, const char *) and remword(const TQString&, uint) functions for more detail.
 *
 * This class contains no data members of its own. All strings are cut
 * on the fly and returned as new qstrings/qstringlists.
 *
 * Quick example on how to use:
 *
 * \code
 * KStringHandler kstr;
 * TQString line = "This is a test of the strings";
 *
 * cout << "1> " << kstr.word( line , "4:" ) << "\n";
 * cout << "2> " << kstr.remrange( line , "2:5" ) << "\n";
 * cout << "2> " << kstr.reverse( line ) << "\n";
 * cout << "2> " << kstr.center( kstr.word( line , 4 ) , 15 ) << "\n";
 * \endcode
 *
 * and so forth.
 *
 * @short Class for manipulating words and sentences in strings
 * @author Ian Zepp <icszepp@islc.net>
 * @see KShell
 */
class KDECORE_EXPORT KStringHandler
{
public:
    /** Returns the nth word in the string if found
      * Returns a EMPTY (not null) string otherwise.
      * Note that the FIRST index is 0.
      * @param text the string to search for the words
      * @param pos the position of the word to search
      * @return the word, or an empty string if not found
      * @deprecated use TQString::section instead
      */
    static TQString        word( const TQString &text , uint pos ) KDE_DEPRECATED;

    /** Returns a range of words from that string.
      * Ie:
      * @li "0" returns the very first word
      * @li "0:" returns the first to the last word
      * @li "0:3" returns the first to fourth words
      * @li ":3" returns everything up to the fourth word
      *
      * If you grok python, you're set.
      * @param text the string to search for the words
      * @param range the words to return (see description)
      * @return the words, or an empty string if not found
      */
    static TQString        word( const TQString &text , const char *range );

    /** Inserts a word into the string, and returns
      * a new string with the word included. the first
      * index is zero (0). If there are not @p pos words in the original
      * string, the new word will be appended to the end.
      * @param text the original text
      * @param word the word to insert
      * @param pos the position (in words) for the new word
      * @return the resulting string
      */
    static TQString        insword( const TQString &text , const TQString &word , uint pos );

    /** Replaces a word in the string, and returns
      * a new string with the word included. the first
      * index is zero (0). If there are not @p pos words in the original
      * string, the new word will be appended to the end.
      * @param text the original text
      * @param word the word to insert
      * @param pos the position (in words) for the new word
      * @return the resulting string
      */
    static TQString        setword( const TQString &text , const TQString &word , uint pos );

    /** Removes a word or ranges of words from the string,
      * and returns a new string. The ranges definitions
      * follow the definitions for the word() function.
      *
      * @li "0"        removes the very first word
      * @li "0:"    removes the first the the last word
      * @li "0:3"    removes the first to fourth words
      * @li ":3"    removes everything up to the fourth word
      * @param text the original text
      * @param range the words to remove (see description)
      * @return the resulting string
      */
    static TQString        remrange( const TQString &text , const char *range );


    /** Removes a word at the given index, and returns a
      * new string. The first index is zero (0).
      * @param text the original text
      * @param pos the position (in words) of thw word to delete
      * @return the resulting string
      */
    static TQString        remword( const TQString &text , uint pos );

    /** Removes a matching word from the string, and returns
      * a new string. Note that only ONE match is removed.
      * @param text the original text
      * @param word the word to remove
      * @return the resulting string
      */
    static TQString        remword( const TQString &text , const TQString &word );

    /** Capitalizes each word in the string
      * "hello there" becomes "Hello There"        (string)
      * @param text the text to capitalize
      * @return the resulting string
      */
    static TQString        capwords( const TQString &text );

    /** Capitalizes each word in the list
      * [hello, there] becomes [Hello, There]    (list)
      * @param list the list to capitalize
      * @return the resulting list
      */
    static TQStringList    capwords( const TQStringList &list );

    /** Reverses the order of the words in a string
      * "hello there" becomes "there hello"        (string)
      * @param text the text to reverse
      * @return the resulting string
      */
    static TQString        reverse( const TQString &text );

    /** Reverses the order of the words in a list
      * [hello, there] becomes [there, hello]    (list)
      * @param list the list to reverse
      * @return the resulting list
      */
    static TQStringList    reverse( const TQStringList &list );

    /** Left-justifies a string and returns a string at least 'width' characters
      * wide.
      * If the string is longer than the @p width, the original
      * string is returned. It is never truncated.
      * @param text the text to justify
      * @param width the desired width of the new string
      * @return the resulting string
      * @deprecated use TQString::leftJustify instead
      */
    static TQString        ljust( const TQString &text , uint width ) KDE_DEPRECATED;

    /** Right-justifies a string and returns a string at least 'width' characters
      * wide.
      * If the string is longer than the @p width, the original
      * string is returned. It is never truncated.
      * @param text the text to justify
      * @param width the desired width of the new string
      * @return the resulting string
      * @deprecated use TQString::rightJustify instead
      */
    static TQString        rjust( const TQString &text , uint width ) KDE_DEPRECATED;

    /** Centers a string and returns a string at least 'width' characters
      * wide.
      * If the string is longer than the @p width, the original
      * string is returned. It is never truncated.
      * @param text the text to justify
      * @param width the desired width of the new string
      * @return the resulting string
      */
    static TQString        center( const TQString &text , uint width );

    /** Substitute characters at the beginning of a string by "...".
     * @param str is the string to modify
     * @param maxlen is the maximum length the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     */
    static TQString        lsqueeze( const TQString & str, uint maxlen = 40 );

    /** Substitute characters at the beginning of a string by "...". Similar to
     * method above, except that it truncates based on pixel width rather than
     * the number of characters
     * @param name is the string to modify
     * @param fontMetrics is the font metrics to use to calculate character sizes
     * @param maxlen is the maximum length in ems the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     * @since 3.2
     */
    static TQString lEmSqueeze( const TQString & name,
                               const TQFontMetrics& fontMetrics,
                               uint maxlen = 30 );

    /** Substitute characters at the beginning of a string by "...". Similar to
     * method above, except that maxlen is the width in pixels to truncate to
     * @param name is the string to modify
     * @param fontMetrics is the font metrics to use to calculate character sizes
     * @param maxPixels is the maximum pixel length the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     * @since 3.2
     */
    static TQString lPixelSqueeze( const TQString & name,
                                  const TQFontMetrics& fontMetrics,
                                  uint maxPixels );

    /** Substitute characters at the middle of a string by "...".
     * @param str is the string to modify
     * @param maxlen is the maximum length the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     */
    static TQString        csqueeze( const TQString & str, uint maxlen = 40 );

    /** Substitute characters in the middle of a string by "...". Similar to
     * method above, except that it truncates based on pixel width rather than
     * the number of characters
     * @param name is the string to modify
     * @param fontMetrics is the font metrics to use to calculate character sizes
     * @param maxlen is the maximum length in ems the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     * @since 3.2
     */
    static TQString cEmSqueeze( const TQString & name,
                               const TQFontMetrics& fontMetrics,
                               uint maxlen = 30 );

    /** Substitute characters in the middle of a string by "...". Similar to
     * method above, except that maxlen is the width in pixels to truncate to
     * @param name is the string to modify
     * @param fontMetrics is the font metrics to use to calculate character sizes
     * @param maxPixels is the maximum pixel length the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     * @since 3.2
     */
    static TQString cPixelSqueeze( const TQString & name,
                                  const TQFontMetrics& fontMetrics,
                                  uint maxPixels );

    /** Substitute characters at the end of a string by "...".
     * @param str is the string to modify
     * @param maxlen is the maximum length the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     */
    static TQString        rsqueeze( const TQString & str, uint maxlen = 40 );

    /** Substitute characters at the end of a string by "...". Similar to
     * method above, except that it truncates based on pixel width rather than
     * the number of characters
     * @param name is the string to modify
     * @param fontMetrics is the font metrics to use to calculate character sizes
     * @param maxlen is the maximum length in ems the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     * @since 3.2
     */
    static TQString rEmSqueeze( const TQString & name,
                               const TQFontMetrics& fontMetrics,
                               uint maxlen = 30 );

    /** Substitute characters at the end of a string by "...". Similar to
     * method above, except that maxlen is the width in pixels to truncate to
     * @param name is the string to modify
     * @param fontMetrics is the font metrics to use to calculate character sizes
     * @param maxPixels is the maximum pixel length the modified string will have
     * If the original string is shorter than "maxlen", it is returned verbatim
     * @return the modified string
     * @since 3.2
     */
    static TQString rPixelSqueeze( const TQString & name,
                                  const TQFontMetrics& fontMetrics,
                                  uint maxPixels );

    /**
     * Match a filename.
     * @param filename is the real decoded filename (or dirname
     *        without trailing '/').
     * @param pattern is a pattern like *.txt, *.tar.gz, Makefile.*, *README*, etc.
     * Patterns with two asterisks like "*.*pk" are not supported.
     * @return true if the given filename matches the given pattern
     */
    static bool matchFileName( const TQString& filename, const TQString& pattern );
    // KDE4: move to KShell

    /**
     * Split a TQString into a TQStringList in a similar fashion to the static
     * TQStringList function in Qt, except you can specify a maximum number
     * of tokens. If max is specified (!= 0) then only that number of tokens
     * will be extracted. The final token will be the remainder of the string.
     *
     * Example:
     * \code
     * perlSplit("__", "some__string__for__you__here", 4)
     * TQStringList contains: "some", "string", "for", "you__here"
     * \endcode
     *
     * @param sep is the string to use to delimit s.
     * @param s is the input string
     * @param max is the maximum number of extractions to perform, or 0.
     * @return A TQStringList containing tokens extracted from s.
     */
    static TQStringList perlSplit
      (const TQString & sep, const TQString & s, uint max = 0);

    /**
     * Split a TQString into a TQStringList in a similar fashion to the static
     * TQStringList function in Qt, except you can specify a maximum number
     * of tokens. If max is specified (!= 0) then only that number of tokens
     * will be extracted. The final token will be the remainder of the string.
     *
     * Example:
     * \code
     * perlSplit(' ', "kparts reaches the parts other parts can't", 3)
     * TQStringList contains: "kparts", "reaches", "the parts other parts can't"
     * \endcode
     *
     * @param sep is the character to use to delimit s.
     * @param s is the input string
     * @param max is the maximum number of extractions to perform, or 0.
     * @return A TQStringList containing tokens extracted from s.
     */
    static TQStringList perlSplit
      (const TQChar & sep, const TQString & s, uint max = 0);

    /**
     * Split a TQString into a TQStringList in a similar fashion to the static
     * TQStringList function in Qt, except you can specify a maximum number
     * of tokens. If max is specified (!= 0) then only that number of tokens
     * will be extracted. The final token will be the remainder of the string.
     *
     * Example:
     * \code
     * perlSplit(TQRegExp("[! ]", "Split me up ! I'm bored ! OK ?", 3)
     * TQStringList contains: "Split", "me", "up ! I'm bored, OK ?"
     * \endcode
     *
     * @param sep is the regular expression to use to delimit s.
     * @param s is the input string
     * @param max is the maximum number of extractions to perform, or 0.
     * @return A TQStringList containing tokens extracted from s.
     */
    static TQStringList perlSplit
      (const TQRegExp & sep, const TQString & s, uint max = 0);

    /**
     * This method auto-detects URLs in strings, and adds HTML markup to them
     * so that richtext or HTML-enabled widgets (such as KActiveLabel)
     * will display the URL correctly.
     * @param text the string which may contain URLs
     * @return the resulting text
     * @since 3.1
     */
    static TQString tagURLs( const TQString& text );

    /**
      Obscure string by using a simple symmetric encryption. Applying the
      function to a string obscured by this function will result in the original
      string.

      The function can be used to obscure passwords stored to configuration
      files. Note that this won't give you any more security than preventing
      that the password is directly copied and pasted.

      @param str string to be obscured
      @return obscured string
      @since 3.2
    */
    static TQString obscure( const TQString &str );

    /**
      Guess whether a string is UTF8 encoded.

      @param str the string to check
      @return true if UTF8. If false, the string is probably in Local8Bit.
      @since 3.2
     */
    static bool isUtf8( const char *str );

    /**
      Construct TQString from a c string, guessing whether it is UTF8- or
      Local8Bit-encoded.

      @param str the input string
      @return the (hopefully correctly guessed) TQString representation of @p str
      @since 3.2
     */
    static TQString from8Bit( const char *str );

#ifdef KDE_NO_COMPAT
private:
#endif
    /**
     * @deprecated Use matchFileName () instead.
     */
    static KDE_DEPRECATED bool matchFilename( const TQString& filename, const TQString& pattern )
    {
        return matchFileName (filename, pattern);
    }

};
#endif