KTextTemplate::SafeString Class
class KTextTemplate::SafeStringA QString wrapper class for containing whether a string is safe or needs to be escaped. More...
Header: | #include <KTextTemplate/SafeString> |
CMake: | find_package(KF6 REQUIRED COMPONENTS TextTemplate) target_link_libraries(mytarget PRIVATE KF6::TextTemplate) |
Public Types
class | NestedString |
enum | Safety { IsSafe, IsNotSafe } |
Public Functions
SafeString() | |
SafeString(const QString &str, KTextTemplate::SafeString::Safety safety = IsNotSafe) | |
SafeString(const QString &str, bool safe) | |
KTextTemplate::SafeString::NestedString & | get() |
const KTextTemplate::SafeString::NestedString & | get() const |
bool | isSafe() const |
bool | needsEscape() const |
void | setNeedsEscape(bool needsEscape) |
void | setSafety(KTextTemplate::SafeString::Safety safety) |
QString | operator QString() const |
QVariant | operator QVariant() const |
KTextTemplate::SafeString | operator+(const KTextTemplate::SafeString &str) |
KTextTemplate::SafeString | operator+(const QString &str) |
KTextTemplate::SafeString & | operator+=(const KTextTemplate::SafeString &str) |
KTextTemplate::SafeString & | operator+=(const QString &str) |
KTextTemplate::SafeString & | operator=(const KTextTemplate::SafeString &str) |
bool | operator==(const KTextTemplate::SafeString &other) const |
bool | operator==(const QString &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
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
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.
Member Type Documentation
enum SafeString::Safety
Possible safety states of a SafeString
Constant | Value | Description |
---|---|---|
KTextTemplate::SafeString::IsSafe | 0 | The string is safe and requires no further escaping |
KTextTemplate::SafeString::IsNotSafe | 1 | The string is not safe. It will be escaped before being added to the output of rendering. |
Member Function Documentation
SafeString::SafeString()
Constructs an empty SafeString.
SafeString::SafeString(const QString &str, KTextTemplate::SafeString::Safety safety = IsNotSafe)
Constructs a SafeString with the content str whose safety is given by safety.
SafeString::SafeString(const QString &str, bool safe)
Constructs a SafeString with the content str whose safety is given by safe.
KTextTemplate::SafeString::NestedString &SafeString::get()
Returns the String held by this SafeString
const KTextTemplate::SafeString::NestedString &SafeString::get() const
Returns the String held by this SafeString
bool SafeString::isSafe() const
Whether the string is safe.
bool SafeString::needsEscape() const
Whether the string needs to be escaped.
See also setNeedsEscape().
void SafeString::setNeedsEscape(bool needsEscape)
Set whether the string should be escaped.
See also needsEscape().
void SafeString::setSafety(KTextTemplate::SafeString::Safety safety)
Set whether the string is safe.
QString SafeString::operator QString() const
Convenience operator for treating a SafeString like a QString.
QVariant SafeString::operator QVariant() const
Convenience operator for storing a SafeString in a QVariant.
KTextTemplate::SafeString SafeString::operator+(const KTextTemplate::SafeString &str)
Returns a concatenation of this with str.
The result is safe if both this and str are safe.
KTextTemplate::SafeString SafeString::operator+(const QString &str)
Returns a concatenation of this with str.
The result is not safe because str is not safe.
KTextTemplate::SafeString &SafeString::operator+=(const KTextTemplate::SafeString &str)
Appends the content of str to this.
The result is safe if both this and str are safe.
KTextTemplate::SafeString &SafeString::operator+=(const QString &str)
Appends the content of str to this.
The result is not safe because str is not safe.
KTextTemplate::SafeString &SafeString::operator=(const KTextTemplate::SafeString &str)
Assignment operator.
bool SafeString::operator==(const KTextTemplate::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.
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.