#include <Wt/WString>
Public Member Functions | |
WString () | |
Construct an empty string. | |
WString (const wchar_t *value) | |
Construct a WString from a wide C string. | |
WString (const WString &other) | |
Copy constructor. | |
WString (const std::wstring &value) | |
Construct a WString from a wide C++ string. | |
WString (const char *value, CharEncoding encoding=LocalEncoding) | |
Construct a WString from a C string. | |
WString (const std::string &value, CharEncoding encoding=LocalEncoding) | |
Construct a WString from a C++ string. | |
~WString () | |
Delete a WString. | |
WString & | operator= (const WString &rhs) |
Assignment 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 wchar_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 |
Is the string empty ? | |
std::string | toUTF8 () const |
Get the value as a UTF8 unicode encoded string. | |
std::wstring | value () const |
Get the value as a wide C++ string. | |
std::string | narrow () const |
Get the value as a narrow C++ string. | |
operator std::wstring () const | |
Get the value as a wide C++ string. | |
bool | literal () const |
Is this string literal or localized ? | |
const std::string | key () const |
Get the key for this localized string. | |
WString & | arg (const std::wstring &value) |
Add a value for the next positional string argument of this localized string. | |
WString & | arg (const std::string &value, CharEncoding=LocalEncoding) |
Add a value for the next positional string argument of this localized string. | |
WString & | arg (const WString &value) |
Add a value for the next positional string argument of this localized string. | |
WString & | arg (int value) |
Add a value for the next positional integer argument of this localized string. | |
WString & | arg (double value) |
Add a value for the next positional integer argument of this localized string. | |
const std::vector < std::string > & | args () const |
The list of arguments. | |
bool | refresh () |
Refresh the message. | |
std::string | jsStringLiteral (char delimiter= '\'') const |
Returns the string as a JavaScript literal. | |
Static Public Member Functions | |
static WString | fromUTF8 (const std::string &value) |
Construct a WString from a UTF8 unicode encoded string. | |
static WString | fromUTF8 (const char *value) |
Construct a WString from a UTF8 unicode encoded string. | |
static WString | tr (const char *key) |
Construct a localized string with the specified key. | |
Related Functions | |
(Note that these are not member functions.) | |
enum | CharEncoding { LocalEncoding, UTF8 } |
Enumeration that indicates a character encoding. More... | |
typedef WString | WMessage |
Alias for WString. | |
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 wchar_t *rhs) |
Conatenate a WString with a C wide string. | |
WT_API WString | operator+ (const WString &lhs, const std::string &rhs) |
Conatenate a WStrin 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 wchar_t *lhs, const WString &rhs) |
Conatenate a C wide 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 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 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 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 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) |
Convert a narrow to a wide string. | |
WT_API std::string | narrow (const std::wstring &s) |
Convert a wide to a narrow string. | |
WT_API std::string | toUTF8 (const std::wstring &s) |
Encode a wide string to UTF8. |
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() and the WString(..., UTF8) constructor 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.
Wt::WString::WString | ( | ) |
Construct an empty string.
Create a literal string with empty contents ("").
Wt::WString::WString | ( | const wchar_t * | value | ) |
Construct 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.
Wt::WString::WString | ( | const std::wstring & | value | ) |
Construct 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.
Wt::WString::WString | ( | const char * | value, | |
CharEncoding | encoding = LocalEncoding | |||
) |
Construct a WString from a C string.
The C string is implicitly converted to unicode. When encoding is LocalEncoding, the current locale is used to interpret the C string. When encoding is UTF8, the C string is interpreted as a UTF8 encoded unicode string.
Wt::WString::WString | ( | const std::string & | value, | |
CharEncoding | encoding = LocalEncoding | |||
) |
Construct a WString from a C++ string.
The C++ string is implicitly converted to unicode. When encoding is LocalEncoding, the current locale is used to interpret the C++ string. When encoding is UTF8, the C++ string is interpreted as a UTF8 encoded unicode string.
Wt::WString::~WString | ( | ) |
Delete a WString.
Frees all resources associated with this string.
Assignment operator.
Copy another string into this string.
bool Wt::WString::operator== | ( | const WString & | rhs | ) | const |
Comparison operator.
Compares to strings and returns true if the strings are exactly the same. This may require evaluating a localized string in the current locale.
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.
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 locale.
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 locale.
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 locale.
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 locale.
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 locale.
WT_API std::wstring fromUTF8 | ( | const std::string & | value | ) | [static] |
Construct a WString from a UTF8 unicode encoded string.
Decode a UTF8 string a wide string.
This is equivalent to using the constructor WString(value, UTF8).
Decode a UTF8 string to a wide string. In a UTF8 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 less characters) than the original, but does not lead to a loss of information.
WString Wt::WString::fromUTF8 | ( | const char * | value | ) | [static] |
Construct a WString from a UTF8 unicode encoded string.
This is equivalent to using the constructor WString(value, UTF8).
std::string Wt::WString::toUTF8 | ( | ) | const |
Get the value as a UTF8 unicode encoded string.
For a localized string, returns the current localized value.
WString Wt::WString::tr | ( | const char * | key | ) | [static] |
Construct a localized string with the specified 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??'.
std::wstring Wt::WString::value | ( | ) | const |
Get the value as a wide C++ string.
For a localized string, returns the current localized value.
std::string Wt::WString::narrow | ( | ) | const |
Wt::WString::operator std::wstring | ( | ) | const |
Get the value as a wide C++ string.
For a localized string, returns the current localized value.
bool Wt::WString::literal | ( | ) | const [inline] |
const std::string Wt::WString::key | ( | ) | const |
Get the key for this localized string.
When the string is literal, the result is undefined.
WString & Wt::WString::arg | ( | const std::wstring & | value | ) |
Add a value for the next positional string argument of this localized string.
In the resource, the n-th argument is reffered to as using '{n}'. For example: a resource message '{1} bought {2} apples in the shop.' with first argument value 'Bart' and second argument value '5' becomes: 'Bart bought 5 apples in the shop.'.
WString & Wt::WString::arg | ( | const std::string & | value, | |
CharEncoding | encoding = LocalEncoding | |||
) |
Add a value for the next positional string argument of this localized string.
In the resource, the n-th argument is reffered to as using '{n}'. For example: a resource message '{1} bought {2} apples in the shop.' with first argument value 'Bart' and second argument value '5' becomes: 'Bart bought 5 apples in the shop.'.
Add a value for the next positional string argument of this localized string.
In the resource, the n-th argument is reffered to as using '{n}'. For example: a resource message '{1} bought {2} apples in the shop.' with first argument value 'Bart' and second argument value '5' becomes: 'Bart bought 5 apples in the shop.'.
WString & Wt::WString::arg | ( | int | value | ) |
Add a value for the next positional integer argument of this localized string.
In the resource, the n-th argument is reffered to as using '{n}'. For example: a resource message '{1} bought {2} apples in the shop.' with first argument value 'Bart' and second argument value '5' becomes: 'Bart bought 5 apples in the shop.'.
WString & Wt::WString::arg | ( | double | value | ) |
Add a value for the next positional integer argument of this localized string.
In the resource, the n-th argument is reffered to as using '{n}'. For example: a resource message '{1} bought {2} apples in the shop.' with first argument value 'Bart' and second argument value '5' becomes: 'Bart bought 5 apples in the shop.'.
const std::vector< std::string > & Wt::WString::args | ( | ) | const |
The list of arguments.
Each argument is UTF8 encoded.
bool Wt::WString::refresh | ( | ) |
Refresh the message.
For a localized message, this rereads the value from the message resource bundle.
Returns whether the value has changed.
std::string Wt::WString::jsStringLiteral | ( | char | delimiter = '\'' |
) | const |
Returns the string as a JavaScript literal.
The delimiter may be a single or double quote.
enum CharEncoding [related] |
Alias for WString.
WString provides all the functionality of the now deprecated WMessage, but is used more consistently through the API.
WT_API std::wstring widen | ( | const std::string & | s | ) | [related] |
Convert a narrow to a wide string.
Convert a narrow string to a wide string. This method will not perform any code conversion, it simply represents the same string with a same number of wide characters.
WT_API std::string narrow | ( | const std::wstring & | s | ) | [related] |
Convert a wide to a narrow string.
Convert a wide string to a narrow string. This method will not perform any code conversion, it simply represents (as far as possible) the same string with a same number of narrow characters.
In general this will lead to a loss of information. If you wish to preserve all information, you should us toUTF8() instead.
WT_API std::string toUTF8 | ( | const std::wstring & | s | ) | [related] |
Encode a wide string to UTF8.
Convert a wide string to UTF8. This method will encode the given wide string in UTF8. This may result in a string that is possibly longer (has more characters), but does not lead to a loss of information.