Grantlee: Grantlee::SafeString Class Reference

Grantlee 5.3.0

Classes | Public Types | Public Member Functions | List of all members
Grantlee::SafeString Class Reference

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

`#include <grantlee/safestring.h>`

## Classes
class | NestedString
| The NestedString is a QString whose methods always return a SafeString. More...

## 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

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
Grantlee::SafeString
A QString wrapper class for containing whether a string is safe or needs to be escaped.
Definition: safestring.h:92
Grantlee::SafeString::IsSafe
@ IsSafe
The string is safe and requires no further escaping.
Definition: safestring.h:98

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

## Member Enumeration Documentation

## ◆ Safety

enum Grantlee::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 97 of file safestring.h.

## Constructor & Destructor Documentation

## ◆ SafeString() [1/4]

Grantlee::SafeString::SafeString | ( |  | ) |

Constructs an empty SafeString.

## ◆ SafeString() [2/4]

Grantlee::SafeString::SafeString | ( | const SafeString & | safeString | ) |

Copy constructor

## ◆ SafeString() [3/4]

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

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

## ◆ SafeString() [4/4]

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

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

## ◆ ~SafeString()

Grantlee::SafeString::~SafeString | ( |  | ) |

Destructor

## Member Function Documentation

## ◆ get() [1/2]

NestedString & Grantlee::SafeString::get | ( |  | ) |
| inline

Returns the String held by this SafeString

Definition at line 366 of file safestring.h.

## ◆ get() [2/2]

const NestedString & Grantlee::SafeString::get | ( |  | ) | const
| inline

Returns the String held by this SafeString

Definition at line 361 of file safestring.h.

## ◆ isSafe()

bool Grantlee::SafeString::isSafe | ( |  | ) | const

Whether the string is safe.

## ◆ needsEscape()

bool Grantlee::SafeString::needsEscape | ( |  | ) | const

Whether the string needs to be escaped.

## ◆ operator QString()

Grantlee::SafeString::operator QString | ( |  | ) | const
| inline

Convenience operator for treating a SafeString like a QString.

Definition at line 371 of file safestring.h.

## ◆ operator QVariant()

Grantlee::SafeString::operator QVariant | ( |  | ) | const
| inline

Convenience operator for storing a SafeString in a QVariant.

Definition at line 423 of file safestring.h.

## ◆ operator+() [1/2]

SafeString Grantlee::SafeString::operator+ | ( | const QString & | str | ) |

Returns a concatenation of this with `str`.

The result is not safe because str is not safe.

## ◆ operator+() [2/2]

SafeString Grantlee::SafeString::operator+ | ( | const SafeString & | str | ) |

Returns a concatenation of this with `str`.

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

## ◆ operator+=() [1/2]

SafeString & Grantlee::SafeString::operator+= | ( | const QString & | str | ) |

Appends the content of `str` to this.

The result is not safe because `str` is not safe.

## ◆ operator+=() [2/2]

SafeString & Grantlee::SafeString::operator+= | ( | const SafeString & | str | ) |

Appends the content of `str` to this.

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

## ◆ operator=()

SafeString & Grantlee::SafeString::operator= | ( | const SafeString & | str | ) |

Assignment operator.

## ◆ operator==() [1/2]

bool Grantlee::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.

## ◆ operator==() [2/2]

bool Grantlee::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.