Glib::ustring has much the same interface as std::string, but contains Unicode characters encoded as UTF-8.
More...
|
| ustring () |
|
| ~ustring () noexcept |
|
| ustring (const ustring &other) |
|
| ustring (ustring &&other) |
|
ustring & | operator= (const ustring &other) |
|
ustring & | operator= (ustring &&other) |
|
void | swap (ustring &other) |
|
| ustring (const std::string &src) |
|
| ustring (std::string &&src) |
|
| ustring (const ustring &src, size_type i, size_type n=npos) |
|
| ustring (const char *src, size_type n) |
|
| ustring (const char *src) |
|
| ustring (size_type n, gunichar uc) |
|
| ustring (size_type n, char c) |
|
template <class In > |
| ustring (In pbegin, In pend) |
|
|
ustring & | operator= (const std::string &src) |
|
ustring & | operator= (std::string &&src) |
|
ustring & | operator= (const char *src) |
|
ustring & | operator= (gunichar uc) |
|
ustring & | operator= (char c) |
|
ustring & | assign (const ustring &src) |
|
ustring & | assign (ustring &&src) |
|
ustring & | assign (const ustring &src, size_type i, size_type n) |
|
ustring & | assign (const char *src, size_type n) |
|
ustring & | assign (const char *src) |
|
ustring & | assign (size_type n, gunichar uc) |
|
ustring & | assign (size_type n, char c) |
|
template <class In > |
ustring & | assign (In pbegin, In pend) |
|
|
ustring & | operator+= (const ustring &src) |
|
ustring & | operator+= (const char *src) |
|
ustring & | operator+= (gunichar uc) |
|
ustring & | operator+= (char c) |
|
void | push_back (gunichar uc) |
|
void | push_back (char c) |
|
ustring & | append (const ustring &src) |
|
ustring & | append (const ustring &src, size_type i, size_type n) |
|
ustring & | append (const char *src, size_type n) |
|
ustring & | append (const char *src) |
|
ustring & | append (size_type n, gunichar uc) |
|
ustring & | append (size_type n, char c) |
|
template <class In > |
ustring & | append (In pbegin, In pend) |
|
|
ustring & | insert (size_type i, const ustring &src) |
|
ustring & | insert (size_type i, const ustring &src, size_type i2, size_type n) |
|
ustring & | insert (size_type i, const char *src, size_type n) |
|
ustring & | insert (size_type i, const char *src) |
|
ustring & | insert (size_type i, size_type n, gunichar uc) |
|
ustring & | insert (size_type i, size_type n, char c) |
|
iterator | insert (iterator p, gunichar uc) |
|
iterator | insert (iterator p, char c) |
|
void | insert (iterator p, size_type n, gunichar uc) |
|
void | insert (iterator p, size_type n, char c) |
|
template <class In > |
void | insert (iterator p, In pbegin, In pend) |
|
|
ustring & | replace (size_type i, size_type n, const ustring &src) |
|
ustring & | replace (size_type i, size_type n, const ustring &src, size_type i2, size_type n2) |
|
ustring & | replace (size_type i, size_type n, const char *src, size_type n2) |
|
ustring & | replace (size_type i, size_type n, const char *src) |
|
ustring & | replace (size_type i, size_type n, size_type n2, gunichar uc) |
|
ustring & | replace (size_type i, size_type n, size_type n2, char c) |
|
ustring & | replace (iterator pbegin, iterator pend, const ustring &src) |
|
ustring & | replace (iterator pbegin, iterator pend, const char *src, size_type n) |
|
ustring & | replace (iterator pbegin, iterator pend, const char *src) |
|
ustring & | replace (iterator pbegin, iterator pend, size_type n, gunichar uc) |
|
ustring & | replace (iterator pbegin, iterator pend, size_type n, char c) |
|
template <class In > |
ustring & | replace (iterator pbegin, iterator pend, In pbegin2, In pend2) |
|
|
void | clear () |
|
ustring & | erase (size_type i, size_type n=npos) |
|
ustring & | erase () |
|
iterator | erase (iterator p) |
|
iterator | erase (iterator pbegin, iterator pend) |
|
|
int | compare (const ustring &rhs) const |
|
int | compare (const char *rhs) const |
|
int | compare (size_type i, size_type n, const ustring &rhs) const |
|
int | compare (size_type i, size_type n, const ustring &rhs, size_type i2, size_type n2) const |
|
int | compare (size_type i, size_type n, const char *rhs, size_type n2) const |
|
int | compare (size_type i, size_type n, const char *rhs) const |
|
std::string | collate_key () const |
|
std::string | casefold_collate_key () const |
|
|
value_type | operator[] (size_type i) const |
|
value_type | at (size_type i) const |
|
ustring | substr (size_type i=0, size_type n=npos) const |
|
|
iterator | begin () |
|
iterator | end () |
|
const_iterator | begin () const |
|
const_iterator | end () const |
|
reverse_iterator | rbegin () |
|
reverse_iterator | rend () |
|
const_reverse_iterator | rbegin () const |
|
const_reverse_iterator | rend () const |
|
const_iterator | cbegin () const |
|
const_iterator | cend () const |
|
|
size_type | find (const ustring &str, size_type i=0) const |
|
size_type | find (const char *str, size_type i, size_type n) const |
|
size_type | find (const char *str, size_type i=0) const |
|
size_type | find (gunichar uc, size_type i=0) const |
|
size_type | find (char c, size_type i=0) const |
|
size_type | rfind (const ustring &str, size_type i=npos) const |
|
size_type | rfind (const char *str, size_type i, size_type n) const |
|
size_type | rfind (const char *str, size_type i=npos) const |
|
size_type | rfind (gunichar uc, size_type i=npos) const |
|
size_type | rfind (char c, size_type i=npos) const |
|
|
size_type | find_first_of (const ustring & match, size_type i=0) const |
|
size_type | find_first_of (const char * match, size_type i, size_type n) const |
|
size_type | find_first_of (const char * match, size_type i=0) const |
|
size_type | find_first_of (gunichar uc, size_type i=0) const |
|
size_type | find_first_of (char c, size_type i=0) const |
|
size_type | find_last_of (const ustring & match, size_type i=npos) const |
|
size_type | find_last_of (const char * match, size_type i, size_type n) const |
|
size_type | find_last_of (const char * match, size_type i=npos) const |
|
size_type | find_last_of (gunichar uc, size_type i=npos) const |
|
size_type | find_last_of (char c, size_type i=npos) const |
|
size_type | find_first_not_of (const ustring & match, size_type i=0) const |
|
size_type | find_first_not_of (const char * match, size_type i, size_type n) const |
|
size_type | find_first_not_of (const char * match, size_type i=0) const |
|
size_type | find_first_not_of (gunichar uc, size_type i=0) const |
|
size_type | find_first_not_of (char c, size_type i=0) const |
|
size_type | find_last_not_of (const ustring & match, size_type i=npos) const |
|
size_type | find_last_not_of (const char * match, size_type i, size_type n) const |
|
size_type | find_last_not_of (const char * match, size_type i=npos) const |
|
size_type | find_last_not_of (gunichar uc, size_type i=npos) const |
|
size_type | find_last_not_of (char c, size_type i=npos) const |
|
|
bool | empty () const |
| Returns true if the string is empty.
|
|
size_type | size () const |
| Returns the number of characters in the string, not including any null-termination.
|
|
size_type | length () const |
| This is the same as size().
|
|
size_type | bytes () const |
| Returns the number of bytes in the string, not including any null-termination.
|
|
|
void | resize (size_type n, gunichar uc) |
|
void | resize (size_type n, char c='\0') |
|
|
size_type | capacity () const |
|
size_type | max_size () const |
|
void | reserve (size_type n=0) |
|
|
| operator std::string () const |
|
const std::string & | raw () const |
|
const char * | data () const |
|
const char * | c_str () const |
|
size_type | copy (char *dest, size_type n, size_type i=0) const |
|
|
bool | validate () const |
|
bool | validate (iterator &first_invalid) |
|
bool | validate (const_iterator &first_invalid) const |
|
ustring | make_valid () const |
|
bool | is_ascii () const |
|
ustring | normalize (NormalizeMode mode=NORMALIZE_DEFAULT_COMPOSE) const |
|
|
ustring | uppercase () const |
|
ustring | lowercase () const |
|
ustring | casefold () const |
|
|
|
template <class T1 > |
static ustring | compose (const ustring &fmt) |
|
template <class T1 > |
static ustring | compose (const ustring &fmt, const T1 &a1) |
|
template <class T1 , class T2 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2) |
|
template <class T1 , class T2 , class T3 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2, const T3 &a3) |
|
template <class T1 , class T2 , class T3 , class T4 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5, const T6 &a6) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5, const T6 &a6, const T7 &a7) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 , class T8 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5, const T6 &a6, const T7 &a7, const T8 &a8) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 , class T8 , class T9 > |
static ustring | compose (const ustring &fmt, const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5, const T6 &a6, const T7 &a7, const T8 &a8, const T9 &a9) |
|
template <class T1 > |
static ustring | format (const T1 &a1) |
|
template <class T1 , class T2 > |
static ustring | format (const T1 &a1, const T2 &a2) |
|
template <class T1 , class T2 , class T3 > |
static ustring | format (const T1 &a1, const T2 &a2, const T3 &a3) |
|
template <class T1 , class T2 , class T3 , class T4 > |
static ustring | format (const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 > |
static ustring | format (const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 > |
static ustring | format (const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5, const T6 &a6) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 > |
static ustring | format (const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5, const T6 &a6, const T7 &a7) |
|
template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 , class T8 > |
static ustring | format (const T1 &a1, const T2 &a2, const T3 &a3, const T4 &a4, const T5 &a5, const T6 &a6, const T7 &a7, const T8 &a8) |
|
template<class... Ts> |
static ustring | sprintf (const ustring &fmt, const Ts &... args) |
|
template<class... Ts> |
static ustring | sprintf (const char *fmt, const Ts &... args) |
|
static ustring | sprintf (const ustring &fmt) |
|
static ustring | sprintf (const char *fmt) |
|
|
(Note that these are not member symbols.)
|
std::istream & | operator>> (std::istream &is, Glib::ustring &utf8_string) |
| Stream input operator.
|
|
std::ostream & | operator<< (std::ostream &os, const Glib::ustring &utf8_string) |
| Stream output operator.
|
|
std::wistream & | operator>> (std::wistream &is, ustring &utf8_string) |
| Wide stream input operator.
|
|
std::wostream & | operator<< (std::wostream &os, const ustring &utf8_string) |
| Wide stream output operator.
|
|
void | swap (ustring &lhs, ustring &rhs) |
|
bool | operator== (const ustring &lhs, const ustring &rhs) |
|
bool | operator== (const ustring &lhs, const char *rhs) |
|
bool | operator== (const char *lhs, const ustring &rhs) |
|
bool | operator!= (const ustring &lhs, const ustring &rhs) |
|
bool | operator!= (const ustring &lhs, const char *rhs) |
|
bool | operator!= (const char *lhs, const ustring &rhs) |
|
bool | operator< (const ustring &lhs, const ustring &rhs) |
|
bool | operator< (const ustring &lhs, const char *rhs) |
|
bool | operator< (const char *lhs, const ustring &rhs) |
|
bool | operator> (const ustring &lhs, const ustring &rhs) |
|
bool | operator> (const ustring &lhs, const char *rhs) |
|
bool | operator> (const char *lhs, const ustring &rhs) |
|
bool | operator<= (const ustring &lhs, const ustring &rhs) |
|
bool | operator<= (const ustring &lhs, const char *rhs) |
|
bool | operator<= (const char *lhs, const ustring &rhs) |
|
bool | operator>= (const ustring &lhs, const ustring &rhs) |
|
bool | operator>= (const ustring &lhs, const char *rhs) |
|
bool | operator>= (const char *lhs, const ustring &rhs) |
|
ustring | operator+ (const ustring &lhs, const ustring &rhs) |
|
ustring | operator+ (const ustring &lhs, const char *rhs) |
|
ustring | operator+ (const char *lhs, const ustring &rhs) |
|
ustring | operator+ (const ustring &lhs, gunichar rhs) |
|
ustring | operator+ (gunichar lhs, const ustring &rhs) |
|
ustring | operator+ (const ustring &lhs, char rhs) |
|
ustring | operator+ (char lhs, const ustring &rhs) |
|
Glib::ustring has much the same interface as std::string, but contains Unicode characters encoded as UTF-8.
- About UTF-8 and ASCII
- The standard character set ANSI_X3.4-1968 – more commonly known as ASCII – is a subset of UTF-8. So, if you want to, you can use Glib::ustring without even thinking about UTF-8.
- Whenever ASCII is mentioned in this manual, we mean the real ASCII (i.e. as defined in ANSI_X3.4-1968), which contains only 7-bit characters. Glib::ustring can not be used with ASCII-compatible extended 8-bit charsets like ISO-8859-1. It's a good idea to avoid string literals containing non-ASCII characters (e.g. German umlauts) in source code, or at least you should use UTF-8 literals.
- You can find a detailed UTF-8 and Unicode FAQ here: http://www.cl.cam.ac.uk/~mgk25/unicode.html
- Glib::ustring vs. std::string
- Glib::ustring has implicit type conversions to and from std::string. These conversions do not convert to/from the current locale (see Glib::locale_from_utf8() and Glib::locale_to_utf8() if you need that). You can always use std::string instead of Glib::ustring – however, using std::string with multi-byte characters is quite hard. For instance,
std::string::operator[]
might return a byte in the middle of a character, and std::string::length()
returns the number of bytes rather than characters. So don't do that without a good reason.
- You cannot always use Glib::ustring instead of std::string.
std::replace(
u.begin(),
u.end(),
'_',
' ');
RefPtr<> is a reference-counting shared smartpointer.
Definition refptr.h:52
Glib::ustring has much the same interface as std::string, but contains Unicode characters encoded as ...
Definition ustring.h:327
You can't use a Glib::ustring::iterator for writing to a Glib::ustring. See the documentation of Glib::ustring_Iterator for differences between it and std::string::iterator.
- Many member functions and operators of Glib::ustring and Glib::ustring_Iterator assume that the string contains only valid UTF-8 data. If it does not, memory outside the bounds of the string can be accessed. If you're uncertain, use validate() and/or make_valid().
- In a perfect world the C++ Standard Library would contain a UTF-8 string class. Unfortunately, the C++98 standard doesn't mention UTF-8 at all. C++11 has UTF-8 literals but no UTF-8 string class. Note that std::wstring is not a UTF-8 string class because it contains only fixed-width characters (where width could be 32, 16, or even 8 bits).
- Glib::ustring and stream input/output
- The stream I/O operators, that is operator<<() and operator>>(), perform implicit charset conversion to/from the current locale. If that's not what you intended (e.g. when writing to a configuration file that should always be UTF-8 encoded) use ustring::raw() to override this behaviour.
- If you're using std::ostringstream to build strings for display in the user interface, you must convert the result back to UTF-8 as shown below:
std::locale::global(std::locale(""));
Glib::ustring locale_to_utf8(const std::string &opsys_string)
Convert from the current locale's encoding to UTF-8.
- Formatted output and internationalization
- The methods ustring::compose() and ustring::format() provide a convenient and powerful alternative to string streams, as shown in the example below. Refer to the method documentation of compose() and format() for details.
static ustring compose(const ustring &fmt)
static ustring format(const T1 &a1)
- Implementation notes
- Glib::ustring does not inherit from std::string, because std::string was intended to be a final class. For instance, it does not have a virtual destructor. Also, a HAS-A relationship is more appropriate because ustring can't just enhance the std::string interface. Rather, it has to reimplement the interface so that all operations are based on characters instead of bytes.
Substitute placeholders in a format string with the referenced arguments.
This function takes a template string in the format used by C’s printf()
family of functions and an arbitrary number of arguments, replaces each placeholder in the template with the formatted version of its corresponding argument at the same ordinal position in the list of subsequent arguments, and returns the result in a new Glib::ustring.
Note: You must pass the correct count/types/order of arguments to match the format string, as when calling printf()
directly. glibmm does not check this for you. Breaking this contract invokes undefined behavior and is a security risk.
The exception is that glibmm special-cases std::string and Glib::ustring, so you can pass them in positions corresponding to s
placeholders without having to call their .c_str() functions; glibmm does that for you. glibmm also overloads sprintf() with fmt
but no args
to avoid risks.
Said restriction also makes sprintf() unsuitable for translatable strings, as translators cannot reorder the placeholders to suit their language. If you wish to support translation, you should instead use compose(), as its placeholders are numbered rather than ordinal, so they can be moved freely.
- Example:
const auto greeting = std::string{
"Hi"};
const auto your_cows = 3;
const auto my_cows = 11;
const auto cow_percentage = 100.0 * your_cows / my_cows;
"%s, %s! You have %d cows. That's about %0.2f%% of the %d cows I have.",
greeting, name, your_cows, cow_percentage, my_cows);
std::cout << text;
static ustring sprintf(const ustring &fmt, const Ts &... args)
- Parameters
-
fmt | The template string, in the format used by printf() et al. |
args | A set of arguments having the count/types/order required by fmt. |
- Returns
- The substituted string.
- Since glibmm 2.62