2
This file is part of the Grantlee template system.
4
Copyright (c) 2009,2010 Stephen Kelly <steveire@gmail.com>
6
This library is free software; you can redistribute it and/or
7
modify it under the terms of the GNU Lesser General Public
8
License as published by the Free Software Foundation; either version
9
2.1 of the Licence, or (at your option) any later version.
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
Lesser General Public License for more details.
16
You should have received a copy of the GNU Lesser General Public
17
License along with this library. If not, see <http://www.gnu.org/licenses/>.
21
#ifndef GRANTLEE_SAFESTRING_H
22
#define GRANTLEE_SAFESTRING_H
24
#include "grantlee_core_export.h"
26
#include <QtCore/QString>
27
#include <QtCore/QVariant>
32
/// @headerfile safestring.h grantlee/safestring.h
35
@brief A QString wrapper class for containing whether a string is safe or needs to be escaped.
37
This allows lazy escaping of strings. Otherwise a string may be escaped multiple times where it
38
should only be escaped once.
40
The SafeString class itself provides information about whether a string is safe from further escaping through the isSafe method. The actual string content held by the SafeString instance is available through the get() method. The get() method returns a QString subclass which should be used like any other QString. The difference is that all methods on NestedString return a SafeString instead of a QString.
43
SafeString s("this & that", SafeString::IsSafe);
44
s.get().replace( "this", "these" ).toUpper();
46
qDebug() << s.get() << s.isSafe(); // outputs "these & that" false
49
Note that most operations on strings make the string unsafe. For example, while <tt>"K & R"</tt> is safe, using replace("m", "n") will result in <tt>"K &anp; R"</tt>, which is unsafe. Likewise using upper() will return <tt>"K & R"</tt>, which is unsafe. Because the SafeString can not determine whether a method call with particular arguments will change a SafeString from being safe to being unsafe, any operation which can possibly make the string unsafe does cause the string to become unsafe. It is then up to the caller to restore safe-ness if needed.
51
NestedString has overloads for SafeStrings whereever appropriate so that strings remain marked as safe where possible.
56
SafeString s1("this & that", SafeString::IsSafe);
58
s1.append( QString( " & the other" ) );
59
// s1 is now "this & that & the other" and is unsafe.
61
SafeString s3(" Wobl & Bob", SafeString::IsSafe);
63
// Both s2 and s3 are safe, and append is a safe operation, so s2 is still safe
66
@see @ref autoescaping
67
@see OutputStream::escape
69
SafeString has appropriate operator overloads to make it convenient to use in methods returning a QVariant, such as Filter::doFilter, or as a QString. Note that a raw QString is essentially the same as a SafeString which is marked as unsafe.
71
@author Stephen Kelly <steveire@gmail.com>
73
class GRANTLEE_CORE_EXPORT SafeString
77
Possible safety states of a SafeString
80
IsSafe, ///< The string is safe and requires no further escaping
81
IsNotSafe ///< The string is not safe. It will be escaped before being added to the output of rendering.
85
Constructs an empty SafeString.
92
SafeString( const SafeString &safeString );
95
Constructs a SafeString with the content @p str whose safety is given by @p safe.
97
SafeString( const QString &str, bool safe );
100
Constructs a SafeString with the content @p str whose safety is given by @p safety.
102
/* implicit */ SafeString( const QString &str, Safety safety = IsNotSafe ); // krazy:exclude=explicit
111
Set whether the string should be escaped.
113
void setNeedsEscape( bool needsEscape );
117
Whether the string needs to be escaped.
119
bool needsEscape() const;
122
Whether the string is safe.
128
Set whether the string is safe.
130
void setSafety( Safety safety );
134
@brief The NestedString is a QString whose methods always return a SafeString
136
This class is largely an implementation detail. See the SafeString documentation for details.
138
class GRANTLEE_CORE_EXPORT NestedString : public QString
141
friend class SafeString;
142
SafeString *m_safeString;
144
NestedString( SafeString *safeString );
145
NestedString( const QString &content, SafeString *safeString );
147
SafeString& append( const SafeString &str );
148
SafeString& append( const QString &str );
149
SafeString& append( const QStringRef &reference );
150
SafeString& append( const QLatin1String &str );
151
// BIC: Use QT_NO_CAST_FROM_ASCII instead.
152
#ifndef GRANTLEE_NO_CAST_FROM_ASCII
153
SafeString& append( const QByteArray &ba );
154
SafeString& append( const char *str );
156
SafeString& append( const QChar ch );
158
SafeString& fill( QChar ch, int size = -1 );
160
SafeString& insert( int position, const SafeString &str );
161
SafeString& insert( int position, const QString &str );
162
SafeString& insert( int position, const QLatin1String &str );
163
SafeString& insert( int position, const QChar *unicode, int size );
164
SafeString& insert( int position, QChar ch );
166
SafeString left( int n ) const;
167
SafeString leftJustified( int width, QChar fill = QLatin1Char( ' ' ), bool truncate = false ) const;
168
SafeString mid( int position, int n = -1 ) const;
170
SafeString normalized( NormalizationForm mode ) const;
171
SafeString normalized( NormalizationForm mode, QChar::UnicodeVersion version ) const;
173
SafeString& prepend( const SafeString &str );
174
SafeString& prepend( const QString &str );
175
SafeString& prepend( const QLatin1String &str );
176
#ifndef GRANTLEE_NO_CAST_FROM_ASCII
177
SafeString& prepend( const QByteArray &ba );
178
SafeString& prepend( const char *str );
180
SafeString& prepend( QChar ch );
182
void push_back( const SafeString& other );
183
void push_front( const SafeString& other );
185
SafeString& remove( int position, int n );
186
SafeString& remove( QChar ch, Qt::CaseSensitivity cs = Qt::CaseSensitive );
187
SafeString& remove( const SafeString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive );
188
SafeString& remove( const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive );
189
SafeString& remove( const QRegExp &rx );
190
SafeString repeated( int times ) const;
191
SafeString& replace( int position, int n, const SafeString &after );
192
SafeString& replace( int position, int n, const QString &after );
193
SafeString& replace( int position, int n, const QChar *unicode, int size );
194
SafeString& replace( int position, int n, QChar after );
195
SafeString& replace( const SafeString &before, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
196
SafeString& replace( const QString &before, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
197
SafeString& replace( const SafeString &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
198
SafeString& replace( const QString &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
199
SafeString& replace( const QChar *before, int blen, const QChar *after, int alen, Qt::CaseSensitivity cs = Qt::CaseSensitive );
200
SafeString& replace( QChar ch, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
201
SafeString& replace( QChar ch, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
202
SafeString& replace( QChar before, QChar after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
203
SafeString& replace( const QLatin1String &before, const QLatin1String &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
204
SafeString& replace( const QLatin1String &before, const SafeString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
205
SafeString& replace( const QLatin1String &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
206
SafeString& replace( const SafeString &before, const QLatin1String &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
207
SafeString& replace( const QString &before, const QLatin1String &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
208
SafeString& replace( QChar c, const QLatin1String &after, Qt::CaseSensitivity cs = Qt::CaseSensitive );
209
SafeString& replace( const QRegExp &rx, const SafeString &after );
210
SafeString& replace( const QRegExp &rx, const QString &after );
212
SafeString right( int n ) const;
213
SafeString rightJustified( int width, QChar fill = QLatin1Char( ' ' ), bool truncate = false ) const;
215
SafeString section( QChar sep, int start, int end = -1, SectionFlags flags = SectionDefault ) const;
216
SafeString section( const SafeString& sep, int start, int end = -1, SectionFlags flags = SectionDefault ) const;
217
SafeString section( const QString& sep, int start, int end = -1, SectionFlags flags = SectionDefault ) const;
218
SafeString section( const QRegExp& reg, int start, int end = -1, SectionFlags flags = SectionDefault ) const;
219
SafeString& setNum( int n, int base = 10 );
220
SafeString& setNum( uint n, int base = 10 );
221
SafeString& setNum( long n, int base = 10 );
222
SafeString& setNum( ulong n, int base = 10 );
223
SafeString& setNum( qlonglong n, int base = 10 );
224
SafeString& setNum( qulonglong n, int base = 10 );
225
SafeString& setNum( short n, int base = 10 );
226
SafeString& setNum( ushort n, int base = 10 );
227
SafeString& setNum( double n, char format = 'g', int precision = 6 );
228
SafeString& setNum( float n, char format = 'g', int precision = 6 );
229
SafeString& setUnicode( const QChar * unicode, int size );
230
SafeString& setUtf16( const ushort * unicode, int size );
231
SafeString simplified() const;
233
QStringList split( const SafeString& sep, SplitBehavior behavior = KeepEmptyParts, Qt::CaseSensitivity cs = Qt::CaseSensitive ) const;
234
QStringList split( const QString& sep, SplitBehavior behavior = KeepEmptyParts, Qt::CaseSensitivity cs = Qt::CaseSensitive ) const;
235
QStringList split( const QChar & sep, SplitBehavior behavior = KeepEmptyParts, Qt::CaseSensitivity cs = Qt::CaseSensitive ) const;
236
QStringList split( const QRegExp & rx, SplitBehavior behavior = KeepEmptyParts ) const;
238
SafeString toLower() const;
239
SafeString toUpper() const;
240
SafeString trimmed() const;
247
Returns the String held by this SafeString
249
const NestedString& get() const {
250
return m_nestedString;
254
Returns the String held by this SafeString
256
NestedString& get() {
257
return m_nestedString;
261
Convenience operator for treating a SafeString like a QString.
263
operator QString() const {
264
return m_nestedString;
270
SafeString &operator=( const SafeString &str );
273
Returns a concatenation of this with @p str.
275
The result is not safe because str is not safe.
277
SafeString operator+( const QString &str );
280
Returns a concatenation of this with @p str.
282
The result is safe if both this and str are safe.
284
SafeString operator+( const SafeString &str );
287
Appends the content of @p str to this.
289
The result is not safe because @p str is not safe.
291
SafeString &operator+=( const QString &str );
294
Appends the content of @p str to this.
296
The result is safe if both this and @p str are safe.
298
SafeString &operator+=( const SafeString &str );
301
Returns true if the content of @p other matches the content of this.
303
Safeness and needing escaping are not accounted for in the comparison.
305
bool operator==( const SafeString &other ) const;
308
Returns true if the content of @p other matches the content of this.
310
Safeness and needing escaping are not accounted for in the comparison.
312
bool operator==( const QString &other ) const;
315
Convenience operator for storing a SafeString in a QVariant.
317
operator QVariant() const {
318
return QVariant::fromValue( *this );
323
NestedString m_nestedString;
331
Q_DECLARE_METATYPE( Grantlee::SafeString )