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

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