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

source code of kcoreaddons/src/lib/text/kstringhandler.h