KTextTemplate

safestring.h
1/*
2 This file is part of the KTextTemplate library
3
4 SPDX-FileCopyrightText: 2009, 2010 Stephen Kelly <steveire@gmail.com>
5
6 SPDX-License-Identifier: LGPL-2.1-or-later
7
8*/
9
10#ifndef KTEXTTEMPLATE_SAFESTRING_H
11#define KTEXTTEMPLATE_SAFESTRING_H
12
13#include "ktexttemplate_export.h"
14
15#include <QString>
16#include <QVariant>
17
18namespace KTextTemplate
19{
20
21/// @headerfile safestring.h <KTextTemplate/SafeString>
22
23/**
24 @brief A QString wrapper class for containing whether a string is safe or
25 needs to be escaped.
26
27 This allows lazy escaping of strings. Otherwise a string may be escaped
28 multiple times where it should only be escaped once.
29
30 The **%SafeString** class itself provides information about whether a string
31 is safe from further escaping through the @ref isSafe method. The actual
32 string content held by the **%SafeString** instance is available through the
33 @ref get method. The @ref get method returns a QString subclass which should
34 be used like any other QString. The difference is that all methods on
35 NestedString return a **%SafeString** instead of a QString.
36
37 @code
38 SafeString s("this & that", SafeString::IsSafe);
39 s.get().replace( "this", "these" ).toUpper();
40
41 qDebug() << s.get() << s.isSafe(); // outputs "these & that" false
42 @endcode
43
44 Note that most operations on strings make the string unsafe. For example,
45 while <tt>"K &amp; R"</tt> is safe, using replace("m", "n") will result in
46 <tt>"K &anp; R"</tt>, which is unsafe. Likewise using upper() will return
47 <tt>"K &AMP; R"</tt>, which is unsafe. Because the **%SafeString** can not
48 determine whether a method call with particular arguments will change
49 a **%SafeString** from being safe to being unsafe, any operation which can
50 possibly make the string unsafe does cause the string to become unsafe. It is
51 then up to the caller to restore safe-ness if needed.
52
53 NestedString has overloads for SafeStrings whereever appropriate so that
54 strings remain marked as safe where possible.
55
56 For example:
57
58 @code
59 SafeString s1("this & that", SafeString::IsSafe);
60 s2 = s1;
61 s1.append( QString( " & the other" ) );
62 // s1 is now "this & that & the other" and is unsafe.
63
64 SafeString s3(" Wobl & Bob", SafeString::IsSafe);
65 s2.append(s3);
66 // Both s2 and s3 are safe, and append is a safe operation, so s2
67 // is still safe
68 @endcode
69
70 @see @ref autoescaping
71 @see OutputStream::escape
72
73 The **%SafeString** class has appropriate operator overloads to make it
74 convenient to use in methods returning a QVariant, such as Filter::doFilter,
75 or as a QString. Note that a raw QString is essentially the same
76 as a **%SafeString** which is marked as unsafe.
77
78 @author Stephen Kelly <steveire@gmail.com>
79*/
80class KTEXTTEMPLATE_EXPORT SafeString
81{
82public:
83 /**
84 Possible safety states of a **%SafeString**
85 */
86 enum Safety {
87 IsSafe, ///< The string is safe and requires no further escaping
88 IsNotSafe ///< The string is not safe. It will be escaped before being
89 /// added to the output of rendering.
90 };
91
92 /**
93 Constructs an empty **%SafeString**.
94 */
95 SafeString();
96
97 /**
98 Copy constructor
99 */
100 SafeString(const SafeString &safeString);
101
102 /**
103 Constructs a **%SafeString** with the content @p str whose safety is given
104 by @p safe.
105 */
106 SafeString(const QString &str, bool safe);
107
108 /**
109 Constructs a **%SafeString** with the content @p str whose safety is given
110 by @p safety.
111 */
112 /* implicit */ SafeString(const QString &str,
113 Safety safety = IsNotSafe); // krazy:exclude=explicit
114
115 /**
116 Destructor
117 */
119
120#ifndef K_DOXYGEN
121 /**
122 Set whether the string should be escaped.
123 */
124 void setNeedsEscape(bool needsEscape);
125#endif
126
127 /**
128 Whether the string needs to be escaped.
129 */
130 bool needsEscape() const;
131
132 /**
133 Whether the string is safe.
134 */
135 bool isSafe() const;
136
137#ifndef K_DOXYGEN
138 /**
139 Set whether the string is safe.
140 */
141 void setSafety(Safety safety);
142#endif
143
144 /**
145 @brief The NestedString is a QString whose methods always return a
146 SafeString
147
148 This class is largely an implementation detail. See the SafeString
149 documentation for details.
150 */
151 class KTEXTTEMPLATE_EXPORT NestedString : public QString
152 {
153#ifndef K_DOXYGEN
154 friend class SafeString;
155 SafeString *m_safeString;
156
157 public:
158 explicit NestedString(SafeString *safeString);
159 NestedString(const QString &content, SafeString *safeString);
160
161 SafeString &append(const SafeString &str);
162 SafeString &append(const QString &str);
163 SafeString &append(const QLatin1String &str);
164#ifndef QT_NO_CAST_FROM_ASCII
165 SafeString &append(const QByteArray &ba)
166 {
167 QString::append(ba);
168 m_safeString->m_safety = IsNotSafe;
169 return *m_safeString;
170 }
171
172 SafeString &append(const char *str)
173 {
174 QString::append(str);
175 m_safeString->m_safety = IsNotSafe;
176 return *m_safeString;
177 }
178#endif
179 SafeString &append(const QChar ch);
180
181 SafeString &fill(QChar ch, int size = -1);
182
183 SafeString &insert(int position, const SafeString &str);
184 SafeString &insert(int position, const QString &str);
185 SafeString &insert(int position, const QLatin1String &str);
186 SafeString &insert(int position, const QChar *unicode, int size);
187 SafeString &insert(int position, QChar ch);
188
189 SafeString left(int n) const;
190 SafeString leftJustified(int width, QChar fill = QLatin1Char(' '), bool truncate = {}) const;
191 SafeString mid(int position, int n = -1) const;
192
193 SafeString normalized(NormalizationForm mode) const;
194 SafeString normalized(NormalizationForm mode, QChar::UnicodeVersion version) const;
195
196 SafeString &prepend(const SafeString &str);
197 SafeString &prepend(const QString &str);
198 SafeString &prepend(const QLatin1String &str);
199#ifndef QT_NO_CAST_FROM_ASCII
200 SafeString &prepend(const QByteArray &ba)
201 {
203 m_safeString->m_safety = IsNotSafe;
204 return *m_safeString;
205 }
206
207 SafeString &prepend(const char *str)
208 {
209 QString::prepend(str);
210 m_safeString->m_safety = IsNotSafe;
211 return *m_safeString;
212 }
213#endif
214 SafeString &prepend(QChar ch);
215
216 void push_back(const SafeString &other);
217 void push_front(const SafeString &other);
218
219 SafeString &remove(int position, int n);
223 SafeString &remove(const QRegularExpression &rx);
224 SafeString repeated(int times) const;
225 SafeString &replace(int position, int n, const SafeString &after);
226 SafeString &replace(int position, int n, const QString &after);
227 SafeString &replace(int position, int n, const QChar *unicode, int size);
228 SafeString &replace(int position, int n, QChar after);
229 SafeString &replace(const SafeString &before, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
230 SafeString &replace(const QString &before, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
231 SafeString &replace(const SafeString &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
232 SafeString &replace(const QString &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
233 SafeString &replace(const QChar *before, int blen, const QChar *after, int alen, Qt::CaseSensitivity cs = Qt::CaseSensitive);
234 SafeString &replace(QChar ch, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
235 SafeString &replace(QChar ch, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
236 SafeString &replace(QChar before, QChar after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
237 SafeString &replace(const QLatin1String &before, const QLatin1String &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
238 SafeString &replace(const QLatin1String &before, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
239 SafeString &replace(const QLatin1String &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
240 SafeString &replace(const SafeString &before, const QLatin1String &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
241 SafeString &replace(const QString &before, const QLatin1String &after, Qt::CaseSensitivity cs = Qt::CaseSensitive);
243 SafeString &replace(const QRegularExpression &rx, const SafeString &after);
244 SafeString &replace(const QRegularExpression &rx, const QString &after);
245
246 SafeString right(int n) const;
247 SafeString rightJustified(int width, QChar fill = QLatin1Char(' '), bool truncate = {}) const;
248
249 SafeString section(QChar sep, int start, int end = -1, SectionFlags flags = SectionDefault) const;
250 SafeString section(const SafeString &sep, int start, int end = -1, SectionFlags flags = SectionDefault) const;
251 SafeString section(const QString &sep, int start, int end = -1, SectionFlags flags = SectionDefault) const;
252 SafeString section(const QRegularExpression &reg, int start, int end = -1, SectionFlags flags = SectionDefault) const;
253 SafeString &setNum(int n, int base = 10);
254 SafeString &setNum(uint n, int base = 10);
255 SafeString &setNum(long n, int base = 10);
256 SafeString &setNum(ulong n, int base = 10);
257 SafeString &setNum(qlonglong n, int base = 10);
258 SafeString &setNum(qulonglong n, int base = 10);
259 SafeString &setNum(short n, int base = 10);
260 SafeString &setNum(ushort n, int base = 10);
261 SafeString &setNum(double n, char format = 'g', int precision = 6);
262 SafeString &setNum(float n, char format = 'g', int precision = 6);
263 SafeString &setUnicode(const QChar *unicode, int size);
264 SafeString &setUtf16(const ushort *unicode, int size);
265 SafeString simplified() const;
266
270 QStringList split(const QRegularExpression &rx, Qt::SplitBehavior behavior = Qt::KeepEmptyParts) const;
271
272 SafeString toLower() const;
273 SafeString toUpper() const;
274 SafeString trimmed() const;
275
276 void chop(int n);
277#endif
278 };
279
280 /**
281 Returns the String held by this **%SafeString**
282 */
283 const NestedString &get() const
284 {
285 return m_nestedString;
286 }
287
288 /**
289 Returns the String held by this **%SafeString**
290 */
292 {
293 return m_nestedString;
294 }
295
296 /**
297 Convenience operator for treating a **%SafeString** like a QString.
298 */
299 operator QString() const
300 {
301 return m_nestedString;
302 }
303
304 /**
305 Assignment operator.
306 */
307 SafeString &operator=(const SafeString &str);
308
309 /**
310 Returns a concatenation of this with @p str.
311
312 The result is not safe because str is not safe.
313 */
314 SafeString operator+(const QString &str);
315
316 /**
317 Returns a concatenation of this with @p str.
318
319 The result is safe if both this and str are safe.
320 */
321 SafeString operator+(const SafeString &str);
322
323 /**
324 Appends the content of @p str to this.
325
326 The result is not safe because @p str is not safe.
327 */
328 SafeString &operator+=(const QString &str);
329
330 /**
331 Appends the content of @p str to this.
332
333 The result is safe if both this and @p str are safe.
334 */
335 SafeString &operator+=(const SafeString &str);
336
337 /**
338 Returns true if the content of @p other matches the content of this.
339
340 Safeness and needing escaping are not accounted for in the comparison.
341 */
342 bool operator==(const SafeString &other) const;
343
344 /**
345 Returns true if the content of @p other matches the content of this.
346
347 Safeness and needing escaping are not accounted for in the comparison.
348 */
349 bool operator==(const QString &other) const;
350
351 /**
352 Convenience operator for storing a **%SafeString** in a QVariant.
353 */
354 operator QVariant() const
355 {
356 return QVariant::fromValue(*this);
357 }
358
359private:
360#ifndef K_DOXYGEN
361 NestedString m_nestedString;
362#endif
363 Safety m_safety;
364 bool m_needsescape;
365};
366}
367
368Q_DECLARE_METATYPE(KTextTemplate::SafeString)
369
370#endif
The NestedString is a QString whose methods always return a SafeString.
Definition safestring.h:152
A QString wrapper class for containing whether a string is safe or needs to be escaped.
Definition safestring.h:81
NestedString & get()
Returns the String held by this SafeString
Definition safestring.h:291
Safety
Possible safety states of a SafeString
Definition safestring.h:86
@ IsSafe
The string is safe and requires no further escaping.
Definition safestring.h:87
const NestedString & get() const
Returns the String held by this SafeString
Definition safestring.h:283
Q_SCRIPTABLE Q_NOREPLY void start()
The KTextTemplate namespace holds all public KTextTemplate API.
Definition Mainpage.dox:8
UnicodeVersion
QString & append(QChar ch)
QString & prepend(QChar ch)
CaseSensitivity
typedef SplitBehavior
QVariant fromValue(T &&value)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:59:16 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.