Wt: Wt::WString Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Static Public Attributes | Related Symbols | List of all members
Wt::WString Class Reference

A value class which describes a locale-aware unicode string. More...

`#include <Wt/WString.h>`

## Public Member Functions
| WString ()
| Creates an empty string.
| WString (const wchar_t *value)
| Creates a WString from a wide C string.
| WString (const WString &other)
| Copy constructor.
| WString (WString &&other)
| Move constructor.
| WString (const std::wstring &value)
| Creates a WString from a wide C++ string.
| WString (const char16_t *value)
| Creates a WString from a UTF-16 C string.
| WString (const std::u16string &value)
| Creates a WString from a UTF-16 C++ string.
| WString (const char32_t *value)
| Creates a WString from a UTF-32 C string.
| WString (const std::u32string &value)
| Creates a WString from a UTF-32 C++ string.
| WString (const char *value, CharEncoding encoding=CharEncoding::Default)
| Creates a WString from a C string.
| WString (const char *value, const std::locale &loc)
| Creates a WString from a C string.
| WString (const std::string &value, CharEncoding encoding=CharEncoding::Default)
| Creates a WString from a C++ string.
| WString (std::string &&value, CharEncoding encoding=CharEncoding::Default)
| Creates a WString from a C++ string.
| WString (const std::string &value, const std::locale &loc)
| Creates a WString from a C++ string.
| ~WString ()
| Destructor.
WString & | operator= (const WString &rhs)
| Copy assignment operator.
WString & | operator= (WString &&rhs)
| Move assignment operator.
bool | operator== (const WString &rhs) const
| Comparison operator.
bool | operator< (const WString &rhs) const
| Comparison operator.
bool | operator> (const WString &rhs) const
| Comparison operator.
WString & | operator+= (const WString &rhs)
| Self-concatenation operator.
WString & | operator+= (const std::wstring &rhs)
| Self-concatenation operator.
WString & | operator+= (const std::u16string &rhs)
| Self-concatenation operator.
WString & | operator+= (const std::u32string &rhs)
| Self-concatenation operator.
WString & | operator+= (const wchar_t *rhs)
| Self-concatenation operator.
WString & | operator+= (const char16_t *rhs)
| Self-concatenation operator.
WString & | operator+= (const char32_t *rhs)
| Self-concatenation operator.
WString & | operator+= (const std::string &rhs)
| Self-concatenation operator.
WString & | operator+= (const char *rhs)
| Self-concatenation operator.
bool | empty () const
| Returns whether the string is empty.
std::string | toUTF8 () const
| Returns the value as a UTF-8 encoded string.
std::string | toXhtmlUTF8 () const
| Returns the value as a UTF-8 encoded XHTML string.
std::wstring | value () const
| Returns the value as a wide C++ string.
std::u16string | toUTF16 () const
| Returns the value as a UTF-16 C++ string.
std::u32string | toUTF32 () const
| Returns the value as a UTF-32 C++ string.
std::string | narrow (const std::locale &loc=std::locale()) const
| Returns the value as a narrow C++ string.
| operator std::wstring () const
| Returns the value as a wide C++ string.
| operator std::u16string () const
| Returns the value as a UTF-16 C++ string.
| operator std::u32string () const
| Returns the value as a UTF-32 C++ string.
bool | literal () const
| Returns whether the string is literal or localized.
const std::string | key () const
| Returns the key for a localized string.
WString & | arg (const std::wstring &value)
| Substitutes the next positional argument with a string value.
WString & | arg (const wchar_t *value)
| Substitutes the next positional argument with a string value.
WString & | arg (const std::u16string &value)
| Substitutes the next positional argument with a string value.
WString & | arg (const char16_t *value)
| Substitutes the next positional argument with a string value.
WString & | arg (const std::u32string &value)
| Substitutes the next positional argument with a string value.
WString & | arg (const char32_t *value)
| Substitutes the next positional argument with a string value.
WString & | arg (const std::string &value, CharEncoding encoding=CharEncoding::Default)
| Substitutes the next positional argument with a string value.
WString & | arg (const char *value, CharEncoding encoding=CharEncoding::Default)
| Substitutes the next positional argument with a string value.
WString & | arg (const WString &value)
| Substitutes the next positional argument with a string value.
WString & | arg (int value)
| Substitutes the next positional argument with an integer value.
WString & | arg (unsigned value)
| Substitutes the next positional argument with an unsigned value.
WString & | arg (long value)
| Substitutes the next positional argument with an integer value.
WString & | arg (unsigned long value)
| Substitutes the next positional argument with an unsigned value.
WString & | arg (long long value)
| Substitutes the next positional argument with an integer value.
WString & | arg (unsigned long long value)
| Substitutes the next positional argument with an unsigned value.
WString & | arg (double value)
| Substitutes the next positional argument with a double value.
const std::vector< WString > & | args () const
| Returns the list of arguments.
bool | refresh ()
| Refreshes the string.
std::string | jsStringLiteral (char delimiter='\'') const
| Returns the string as a JavaScript literal.
bool | operator!= (const WString &rhs) const
| Comparison operator.

## Static Public Member Functions
static void | setDefaultEncoding (Wt::CharEncoding encoding)
| Sets the encoding for CharEncoding::Default.
static WString | fromUTF8 (const std::string &value, bool checkValid=false)
| Creates a WString from a UTF-8 encoded string.
static WString | fromUTF8 (std::string &&value, bool checkValid=false)
| Creates a WString from a UTF-8 encoded string.
static WString | fromUTF8 (const char *value, bool checkValid=false)
| Creates a WString from a UTF-8 unicode encoded string.
static WString | tr (const char *key)
| Creates a localized string from a key.
static WString | tr (const std::string &key)
| Creates a localized string with the specified key.
static WString | trn (const char *key, ::uint64_t n)
| Creates a localized string from a key for a number `n`.
static WString | trn (const std::string &key, ::uint64_t n)
| Creates a localized string with the specified key for a number `n`.

## Static Public Attributes
static const WString | Empty
| An empty string.

## Related Symbols
(Note that these are not member symbols.)
enum class | CharEncoding
| Enumeration that indicates a character encoding. More...
WT_API WString | utf8 (const char *value)
| Short hand for WString(const char * value, CharEncoding::UTF8)
WT_API WString | utf8 (const std::string &value)
| Short hand for WString(const std::string& value, CharEncoding::UTF8)
WT_API WString | operator+ (const WString &lhs, const WString &rhs)
| Concatenate two WStrings.
WT_API WString | operator+ (const WString &lhs, const std::wstring &rhs)
| Conatenate a WString with a C++ wide string.
WT_API WString | operator+ (const WString &lhs, const std::u16string &rhs)
| Conatenate a WString with a C++ UTF-16 string.
WT_API WString | operator+ (const WString &lhs, const std::u32string &rhs)
| Conatenate a WString with a C++ UTF-32 string.
WT_API WString | operator+ (const WString &lhs, const wchar_t *rhs)
| Conatenate a WString with a C wide string.
WT_API WString | operator+ (const WString &lhs, const char16_t *rhs)
| Conatenate a WString with a C UTF-16 string.
WT_API WString | operator+ (const WString &lhs, const char32_t *rhs)
| Conatenate a WString with a C UTF-32 string.
WT_API WString | operator+ (const WString &lhs, const std::string &rhs)
| Conatenate a WString with a C++ string.
WT_API WString | operator+ (const WString &lhs, const char *rhs)
| Conatenate a WString with a C string.
WT_API WString | operator+ (const std::wstring &lhs, const WString &rhs)
| Conatenate a C++ wide string with a WString.
WT_API WString | operator+ (const std::u16string &lhs, const WString &rhs)
| Conatenate a C++ UTF-16 string with a WString.
WT_API WString | operator+ (const std::u32string &lhs, const WString &rhs)
| Conatenate a C++ UTF-32 string with a WString.
WT_API WString | operator+ (const wchar_t *lhs, const WString &rhs)
| Conatenate a C wide string with a WString.
WT_API WString | operator+ (const char16_t *lhs, const WString &rhs)
| Conatenate a C UTF-16 string with a WString.
WT_API WString | operator+ (const char32_t *lhs, const WString &rhs)
| Conatenate a C UTF-32 string with a WString.
WT_API WString | operator+ (const std::string &lhs, const WString &rhs)
| Conatenate a C++ string with a WString.
WT_API WString | operator+ (const char *lhs, const WString &rhs)
| Conatenate a C string with a WString.
WT_API bool | operator== (const char *lhs, const WString &rhs)
| Compare a C string with a WString.
WT_API bool | operator== (const wchar_t *lhs, const WString &rhs)
| Compare a C wide string with a WString.
WT_API bool | operator== (const char16_t *lhs, const WString &rhs)
| Compare a C UTF-16 string with a WString.
WT_API bool | operator== (const char32_t *lhs, const WString &rhs)
| Compare a C UTF-32 string with a WString.
WT_API bool | operator== (const std::string &lhs, const WString &rhs)
| Compare a C++ string with a WString.
WT_API bool | operator== (const std::wstring &lhs, const WString &rhs)
| Compare a C++ wide string with a WString.
WT_API bool | operator== (const std::u16string &lhs, const WString &rhs)
| Compare a C++ UTF-16 string with a WString.
WT_API bool | operator== (const std::u32string &lhs, const WString &rhs)
| Compare a C++ UTF-32 string with a WString.
WT_API bool | operator!= (const char *lhs, const WString &rhs)
| Compare a C string with a WString.
WT_API bool | operator!= (const wchar_t *lhs, const WString &rhs)
| Compare a C wide string with a WString.
WT_API bool | operator!= (const char16_t *lhs, const WString &rhs)
| Compare a C UTF-16 string with a WString.
WT_API bool | operator!= (const char32_t *lhs, const WString &rhs)
| Compare a C UTF-32 string with a WString.
WT_API bool | operator!= (const std::string &lhs, const WString &rhs)
| Compare a C++ string with a WString.
WT_API bool | operator!= (const std::wstring &lhs, const WString &rhs)
| Compare a C++ wide string with a WString.
WT_API bool | operator!= (const std::u16string &lhs, const WString &rhs)
| Compare a C++ UTF-16 string with a WString.
WT_API bool | operator!= (const std::u32string &lhs, const WString &rhs)
| Compare a C++ UTF-32 string with a WString.
WT_API std::wostream & | operator<< (std::wostream &lhs, const WString &rhs)
| Output a WString to a C++ wide stream.
WT_API std::ostream & | operator<< (std::ostream &lhs, const WString &rhs)
| Output a WString to a C++ stream.
WT_API std::wstring | widen (const std::string &s, const std::locale &loc=std::locale())
| Convert a narrow to a wide string.
WT_API std::u16string | toUTF16 (const std::string &s, const std::locale &loc=std::locale())
| Convert a narrow string to UTF-16.
WT_API std::u32string | toUTF32 (const std::string &s, const std::locale &loc=std::locale())
| Convert a narrow string to UTF-32.
WT_API std::string | narrow (const std::wstring &s, const std::locale &loc=std::locale())
| Convert a wide to a narrow string.
WT_API std::string | narrow (const std::u16string &s, const std::locale &loc=std::locale())
| Convert a UTF-16 to a narrow string.
WT_API std::string | narrow (const std::u32string &s, const std::locale &loc=std::locale())
| Convert a UTF-32 to a narrow string.
WT_API std::wstring | fromUTF8 (const std::string &s)
| Decode a UTF-8 string a wide string.
WT_API std::u16string | utf8ToUTF16 (const std::string &s)
| Decode a UTF-8 string a UTF-16 string.
WT_API std::u32string | utf8ToUTF32 (const std::string &s)
| Decode a UTF-8 string a UTF-32 string.
WT_API std::string | fromUTF8 (const std::string &s, const std::locale &loc)
| Decode a UTF-8 string into a (narrow) string.
WT_API std::string | toUTF8 (const std::wstring &s)
| Encode a wide string to UTF-8.
WT_API std::string | toUTF8 (const std::u16string &s)
| Encode a UTF-16 string to UTF-8.
WT_API std::string | toUTF8 (const std::u32string &s)
| Encode a UTF-32 string to UTF-8.
WT_API std::string | toUTF8 (const std::string &s, const std::locale &loc=std::locale())
| Encode a character string (encoding known) to UTF-8.
WT_API std::u16string | toUTF16 (const std::wstring &s)
| Convert a wide string to UTF-16.
WT_API std::u32string | toUTF32 (const std::wstring &s)
| Convert a wide string to UTF-32.

## Detailed Description

A value class which describes a locale-aware unicode string.

Wt offers this string to facilitate handling of unicode text through the user interface, and to offer support for localized text using message resource bundles.

A WString may be constructed from a std::string, std::wstring or c-style strings (const char * and const wchar_t *), and converted to each of these strings taking into account the locale in which the Wt application runs on the web server. Independent of the locale on the web server, you may convert from and to UTF8 unicode encoded std::strings.

By using the static functions WString::tr() (or WWidget::tr()), one may construct a localized string. The key is used to retrieve its current value from the application's message-resource bundles.

Argument place holder in a string, denoted using {n} for the n'th argument, may be substituted by values set using arg(int) and arg(std::string).

WString is used by all built-in widgets for displayed text. By calling WApplication::setLocale() or WApplication::refresh(), the contents of every WString is reevaluated in the new locale, by calling refresh(). In this way, the contents of the whole user interface is adapted to a possibly changed locale.

To benefit from the localization properties of WString, you should design your own widget classes to use WString in their interface for any text that is displayed. In this way, your own widgets will automatically, and without any extra effort, participate in a relocalization triggered by WApplication::setLocale().

This string class does not provide anything more than basic manipulations. Instead, you should convert to a standard library string class to manipulate the string contents and perform string algorithms on them. In particular, we recommend to use the conversion methods toUTF8(), fromUTF8() to convert from and to UTF8 encoded std::strings. In this way, you can support the whole unicode character set, with backward compatible support for the standard 7-bit ASCII set. Since WString internally uses UTF8-encoding, and UTF8-encoding is used by the library for communication with the browser, there is no actual conversion overhead. Only when you need to run string algorithms that require the actual length of the string in number of characters, you would need to convert to a wide string representation such as std::wstring.

See also
  WApplication::messageResourceBundle()
  WApplication::locale()

## Constructor & Destructor Documentation

## ◆ WString() [1/12]

Wt::WString::WString | ( |  | ) |

Creates an empty string.

Create a literal string with empty contents ("").

## ◆ WString() [2/12]

Wt::WString::WString | ( | const wchar_t * | value | ) |

Creates a WString from a wide C string.

The wide string is implicitly converted to proper unicode. Note that there are known issues with the portability of wchar_t since its width and encoding are platform dependent.

## ◆ WString() [3/12]

Wt::WString::WString | ( | const std::wstring & | value | ) |

Creates a WString from a wide C++ string.

The wide string is implicitly converted to proper unicode. Note that there are known issues with the portability of wchar_t since its width and encoding are platform dependent.

## ◆ WString() [4/12]

Wt::WString::WString | ( | const char16_t * | value | ) |

Creates a WString from a UTF-16 C string.

The UTF-16 string is implicitly converted to UTF-8.

## ◆ WString() [5/12]

Wt::WString::WString | ( | const std::u16string & | value | ) |

Creates a WString from a UTF-16 C++ string.

The UTF-16 string is implicitly converted to UTF-8.

## ◆ WString() [6/12]

Wt::WString::WString | ( | const char32_t * | value | ) |

Creates a WString from a UTF-32 C string.

The UTF-32 string is implicitly converted to UTF-8.

## ◆ WString() [7/12]

Wt::WString::WString | ( | const std::u32string & | value | ) |

Creates a WString from a UTF-32 C++ string.

The UTF-32 string is implicitly converted to UTF-8.

## ◆ WString() [8/12]

Wt::WString::WString | ( | const char * | value,
|  | CharEncoding | encoding = CharEncoding::Default )

Creates a WString from a C string.

The C string is implicitly converted to unicode. When `encoding` is CharEncoding::Local, the current locale is used to interpret the C string. When encoding is CharEncoding::UTF8, the C string is interpreted as a CharEncoding::UTF8 encoded unicode string.

WString::setDefaultEncoding() controls the behaviour of CharEncoding::Default. Use it to set a system-wide default format for C style strings (e.g. to UTF-8).

## ◆ WString() [9/12]

Wt::WString::WString | ( | const char * | value,
|  | const std::locale & | loc )

Creates a WString from a C string.

The C string is implicitly converted to unicode. The string is interpreted within the character set of the given locale.

## ◆ WString() [10/12]

Wt::WString::WString | ( | const std::string & | value,
|  | CharEncoding | encoding = CharEncoding::Default )

Creates a WString from a C++ string.

The C++ string is implicitly converted to unicode. When `encoding` is CharEncoding::Local, the current locale is used to interpret the C++ string. When encoding is CharEncoding::UTF8, the C++ string is interpreted as a CharEncoding::UTF8 encoded unicode string.

WString::setDefaultEncoding() controls the behaviour of CharEncoding::Default. Use it to set a system-wide default format for C style strings (e.g. to UTF-8).

## ◆ WString() [11/12]

Wt::WString::WString | ( | std::string && | value,
|  | CharEncoding | encoding = CharEncoding::Default )

Creates a WString from a C++ string.

The C++ string is implicitly converted to unicode. When `encoding` is CharEncoding::Local, the current locale is used to interpret the C++ string. When encoding is CharEncoding::UTF8, the C++ string is interpreted as a CharEncoding::UTF8 encoded unicode string.

WString::setDefaultEncoding() controls the behaviour of CharEncoding::Default. Use it to set a system-wide default format for C style strings (e.g. to UTF-8).

## ◆ WString() [12/12]

Wt::WString::WString | ( | const std::string & | value,
|  | const std::locale & | loc )

Creates a WString from a C++ string.

The C++ string is implicitly converted to unicode. The string is interpreted within the character set of the given locale.

## Member Function Documentation

## ◆ arg() [1/16]

WString & Wt::WString::arg | ( | const char * | value,
|  | CharEncoding | encoding = CharEncoding::Default )

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [2/16]

WString & Wt::WString::arg | ( | const char16_t * | value | ) |

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [3/16]

WString & Wt::WString::arg | ( | const char32_t * | value | ) |

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [4/16]

WString & Wt::WString::arg | ( | const std::string & | value,
|  | CharEncoding | encoding = CharEncoding::Default )

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [5/16]

WString & Wt::WString::arg | ( | const std::u16string & | value | ) |

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [6/16]

WString & Wt::WString::arg | ( | const std::u32string & | value | ) |

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [7/16]

WString & Wt::WString::arg | ( | const std::wstring & | value | ) |

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [8/16]

WString & Wt::WString::arg | ( | const wchar_t * | value | ) |

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [9/16]

WString & Wt::WString::arg | ( | const WString & | value | ) |

Substitutes the next positional argument with a string value.

In the string, the `n-th` argument is referred to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [10/16]

WString & Wt::WString::arg | ( | double | value | ) |

Substitutes the next positional argument with a double value.

In the string, the `n-th` argument is reffered to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [11/16]

WString & Wt::WString::arg | ( | int | value | ) |

Substitutes the next positional argument with an integer value.

In the string, the `n-th` argument is reffered to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [12/16]

WString & Wt::WString::arg | ( | long long | value | ) |

Substitutes the next positional argument with an integer value.

In the string, the `n-th` argument is reffered to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [13/16]

WString & Wt::WString::arg | ( | long | value | ) |

Substitutes the next positional argument with an integer value.

In the string, the `n-th` argument is reffered to as using {`n}`.

For example: the string "<tt>{1} bought {2} apples in the shop.</tt>" with first argument value "<tt>Bart</tt>" and second argument value `5` becomes: "<tt>Bart bought 5 apples in the shop.</tt>"

## ◆ arg() [14/16]

WString & Wt::WString::arg | ( | unsigned long long | value | ) |

Substitutes the next positional argument with an unsigned value.

See also
  arg()

## ◆ arg() [15/16]

WString & Wt::WString::arg | ( | unsigned long | value | ) |

Substitutes the next positional argument with an unsigned value.

See also
  arg()

## ◆ arg() [16/16]

WString & Wt::WString::arg | ( | unsigned | value | ) |

Substitutes the next positional argument with an unsigned value.

See also
  arg()

## ◆ fromUTF8() [1/3]

static WString Wt::WString::fromUTF8 | ( | const char * | value,
|  | bool | checkValid = false )
| static

Creates a WString from a UTF-8 unicode encoded string.

This is equivalent to using the constructor WString(`value`, CharEncoding::UTF8).

When `checkValid` is `true`, the UTF-8 encoding is validated. You should enable this only if you cannot trust the origin of the string. The library uses this internally whenever it receives data from the browser (in UTF-8 format).

## ◆ fromUTF8() [2/3]

static WString Wt::WString::fromUTF8 | ( | const std::string & | value,
|  | bool | checkValid = false )
| static

Creates a WString from a UTF-8 encoded string.

This is equivalent to using the constructor WString(`value`, CharEncoding::UTF8).

When `checkValid` is `true`, the UTF-8 encoding is validated. You should enable this only if you cannot trust the origin of the string. The library uses this internally whenever it receives data from the browser (in UTF-8 format).

## ◆ fromUTF8() [3/3]

static WString Wt::WString::fromUTF8 | ( | std::string && | value,
|  | bool | checkValid = false )
| static

Creates a WString from a UTF-8 encoded string.

This is equivalent to using the constructor WString(`value`, CharEncoding::UTF8).

When `checkValid` is `true`, the UTF-8 encoding is validated. You should enable this only if you cannot trust the origin of the string. The library uses this internally whenever it receives data from the browser (in UTF-8 format).

## ◆ jsStringLiteral()

std::string Wt::WString::jsStringLiteral | ( | char | delimiter = '\'' | ) | const

Returns the string as a JavaScript literal.

The `delimiter` may be a single or double quote.

See also
  WWebWidget::jsStringLiteral()

## ◆ key()

const std::string Wt::WString::key | ( |  | ) | const

Returns the key for a localized string.

When the string is literal, the result is undefined.

## ◆ literal()

bool Wt::WString::literal | ( |  | ) | const

Returns whether the string is literal or localized.

See also
  tr()

## ◆ narrow()

std::string Wt::WString::narrow | ( | const std::locale & | loc = std::locale() | ) | const

Returns the value as a narrow C++ string.

A localized string is resolved using the WApplication::localizedStrings().

Argument place holders are substitued with actual arguments.

Any wide character is narrowed using the provided locale, possibly losing information. If you wish to keep all information, use toUTF8() instead, which encodes wide characters in the string.

See also
  toUTF8()

## ◆ operator std::u16string()

Wt::WString::operator std::u16string | ( |  | ) | const

Returns the value as a UTF-16 C++ string.

A localized string is resolved using the WApplication::localizedStrings().

Argument place holders are substitued with actual arguments.

## ◆ operator std::u32string()

Wt::WString::operator std::u32string | ( |  | ) | const

Returns the value as a UTF-32 C++ string.

A localized string is resolved using the WApplication::localizedStrings().

Argument place holders are substitued with actual arguments.

## ◆ operator std::wstring()

Wt::WString::operator std::wstring | ( |  | ) | const

Returns the value as a wide C++ string.

A localized string is resolved using the WApplication::localizedStrings().

Argument place holders are substitued with actual arguments.

## ◆ operator!=()

bool Wt::WString::operator!= | ( | const WString & | rhs | ) | const

Comparison operator.

Compares two strings and returns `true` if the strings are not exactly the same. This may require evaluating a localized string in the current locale.

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

WString & Wt::WString::operator+= | ( | const char * | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. The right hand side is interpreted in the server locale and converted to unicode. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

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

WString & Wt::WString::operator+= | ( | const char16_t * | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

## ◆ operator+=() [3/9]

WString & Wt::WString::operator+= | ( | const char32_t * | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

## ◆ operator+=() [4/9]

WString & Wt::WString::operator+= | ( | const std::string & | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. The right hand side is interpreted in the server locale and converted to unicode. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

## ◆ operator+=() [5/9]

WString & Wt::WString::operator+= | ( | const std::u16string & | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

## ◆ operator+=() [6/9]

WString & Wt::WString::operator+= | ( | const std::u32string & | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

## ◆ operator+=() [7/9]

WString & Wt::WString::operator+= | ( | const std::wstring & | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

## ◆ operator+=() [8/9]

WString & Wt::WString::operator+= | ( | const wchar_t * | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

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

WString & Wt::WString::operator+= | ( | const WString & | rhs | ) |

Self-concatenation operator.

Appends a string to the current value. If the string was localized, this automatically converts it to a literal string, by evaluating the string using the current WLocale.

## ◆ operator<()

bool Wt::WString::operator< | ( | const WString & | rhs | ) | const

Comparison operator.

Compares to strings lexicographically. This may require evaluating a localized string in the current locale. The unicode representation of the strings are compared.

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

WString & Wt::WString::operator= | ( | const WString & | rhs | ) |

Copy assignment operator.

Copy another string into this string.

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

WString & Wt::WString::operator= | ( | WString && | rhs | ) |

Move assignment operator.

Move another string into this string.

## ◆ operator==()

bool Wt::WString::operator== | ( | const WString & | rhs | ) | const

Comparison operator.

Compares two strings and returns `true` if the strings are exactly the same. This may require evaluating a localized string in the current locale.

## ◆ operator>()

bool Wt::WString::operator> | ( | const WString & | rhs | ) | const

Comparison operator.

Compares to strings lexicographically. This may require evaluating a localized string in the current locale. The unicode representation of the strings are compared.

## ◆ refresh()

bool Wt::WString::refresh | ( |  | ) |

Refreshes the string.

For a localized string, its value is resolved again.

Returns whether the value has (potentially) changed.

## ◆ setDefaultEncoding()

static void Wt::WString::setDefaultEncoding | ( | Wt::CharEncoding | encoding | ) |
| static

Sets the encoding for CharEncoding::Default.

WString::setDefaultEncoding() controls the behaviour of CharEncoding::Default. If not modified, the default encoding will be the CharEncoding::UTF8.

Since this is a system-wide setting, and not a per-session setting, you should call this function before any session is created, e.g. in main() before calling WRun().

## ◆ toUTF16()

std::u16string Wt::WString::toUTF16 | ( |  | ) | const

Returns the value as a UTF-16 C++ string.

A localized string is resolved using the WApplication::localizedStrings().

Argument place holders are substitued with actual arguments.

## ◆ toUTF32()

std::u32string Wt::WString::toUTF32 | ( |  | ) | const

Returns the value as a UTF-32 C++ string.

A localized string is resolved using the WApplication::localizedStrings().

Argument place holders are substitued with actual arguments.

## ◆ toUTF8()

std::string Wt::WString::toUTF8 | ( |  | ) | const

Returns the value as a UTF-8 encoded string.

For a localized string, returns the current localized value. If the localized string is formatted as XML, this will unescape all XML escapes. Literal strings will remain unchanged.

See also
  fromUTF8(), toXhtmlUTF8()

## ◆ toXhtmlUTF8()

std::string Wt::WString::toXhtmlUTF8 | ( |  | ) | const

Returns the value as a UTF-8 encoded XHTML string.

For a localized string, returns the current localized value. If the localized string is formatted as plaintext, the localized string will be escaped. Literal strings will remain unchanged.

See also
  toUTF8()

## ◆ tr() [1/2]

static WString Wt::WString::tr | ( | const char * | key | ) |
| static

Creates a localized string from a key.

Whenever the value of the string is needed, the key is used for a lookup in the application message resource bundles taking into account the current application locale. If the key cannot be resolved, its value is set to '??key??'.

See also
  WApplication::locale(), WApplication::localizedStrings()

## ◆ tr() [2/2]

static WString Wt::WString::tr | ( | const std::string & | key | ) |
| static

Creates a localized string with the specified key.

See also
  tr(const char *)

## ◆ trn() [1/2]

static WString Wt::WString::trn | ( | const char * | key,
|  | ::uint64_t | n )
| static

Creates a localized string from a key for a number `n`.

Whenever the value of the string is needed, the `key` is used for a lookup in the application message resource bundles taking into account the current application locale. This function fetches the appropriate plural case for the translation corresponding to the quantity `n`. Note that usually, your string will have a place-holder for the value of `n`, and thus you will also need to bind `as` an argument.

For example, consider a string "quantity.cars" with two plural cases:

- n == 1: "{1} car"
- n != 1: "{1} cars"

You would use the following to use the string:

Wt::WString::trn("quantity.cars", cars).arg(cars);
Wt::WString::arg
WString & arg(const std::wstring &value)
Substitutes the next positional argument with a string value.
Wt::WString::trn
static WString trn(const char *key, ::uint64_t n)
Creates a localized string from a key for a number n.

If the `key` cannot be resolved, its value is set to '??key??'.

See also
  tr()

## ◆ trn() [2/2]

static WString Wt::WString::trn | ( | const std::string & | key,
|  | ::uint64_t | n )
| static

Creates a localized string with the specified key for a number `n`.

See also
  trn(const char *)

## ◆ value()

std::wstring Wt::WString::value | ( |  | ) | const

Returns the value as a wide C++ string.

A localized string is resolved using the WApplication::localizedStrings().

Argument place holders are substitued with actual arguments.

## Friends And Related Symbol Documentation

## ◆ CharEncoding

enum class CharEncoding
| related

Enumeration that indicates a character encoding.

Character encodings are used to represent characters in a stream of bytes.

## ◆ fromUTF8() [1/2]

WT_API std::wstring fromUTF8 | ( | const std::string & | s | ) |
| related

Decode a UTF-8 string a wide string.

Decode a UTF-8 string to a wide string. In a UTF-8 encoded unicode string, some unicode characters are represented in more than one byte. This method will decode to extract the proper unicode characters from the string. The resulting string may thus be shorter (has fewer characters) than the original, but does not lead to a loss of information.

See also
  toUTF8(const std::string& s, const std::locale&), narrow(const std::wstring&, const std::locale&)

## ◆ fromUTF8() [2/2]

WT_API std::string fromUTF8 | ( | const std::string & | s,
|  | const std::locale & | loc )
| related

Decode a UTF-8 string into a (narrow) string.

Decode a UTF-8 string to a normal string. Not all Unicode characters can be represented in a narrow string, and quite a lot characters will have no equivalent in the target character set, so you may loose information.

To distinguish from the other fromUTF8() function, that returns a wstring, the locale is not an optional argument, as in most other locale-conversing functions. You may choose to use the default-constructed std::locale().

See also
  toUTF8(const std::string& s, const std::locale &), fromUTF8(const std::string& s)

## ◆ narrow() [1/3]

WT_API std::string narrow | ( | const std::u16string & | s,
|  | const std::locale & | loc = std::locale() )
| related

Convert a UTF-16 to a narrow string.

Convert a UTF-16 string to a narrow string. This method will encode the characters in the given locale, if possible.

In general this will lead to a loss of information. If you wish to preserve all information, you should use toUTF8() instead.

See also
  toUTF16(const std::string&, const std::locale&), toUTF8(const std::u16string& s)

## ◆ narrow() [2/3]

WT_API std::string narrow | ( | const std::u32string & | s,
|  | const std::locale & | loc = std::locale() )
| related

Convert a UTF-32 to a narrow string.

Convert a UTF-32 string to a narrow string. This method will encode the characters in the given locale, if possible.

In general this will lead to a loss of information. If you wish to preserve all information, you should use toUTF8() instead.

See also
  toUTF32(const std::string&, const std::locale&), toUTF8(const std::u32string& s)

## ◆ narrow() [3/3]

WT_API std::string narrow | ( | const std::wstring & | s,
|  | const std::locale & | loc = std::locale() )
| related

Convert a wide to a narrow string.

Convert a wide string to a narrow string. This method will encode the characters in the given locale, if possible.

In general this will lead to a loss of information. If you wish to preserve all information, you should use toUTF8() instead.

See also
  widen(const std::string&, const std::locale&), toUTF8(const std::wstring& s)

## ◆ operator<<()

WT_API std::ostream & operator<< | ( | std::ostream & | lhs,
|  | const WString & | rhs )
| related

Output a WString to a C++ stream.

The string is narrowed using the currently global C++ locale, possibly losing information.

## ◆ toUTF16() [1/2]

WT_API std::u16string toUTF16 | ( | const std::string & | s,
|  | const std::locale & | loc = std::locale() )
| related

Convert a narrow string to UTF-16.

Convert a narrow string to UTF-16. This method will interpret the input string as being encoded in the given locale (by default the currently configured global C++ locale).

See also
  narrow(const std::u16string&, const std::locale &), utf8ToUTF16(const std::string &s)

## ◆ toUTF16() [2/2]

WT_API std::u16string toUTF16 | ( | const std::wstring & | s | ) |
| related

Convert a wide string to UTF-16.

Convert a wide string to UTF-16. If sizeof(wchar_t) == 2, then the resulting string will be a copy of the given string. If sizeof(wchar_t) == 4, the resulting string will be converted from UTF-32 to UTF-16.

## ◆ toUTF32() [1/2]

WT_API std::u32string toUTF32 | ( | const std::string & | s,
|  | const std::locale & | loc = std::locale() )
| related

Convert a narrow string to UTF-32.

Convert a narrow string to UTF-32. This method will interpret the input string as being encoded in the given locale (by default the currently configured global C++ locale).

See also
  narrow(const std::u32string&, const std::locale &), utf8ToUTF32(const std::string &s)

## ◆ toUTF32() [2/2]

WT_API std::u32string toUTF32 | ( | const std::wstring & | s | ) |
| related

Convert a wide string to UTF-32.

Convert a wide string to UTF-32. If sizeof(wchar_t) == 4, then the resulting string will be a copy of the given string. If sizeof(wchar_t) == 2, the resulting string will be converted from UTF-16 to UTF-32.

## ◆ toUTF8() [1/4]

WT_API std::string toUTF8 | ( | const std::string & | s,
|  | const std::locale & | loc = std::locale() )
| related

Encode a character string (encoding known) to UTF-8.

Convert a char * string to UTF-8. This method will encode the given string in UTF-8, assuming that the original string was encoded in the given locale. This conversion does not lead to a loss of information.

The reverse operation is in principle narrow(fromUTF8(str), locale).

Do not call this function multiple times: toUTF8(toUTF8(str)) is meaningless.

See also
  toUTF8(const std::wstring& s), fromUTF8(const std::string &), narrow(const std::wstring&, const std::locale&)

## ◆ toUTF8() [2/4]

WT_API std::string toUTF8 | ( | const std::u16string & | s | ) |
| related

Encode a UTF-16 string to UTF-8.

Convert a UTF-16 string to UTF-8. This method will encode the given UTF-16 string in UTF-8. This may result in a string that is possibly longer (has more characters), but does not lead to a loss of information.

See also
  utf8ToUTF16(const std::string& s), narrow(const std::u16string&, const std::locale&)

## ◆ toUTF8() [3/4]

WT_API std::string toUTF8 | ( | const std::u32string & | s | ) |
| related

Encode a UTF-32 string to UTF-8.

Convert a UTF-32 string to UTF-8. This method will encode the given UTF-32 string in UTF-8. This may result in a string that is possibly longer (has more characters), but does not lead to a loss of information.

See also
  utf8ToUTF32(const std::string& s), narrow(const std::u32string&, const std::locale&)

## ◆ toUTF8() [4/4]

WT_API std::string toUTF8 | ( | const std::wstring & | s | ) |
| related

Encode a wide string to UTF-8.

Convert a wide string to UTF-8. This method will encode the given wide string in UTF-8. This may result in a string that is possibly longer (has more characters), but does not lead to a loss of information.

See also
  fromUTF8(const std::string& s), narrow(const std::wstring&, const std::locale&)

## ◆ utf8ToUTF16()

WT_API std::u16string utf8ToUTF16 | ( | const std::string & | s | ) |
| related

Decode a UTF-8 string a UTF-16 string.

Decode a UTF-8 string to a UTF-16 string. In a UTF-8 encoded unicode string, some unicode characters are represented in more than one byte. This method will decode to extract the proper unicode characters from the string. The resulting string may thus be shorter (has fewer characters) than the original, but does not lead to a loss of information.

See also
  toUTF8(const std::string& s, const std::locale&), narrow(const std::u16string&, const std::locale&)

## ◆ utf8ToUTF32()

WT_API std::u32string utf8ToUTF32 | ( | const std::string & | s | ) |
| related

Decode a UTF-8 string a UTF-32 string.

Decode a UTF-8 string to a UTF-32 string. In a UTF-8 encoded unicode string, some unicode characters are represented in more than one byte. This method will decode to extract the proper unicode characters from the string. The resulting string may thus be shorter (has fewer characters) than the original, but does not lead to a loss of information.

See also
  toUTF8(const std::string& s, const std::locale&), narrow(const std::u32string&, const std::locale&)

## ◆ widen()

WT_API std::wstring widen | ( | const std::string & | s,
|  | const std::locale & | loc = std::locale() )
| related

Convert a narrow to a wide string.

Convert a narrow string to a wide string. This method will interpret the input string as being encoded in the given locale (by default the currently configured global C++ locale).

See also
  narrow(const std::wstring&, const std::locale &), fromUTF8(const std::string& s)