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
28class QChar;
29class QRegExp;
30class QString;
31class 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 */
59namespace 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