KTextTemplate::SafeString Class Reference

#include <KTextTemplate/SafeString>

Classes
class	NestedString

Public Types
enum	Safety { IsSafe , IsNotSafe }

Public Member Functions
	SafeString ()
	SafeString (const QString &str, bool safe)
	SafeString (const QString &str, Safety safety=IsNotSafe)
	SafeString (const SafeString &safeString)
	~SafeString ()
NestedString &	get ()
const NestedString &	get () const
bool	isSafe () const
bool	needsEscape () const
	operator QString () const
	operator QVariant () const
SafeString	operator+ (const QString &str)
SafeString	operator+ (const SafeString &str)
SafeString &	operator+= (const QString &str)
SafeString &	operator+= (const SafeString &str)
SafeString &	operator= (const SafeString &str)
bool	operator== (const QString &other) const
bool	operator== (const SafeString &other) const

Detailed Description

A QString wrapper class for containing whether a string is safe or needs to be escaped.

This allows lazy escaping of strings. Otherwise a string may be escaped multiple times where it should only be escaped once.

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.

SafeString s("this & that", SafeString::IsSafe);
s.get().replace( "this", "these" ).toUpper();
 
qDebug() << s.get() << s.isSafe(); // outputs "these & that" false

Note that most operations on strings make the string unsafe. For example, while "K & R" is safe, using replace("m", "n") will result in "K &anp; R", which is unsafe. Likewise using upper() will return "K & R", 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.

NestedString has overloads for SafeStrings whereever appropriate so that strings remain marked as safe where possible.

For example:

SafeString s1("this & that", SafeString::IsSafe);
s2 = s1;
s1.append( QString( " & the other" ) );
// s1 is now "this & that & the other" and is unsafe.
 
SafeString s3(" Wobl & Bob", SafeString::IsSafe);
s2.append(s3);
// Both s2 and s3 are safe, and append is a safe operation, so s2
// is still safe

See also

Autoescaping and safe-ness

OutputStream::escape

The SafeString class 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.

Author

Stephen Kelly steve.nosp@m.ire@.nosp@m.gmail.nosp@m..com

Definition at line 80 of file safestring.h.

Member Enumeration Documentation

Safety

enum KTextTemplate::SafeString::Safety

Possible safety states of a SafeString

Enumerator
IsSafe	The string is safe and requires no further escaping.
IsNotSafe	The string is not safe. It will be escaped before being added to the output of rendering.

Definition at line 86 of file safestring.h.

Constructor & Destructor Documentation

SafeString() [1/4]

SafeString::SafeString

(

)

Constructs an empty SafeString.

Definition at line 16 of file safestring.cpp.

SafeString() [2/4]

SafeString::SafeString

(

const SafeString &

safeString

)

Copy constructor.

Definition at line 23 of file safestring.cpp.

SafeString() [3/4]

SafeString::SafeString	(	const QString &	str,
		bool	safe )

Constructs a SafeString with the content str whose safety is given by safe.

Definition at line 30 of file safestring.cpp.

SafeString() [4/4]

SafeString::SafeString	(	const QString &	str,
		Safety	safety = IsNotSafe )

Constructs a SafeString with the content str whose safety is given by safety.

Definition at line 37 of file safestring.cpp.

~SafeString()

SafeString::~SafeString ( )

default

Destructor.

Member Function Documentation

get() [1/2]

NestedString & KTextTemplate::SafeString::get ( )

inline

Returns the String held by this SafeString

Definition at line 291 of file safestring.h.

get() [2/2]

const NestedString & KTextTemplate::SafeString::get ( ) const

inline

Returns the String held by this SafeString

Definition at line 283 of file safestring.h.

isSafe()

bool SafeString::isSafe

(

)

const

Whether the string is safe.

Definition at line 61 of file safestring.cpp.

needsEscape()

bool SafeString::needsEscape

(

)

const

Whether the string needs to be escaped.

Definition at line 51 of file safestring.cpp.

operator QString()

KTextTemplate::SafeString::operator QString ( ) const

inline

Convenience operator for treating a SafeString like a QString.

Definition at line 299 of file safestring.h.

operator QVariant()

KTextTemplate::SafeString::operator QVariant ( ) const

inline

Convenience operator for storing a SafeString in a QVariant.

Definition at line 354 of file safestring.h.

operator+() [1/2]

SafeString SafeString::operator+

(

const QString &

str

)

Returns a concatenation of this with str.

The result is not safe because str is not safe.

Definition at line 88 of file safestring.cpp.

operator+() [2/2]

SafeString SafeString::operator+

(

const SafeString &

str

)

Returns a concatenation of this with str.

The result is safe if both this and str are safe.

Definition at line 93 of file safestring.cpp.

operator+=() [1/2]

SafeString & SafeString::operator+=

(

const QString &

str

)

Appends the content of str to this.

The result is not safe because str is not safe.

Definition at line 100 of file safestring.cpp.

operator+=() [2/2]

SafeString & SafeString::operator+=

(

const SafeString &

str

)

Appends the content of str to this.

The result is safe if both this and str are safe.

Definition at line 108 of file safestring.cpp.

operator=()

SafeString & SafeString::operator=

(

const SafeString &

str

)

Assignment operator.

Definition at line 77 of file safestring.cpp.

operator==() [1/2]

bool SafeString::operator==

(

const QString &

other

)

const

Returns true if the content of other matches the content of this.

Safeness and needing escaping are not accounted for in the comparison.

Definition at line 124 of file safestring.cpp.

operator==() [2/2]

bool SafeString::operator==

(

const SafeString &

other

)

const

Returns true if the content of other matches the content of this.

Safeness and needing escaping are not accounted for in the comparison.

Definition at line 117 of file safestring.cpp.

---

The documentation for this class was generated from the following files:

• safestring.h
• safestring.cpp