Glib::ustring Class Reference

Glib::ustring has much the same interface as std::string, but contains Unicode characters encoded as UTF-8. More...

`#include <glibmm/ustring.h>`

Inheritance diagram for Glib::ustring:
[legend]

## Public Types

using | size_type = std::string::size_type
using | difference_type = std::string::difference_type
using | value_type = gunichar
using | reference = gunichar&
using | const_reference = const gunichar&
using | iterator = ustring_Iterator< std::string::iterator >
using | const_iterator = ustring_Iterator< std::string::const_iterator >
using | reverse_iterator = std::reverse_iterator< iterator >
using | const_reverse_iterator = std::reverse_iterator< const_iterator >

## Public Member Functions

| 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)
Assign new contents.
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)
Append to the string.
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)
Insert into the string.
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)
Replace sub-strings.
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)
Erase sub-strings.
void | clear ()
ustring& | erase (size_type i, size_type n=npos)
ustring& | erase ()
iterator | erase (iterator p)
iterator | erase (iterator pbegin, iterator pend)
Compare and collate.
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
Extract characters and sub-strings.
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
Access a sequence of characters.
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
Find sub-strings.
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
Match against a set of characters.
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
Retrieve the string's size.
bool | empty () const
| Returns true if the string is empty. More...
size_type | size () const
| Returns the number of characters in the string, not including any null-termination. More...
size_type | length () const
| This is the same as size(). More...
size_type | bytes () const
| Returns the number of bytes in the string, not including any null-termination. More...
Change the string's size.
void | resize (size_type n, gunichar uc)
void | resize (size_type n, char c='\0')
Control the allocated memory.
size_type | capacity () const
size_type | max_size () const
void | reserve (size_type n=0)
Get a per-byte representation of the string.
| 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
UTF-8 utilities.
bool | validate () const
bool | validate (iterator& first_invalid)
bool | validate (const_iterator& first_invalid) const
bool | is_ascii () const
ustring | normalize (NormalizeMode mode=NORMALIZE_DEFAULT_COMPOSE) const
Character case conversion.
ustring | uppercase () const
ustring | lowercase () const
ustring | casefold () const

## Static Public Member Functions

Message formatting.
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)

## Static Public Attributes

static const size_type | npos = std::string::npos

## Related Functions

(Note that these are not member functions.)
std::istream& | operator>> (std::istream& is, Glib::ustring& utf8_string)
| Stream input operator. More...
std::ostream& | operator<< (std::ostream& os, const Glib::ustring& utf8_string)
| Stream output operator. More...
std::wistream& | operator>> (std::wistream& is, ustring& utf8_string)
| Wide stream input operator. More...
std::wostream& | operator<< (std::wostream& os, const ustring& utf8_string)
| Wide stream output operator. More...
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)

## Detailed Description

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.

  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.

  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("")); // set the global locale to the user's preferred locale
  std::ostringstream output;
  output << percentage << " % done";
  label->set_text(Glib::locale_to_utf8(output.str()));

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.
  using Glib::ustring;
  ustring message = ustring::compose("%1 is lower than 0x%2.",
  12, ustring::format(std::hex, 16));

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.

## Member Typedef Documentation

## const_iterator

using Glib::ustring::const_iterator = ustring_Iterator<std::string::const_iterator>

## const_reference

using Glib::ustring::const_reference = const gunichar&

## const_reverse_iterator

using Glib::ustring::const_reverse_iterator = std::reverse_iterator<const_iterator>

## difference_type

using Glib::ustring::difference_type = std::string::difference_type

## iterator

using Glib::ustring::iterator = ustring_Iterator<std::string::iterator>

## reference

using Glib::ustring::reference = gunichar&

## reverse_iterator

using Glib::ustring::reverse_iterator = std::reverse_iterator<iterator>

## size_type

using Glib::ustring::size_type = std::string::size_type

## value_type

using Glib::ustring::value_type = gunichar

## Constructor & Destructor Documentation

## ustring() [1/11]

Glib::ustring::ustring | ( |  | ) |

Default constructor, which creates an empty string.

## ~ustring()

Glib::ustring::~ustring | ( |  | ) |

noexcept

## ustring() [2/11]

Glib::ustring::ustring | ( | const ustring& | other | ) |

Construct a ustring as a copy of another ustring.

Parameters

  other | A source string.

## ustring() [3/11]

Glib::ustring::ustring | ( | ustring&& | other | ) |

Construct a ustring by moving from another ustring.

Parameters

  other | A source string.

## ustring() [4/11]

Glib::ustring::ustring | ( | const std::string & | src | ) |

Construct a ustring as a copy of a std::string.

Parameters

  src | A source `std::string` containing text encoded as UTF-8.

## ustring() [5/11]

Glib::ustring::ustring | ( | std::string && | src | ) |

Construct a ustring by moving from a std::string.

Parameters

  src | A source `std::string` containing text encoded as UTF-8.

## ustring() [6/11]

Glib::ustring::ustring | ( | const ustring& | src,
|  | size_type | i,
|  | size_type | n = `npos`
| ) |  |

Construct a ustring as a copy of a substring.

Parameters

  src | Source ustring.
  i | Index of first character to copy from.
  n | Number of UTF-8 characters to copy (defaults to copying the remainder).

## ustring() [7/11]

Glib::ustring::ustring | ( | const char * | src,
|  | size_type | n
| ) |  |

Construct a ustring as a partial copy of a C string.

Parameters

  src | Source C string encoded as UTF-8.
  n | Number of UTF-8 characters to copy.

## ustring() [8/11]

Glib::ustring::ustring | ( | const char * | src | ) |

Construct a ustring as a copy of a C string.

Parameters

  src | Source C string encoded as UTF-8.

## ustring() [9/11]

Glib::ustring::ustring | ( | size_type | n,
|  | gunichar | uc
| ) |  |

Construct a ustring as multiple characters.

Parameters

  n | Number of characters.
  uc | UCS-4 code point to use.

## ustring() [10/11]

Glib::ustring::ustring | ( | size_type | n,
|  | char | c
| ) |  |

Construct a ustring as multiple characters.

Parameters

  n | Number of characters.
  c | ASCII character to use.

## ustring() [11/11]

template <class In >

Glib::ustring::ustring | ( | In | pbegin,
|  | In | pend
| ) |  |

Construct a ustring as a copy of a range.

Parameters

  pbegin | Start of range.
  pend | End of range.

## Member Function Documentation

## append() [1/7]

ustring& Glib::ustring::append | ( | const ustring& | src | ) |

## append() [2/7]

ustring& Glib::ustring::append | ( | const ustring& | src,
|  | size_type | i,
|  | size_type | n
| ) |  |

## append() [3/7]

ustring& Glib::ustring::append | ( | const char * | src,
|  | size_type | n
| ) |  |

## append() [4/7]

ustring& Glib::ustring::append | ( | const char * | src | ) |

## append() [5/7]

ustring& Glib::ustring::append | ( | size_type | n,
|  | gunichar | uc
| ) |  |

## append() [6/7]

ustring& Glib::ustring::append | ( | size_type | n,
|  | char | c
| ) |  |

## append() [7/7]

template <class In >

ustring& Glib::ustring::append | ( | In | pbegin,
|  | In | pend
| ) |  |

## assign() [1/8]

ustring& Glib::ustring::assign | ( | const ustring& | src | ) |

## assign() [2/8]

ustring& Glib::ustring::assign | ( | ustring&& | src | ) |

## assign() [3/8]

ustring& Glib::ustring::assign | ( | const ustring& | src,
|  | size_type | i,
|  | size_type | n
| ) |  |

## assign() [4/8]

ustring& Glib::ustring::assign | ( | const char * | src,
|  | size_type | n
| ) |  |

## assign() [5/8]

ustring& Glib::ustring::assign | ( | const char * | src | ) |

## assign() [6/8]

ustring& Glib::ustring::assign | ( | size_type | n,
|  | gunichar | uc
| ) |  |

## assign() [7/8]

ustring& Glib::ustring::assign | ( | size_type | n,
|  | char | c
| ) |  |

## assign() [8/8]

template <class In >

ustring& Glib::ustring::assign | ( | In | pbegin,
|  | In | pend
| ) |  |

## at()

value_type Glib::ustring::at | ( | size_type | i | ) | const

No reference return; use replace() to write characters.

Exceptions

  std::out_of_range |

## begin() [1/2]

iterator Glib::ustring::begin | ( |  | ) |

## begin() [2/2]

const_iterator Glib::ustring::begin | ( |  | ) | const

## bytes()

size_type Glib::ustring::bytes | ( |  | ) | const

Returns the number of bytes in the string, not including any null-termination.

Returns
  The number of bytes.

See also
  size(), empty()

## c_str()

const char* Glib::ustring::c_str | ( |  | ) | const

## capacity()

size_type Glib::ustring::capacity | ( |  | ) | const

## casefold()

ustring Glib::ustring::casefold | ( |  | ) | const

Returns a caseless representation of the UTF-8 string. The resulting string doesn't correspond to any particular case, therefore the result is only useful to compare strings and should never be displayed to the user.

## casefold_collate_key()

std::string Glib::ustring::casefold_collate_key | ( |  | ) | const

Create a unique key for the UTF-8 string that can be used for caseless sorting. `ustr.casefold_collate_key()` results in the same string as `ustr.casefold().collate_key()`, but the former is likely more efficient.

## cbegin()

const_iterator Glib::ustring::cbegin | ( |  | ) | const

Since glibmm 2.52:

## cend()

const_iterator Glib::ustring::cend | ( |  | ) | const

Since glibmm 2.52:

## clear()

void Glib::ustring::clear | ( |  | ) |

## collate_key()

std::string Glib::ustring::collate_key | ( |  | ) | const

Create a unique sorting key for the UTF-8 string. If you need to compare UTF-8 strings regularly, e.g. for sorted containers such as `std::set<>`, you should consider creating a collate key first and compare this key instead of the actual string.

The ustring::compare() methods as well as the relational operators `== != < > <= >=` are quite costly because they have to deal with Unicode and the collation rules defined by the current locale. Converting both operands to UCS-4 is just the first of several costly steps involved when comparing ustrings. So be careful.

## compare() [1/6]

int Glib::ustring::compare | ( | const ustring& | rhs | ) | const

## compare() [2/6]

int Glib::ustring::compare | ( | const char * | rhs | ) | const

## compare() [3/6]

int Glib::ustring::compare | ( | size_type | i,
|  | size_type | n,
|  | const ustring& | rhs
| ) |  | const

## compare() [4/6]

int Glib::ustring::compare | ( | size_type | i,
|  | size_type | n,
|  | const ustring& | rhs,
|  | size_type | i2,
|  | size_type | n2
| ) |  | const

## compare() [5/6]

int Glib::ustring::compare | ( | size_type | i,
|  | size_type | n,
|  | const char * | rhs,
|  | size_type | n2
| ) |  | const

## compare() [6/6]

int Glib::ustring::compare | ( | size_type | i,
|  | size_type | n,
|  | const char * | rhs
| ) |  | const

## compose() [1/10]

template <class T1 >

static ustring Glib::ustring::compose | ( | const ustring& | fmt | ) |

inline static

## compose() [2/10]

template <class T1 >

static ustring Glib::ustring::compose | ( | const ustring& | fmt,
|  | const T1 & | a1
| ) |  |

inline static

Substitute placeholders in a format string with the referenced arguments. The template string should be in `qt-format`, that is `"%1"`, `"%2"`, ..., `"%9"` are used as placeholders and `"%%"` denotes a literal `"%"`. Substitutions may be reordered.

Example:
  using Glib::ustring;
  const int percentage = 50;
  const ustring text = ustring::compose("%1%% done", percentage);

Parameters

  fmt | A template string in `qt-format`.
  a1 | The argument to substitute for `"%1"`.

Returns
  The substituted message string.

Exceptions

  Glib::ConvertError |

Since glibmm 2.16:

## compose() [3/10]

template <class T1 , class T2 >

static ustring Glib::ustring::compose | ( | const ustring& | fmt,
|  | const T1 & | a1,
|  | const T2 & | a2
| ) |  |

inline static

## compose() [4/10]

template <class T1 , class T2 , class T3 >

static ustring Glib::ustring::compose | ( | const ustring& | fmt,
|  | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3
| ) |  |

inline static

## compose() [5/10]

template <class T1 , class T2 , class T3 , class T4 >

static ustring Glib::ustring::compose | ( | const ustring& | fmt,
|  | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3,
|  | const T4 & | a4
| ) |  |

inline static

## compose() [6/10]

template <class T1 , class T2 , class T3 , class T4 , class T5 >

static ustring Glib::ustring::compose | ( | const ustring& | fmt,
|  | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3,
|  | const T4 & | a4,
|  | const T5 & | a5
| ) |  |

inline static

## compose() [7/10]

template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 >

static ustring Glib::ustring::compose | ( | const ustring& | fmt,
|  | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3,
|  | const T4 & | a4,
|  | const T5 & | a5,
|  | const T6 & | a6
| ) |  |

inline static

## compose() [8/10]

template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 >

static ustring Glib::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
| ) |  |

inline static

## compose() [9/10]

template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 , class T8 >

static ustring Glib::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
| ) |  |

inline static

## compose() [10/10]

template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 , class T8 , class T9 >

static ustring Glib::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
| ) |  |

inline static

## copy()

size_type Glib::ustring::copy | ( | char * | dest,
|  | size_type | n,
|  | size_type | i = `0`
| ) |  | const

Returns
  Number of copied bytes, not characters.

## data()

const char* Glib::ustring::data | ( |  | ) | const

## empty()

bool Glib::ustring::empty | ( |  | ) | const

Returns true if the string is empty.

Equivalent to *this == "".

Returns
  Whether the string is empty.

## end() [1/2]

iterator Glib::ustring::end | ( |  | ) |

## end() [2/2]

const_iterator Glib::ustring::end | ( |  | ) | const

## erase() [1/4]

ustring& Glib::ustring::erase | ( | size_type | i,
|  | size_type | n = `npos`
| ) |  |

## erase() [2/4]

ustring& Glib::ustring::erase | ( |  | ) |

## erase() [3/4]

iterator Glib::ustring::erase | ( | iterator | p | ) |

## erase() [4/4]

iterator Glib::ustring::erase | ( | iterator | pbegin,
|  | iterator | pend
| ) |  |

## find() [1/5]

size_type Glib::ustring::find | ( | const ustring& | str,
|  | size_type | i = `0`
| ) |  | const

## find() [2/5]

size_type Glib::ustring::find | ( | const char * | str,
|  | size_type | i,
|  | size_type | n
| ) |  | const

## find() [3/5]

size_type Glib::ustring::find | ( | const char * | str,
|  | size_type | i = `0`
| ) |  | const

## find() [4/5]

size_type Glib::ustring::find | ( | gunichar | uc,
|  | size_type | i = `0`
| ) |  | const

## find() [5/5]

size_type Glib::ustring::find | ( | char | c,
|  | size_type | i = `0`
| ) |  | const

## find_first_not_of() [1/5]

size_type Glib::ustring::find_first_not_of | ( | const ustring& | match,
|  | size_type | i = `0`
| ) |  | const

## find_first_not_of() [2/5]

size_type Glib::ustring::find_first_not_of | ( | const char * | match,
|  | size_type | i,
|  | size_type | n
| ) |  | const

## find_first_not_of() [3/5]

size_type Glib::ustring::find_first_not_of | ( | const char * | match,
|  | size_type | i = `0`
| ) |  | const

## find_first_not_of() [4/5]

size_type Glib::ustring::find_first_not_of | ( | gunichar | uc,
|  | size_type | i = `0`
| ) |  | const

## find_first_not_of() [5/5]

size_type Glib::ustring::find_first_not_of | ( | char | c,
|  | size_type | i = `0`
| ) |  | const

## find_first_of() [1/5]

size_type Glib::ustring::find_first_of | ( | const ustring& | match,
|  | size_type | i = `0`
| ) |  | const

## find_first_of() [2/5]

size_type Glib::ustring::find_first_of | ( | const char * | match,
|  | size_type | i,
|  | size_type | n
| ) |  | const

## find_first_of() [3/5]

size_type Glib::ustring::find_first_of | ( | const char * | match,
|  | size_type | i = `0`
| ) |  | const

## find_first_of() [4/5]

size_type Glib::ustring::find_first_of | ( | gunichar | uc,
|  | size_type | i = `0`
| ) |  | const

## find_first_of() [5/5]

size_type Glib::ustring::find_first_of | ( | char | c,
|  | size_type | i = `0`
| ) |  | const

## find_last_not_of() [1/5]

size_type Glib::ustring::find_last_not_of | ( | const ustring& | match,
|  | size_type | i = `npos`
| ) |  | const

## find_last_not_of() [2/5]

size_type Glib::ustring::find_last_not_of | ( | const char * | match,
|  | size_type | i,
|  | size_type | n
| ) |  | const

## find_last_not_of() [3/5]

size_type Glib::ustring::find_last_not_of | ( | const char * | match,
|  | size_type | i = `npos`
| ) |  | const

## find_last_not_of() [4/5]

size_type Glib::ustring::find_last_not_of | ( | gunichar | uc,
|  | size_type | i = `npos`
| ) |  | const

## find_last_not_of() [5/5]

size_type Glib::ustring::find_last_not_of | ( | char | c,
|  | size_type | i = `npos`
| ) |  | const

## find_last_of() [1/5]

size_type Glib::ustring::find_last_of | ( | const ustring& | match,
|  | size_type | i = `npos`
| ) |  | const

## find_last_of() [2/5]

size_type Glib::ustring::find_last_of | ( | const char * | match,
|  | size_type | i,
|  | size_type | n
| ) |  | const

## find_last_of() [3/5]

size_type Glib::ustring::find_last_of | ( | const char * | match,
|  | size_type | i = `npos`
| ) |  | const

## find_last_of() [4/5]

size_type Glib::ustring::find_last_of | ( | gunichar | uc,
|  | size_type | i = `npos`
| ) |  | const

## find_last_of() [5/5]

size_type Glib::ustring::find_last_of | ( | char | c,
|  | size_type | i = `npos`
| ) |  | const

## format() [1/8]

template <class T1 >

static ustring Glib::ustring::format | ( | const T1 & | a1 | ) |

inline static

Format the argument to its string representation. Applies the arguments in order to an std::wostringstream and returns the resulting string. I/O manipulators may also be used as arguments. This greatly simplifies the common task of converting a number to a string, as demonstrated by the example below. The format() methods can also be used in conjunction with compose() to facilitate localization of user-visible messages.

using Glib::ustring;
double value = 22.0 / 7.0;
ustring text = ustring::format(std::fixed, std::setprecision(2), value);

Note
  The use of a wide character stream in the implementation of format() is almost completely transparent. However, one of the instances where the use of wide streams becomes visible is when the std::setfill() stream manipulator is used. In order for std::setfill() to work the argument must be of type `wchar_t`. This can be achieved by using the `L` prefix with a character literal, as shown in the example.
  using Glib::ustring;
  // Insert leading zeroes to fill in at least six digits
  ustring text = ustring::format(std::setfill(L'0'), std::setw(6), 123);

Parameters

  a1 | A streamable value or an I/O manipulator.

Returns
  The string representation of the argument stream.

Exceptions

  Glib::ConvertError |

Since glibmm 2.16:

## format() [2/8]

template <class T1 , class T2 >

static ustring Glib::ustring::format | ( | const T1 & | a1,
|  | const T2 & | a2
| ) |  |

inline static

## format() [3/8]

template <class T1 , class T2 , class T3 >

static ustring Glib::ustring::format | ( | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3
| ) |  |

inline static

## format() [4/8]

template <class T1 , class T2 , class T3 , class T4 >

static ustring Glib::ustring::format | ( | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3,
|  | const T4 & | a4
| ) |  |

inline static

## format() [5/8]

template <class T1 , class T2 , class T3 , class T4 , class T5 >

static ustring Glib::ustring::format | ( | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3,
|  | const T4 & | a4,
|  | const T5 & | a5
| ) |  |

inline static

## format() [6/8]

template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 >

static ustring Glib::ustring::format | ( | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3,
|  | const T4 & | a4,
|  | const T5 & | a5,
|  | const T6 & | a6
| ) |  |

inline static

## format() [7/8]

template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 >

static ustring Glib::ustring::format | ( | const T1 & | a1,
|  | const T2 & | a2,
|  | const T3 & | a3,
|  | const T4 & | a4,
|  | const T5 & | a5,
|  | const T6 & | a6,
|  | const T7 & | a7
| ) |  |

inline static

## format() [8/8]

template <class T1 , class T2 , class T3 , class T4 , class T5 , class T6 , class T7 , class T8 >

static ustring Glib::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
| ) |  |

inline static

## insert() [1/11]

ustring& Glib::ustring::insert | ( | size_type | i,
|  | const ustring& | src
| ) |  |

## insert() [2/11]

ustring& Glib::ustring::insert | ( | size_type | i,
|  | const ustring& | src,
|  | size_type | i2,
|  | size_type | n
| ) |  |

## insert() [3/11]

ustring& Glib::ustring::insert | ( | size_type | i,
|  | const char * | src,
|  | size_type | n
| ) |  |

## insert() [4/11]

ustring& Glib::ustring::insert | ( | size_type | i,
|  | const char * | src
| ) |  |

## insert() [5/11]

ustring& Glib::ustring::insert | ( | size_type | i,
|  | size_type | n,
|  | gunichar | uc
| ) |  |

## insert() [6/11]

ustring& Glib::ustring::insert | ( | size_type | i,
|  | size_type | n,
|  | char | c
| ) |  |

## insert() [7/11]

iterator Glib::ustring::insert | ( | iterator | p,
|  | gunichar | uc
| ) |  |

## insert() [8/11]

iterator Glib::ustring::insert | ( | iterator | p,
|  | char | c
| ) |  |

## insert() [9/11]

void Glib::ustring::insert | ( | iterator | p,
|  | size_type | n,
|  | gunichar | uc
| ) |  |

## insert() [10/11]

void Glib::ustring::insert | ( | iterator | p,
|  | size_type | n,
|  | char | c
| ) |  |

## insert() [11/11]

template <class In >

void Glib::ustring::insert | ( | iterator | p,
|  | In | pbegin,
|  | In | pend
| ) |  |

## is_ascii()

bool Glib::ustring::is_ascii | ( |  | ) | const

Check whether the string is plain 7-bit ASCII.

  Unlike any other ustring method, is_ascii() is safe to use on invalid UTF-8 strings. If the string isn't valid UTF-8, it cannot be valid ASCII either, therefore is_ascii() will just return `false` then.

Returns
  Whether the string contains only ASCII characters.

## length()

size_type Glib::ustring::length | ( |  | ) | const

This is the same as size().

## lowercase()

ustring Glib::ustring::lowercase | ( |  | ) | const

Returns a new UTF-8 string with all characters characters converted to their lowercase equivalent, while honoring the current locale. The resulting string may change in the number of bytes as well as in the number of characters.

## max_size()

size_type Glib::ustring::max_size | ( |  | ) | const

## normalize()

ustring Glib::ustring::normalize | ( | NormalizeMode | mode = `NORMALIZE_DEFAULT_COMPOSE` | ) | const

"Normalize" the Unicode character representation of the string.

## operator std::string()

Glib::ustring::operator std::string | ( |  | ) | const

inline

## operator+=() [1/4]

ustring& Glib::ustring::operator+= | ( | const ustring& | src | ) |

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

ustring& Glib::ustring::operator+= | ( | const char * | src | ) |

## operator+=() [3/4]

ustring& Glib::ustring::operator+= | ( | gunichar | uc | ) |

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

ustring& Glib::ustring::operator+= | ( | char | c | ) |

## operator=() [1/7]

ustring& Glib::ustring::operator= | ( | const ustring& | other | ) |

Assign the value of another string by copying to this string.

Parameters

  other | A source string.

## operator=() [2/7]

ustring& Glib::ustring::operator= | ( | ustring&& | other | ) |

Assign the value of another string by moving to this string.

Parameters

  other | A source string.

## operator=() [3/7]

ustring& Glib::ustring::operator= | ( | const std::string & | src | ) |

## operator=() [4/7]

ustring& Glib::ustring::operator= | ( | std::string && | src | ) |

## operator=() [5/7]

ustring& Glib::ustring::operator= | ( | const char * | src | ) |

## operator=() [6/7]

ustring& Glib::ustring::operator= | ( | gunichar | uc | ) |

## operator=() [7/7]

ustring& Glib::ustring::operator= | ( | char | c | ) |

## operator[]()

value_type Glib::ustring::operator[] | ( | size_type | i | ) | const

No reference return; use replace() to write characters.

## push_back() [1/2]

void Glib::ustring::push_back | ( | gunichar | uc | ) |

## push_back() [2/2]

void Glib::ustring::push_back | ( | char | c | ) |

## raw()

const std::string& Glib::ustring::raw | ( |  | ) | const

inline

## rbegin() [1/2]

reverse_iterator Glib::ustring::rbegin | ( |  | ) |

## rbegin() [2/2]

const_reverse_iterator Glib::ustring::rbegin | ( |  | ) | const

## rend() [1/2]

reverse_iterator Glib::ustring::rend | ( |  | ) |

## rend() [2/2]

const_reverse_iterator Glib::ustring::rend | ( |  | ) | const

## replace() [1/12]

ustring& Glib::ustring::replace | ( | size_type | i,
|  | size_type | n,
|  | const ustring& | src
| ) |  |

## replace() [2/12]

ustring& Glib::ustring::replace | ( | size_type | i,
|  | size_type | n,
|  | const ustring& | src,
|  | size_type | i2,
|  | size_type | n2
| ) |  |

## replace() [3/12]

ustring& Glib::ustring::replace | ( | size_type | i,
|  | size_type | n,
|  | const char * | src,
|  | size_type | n2
| ) |  |

## replace() [4/12]

ustring& Glib::ustring::replace | ( | size_type | i,
|  | size_type | n,
|  | const char * | src
| ) |  |

## replace() [5/12]

ustring& Glib::ustring::replace | ( | size_type | i,
|  | size_type | n,
|  | size_type | n2,
|  | gunichar | uc
| ) |  |

## replace() [6/12]

ustring& Glib::ustring::replace | ( | size_type | i,
|  | size_type | n,
|  | size_type | n2,
|  | char | c
| ) |  |

## replace() [7/12]

ustring& Glib::ustring::replace | ( | iterator | pbegin,
|  | iterator | pend,
|  | const ustring& | src
| ) |  |

## replace() [8/12]

ustring& Glib::ustring::replace | ( | iterator | pbegin,
|  | iterator | pend,
|  | const char * | src,
|  | size_type | n
| ) |  |

## replace() [9/12]

ustring& Glib::ustring::replace | ( | iterator | pbegin,
|  | iterator | pend,
|  | const char * | src
| ) |  |

## replace() [10/12]

ustring& Glib::ustring::replace | ( | iterator | pbegin,
|  | iterator | pend,
|  | size_type | n,
|  | gunichar | uc
| ) |  |

## replace() [11/12]

ustring& Glib::ustring::replace | ( | iterator | pbegin,
|  | iterator | pend,
|  | size_type | n,
|  | char | c
| ) |  |

## replace() [12/12]

template <class In >

ustring& Glib::ustring::replace | ( | iterator | pbegin,
|  | iterator | pend,
|  | In | pbegin2,
|  | In | pend2
| ) |  |

## reserve()

void Glib::ustring::reserve | ( | size_type | n = `0` | ) |

## resize() [1/2]

void Glib::ustring::resize | ( | size_type | n,
|  | gunichar | uc
| ) |  |

## resize() [2/2]

void Glib::ustring::resize | ( | size_type | n,
|  | char | c = `'\0'`
| ) |  |

## rfind() [1/5]

size_type Glib::ustring::rfind | ( | const ustring& | str,
|  | size_type | i = `npos`
| ) |  | const

## rfind() [2/5]

size_type Glib::ustring::rfind | ( | const char * | str,
|  | size_type | i,
|  | size_type | n
| ) |  | const

## rfind() [3/5]

size_type Glib::ustring::rfind | ( | const char * | str,
|  | size_type | i = `npos`
| ) |  | const

## rfind() [4/5]

size_type Glib::ustring::rfind | ( | gunichar | uc,
|  | size_type | i = `npos`
| ) |  | const

## rfind() [5/5]

size_type Glib::ustring::rfind | ( | char | c,
|  | size_type | i = `npos`
| ) |  | const

## size()

size_type Glib::ustring::size | ( |  | ) | const

Returns the number of characters in the string, not including any null-termination.

Returns
  The number of UTF-8 characters.

See also
  bytes(), empty()

## substr()

ustring Glib::ustring::substr | ( | size_type | i = `0`,
|  | size_type | n = `npos`
| ) |  | const

inline

## swap()

void Glib::ustring::swap | ( | ustring& | other | ) |

Swap contents with another string.

Parameters

  other | String to swap with.

## uppercase()

ustring Glib::ustring::uppercase | ( |  | ) | const

Returns a new UTF-8 string with all characters characters converted to their uppercase equivalent, while honoring the current locale. The resulting string may change in the number of bytes as well as in the number of characters. For instance, the German sharp s `"ß"` will be replaced by two characters `"SS"` because there is no capital `"ß"`.

## validate() [1/3]

bool Glib::ustring::validate | ( |  | ) | const

Check whether the string is valid UTF-8.

## validate() [2/3]

bool Glib::ustring::validate | ( | iterator& | first_invalid | ) |

Check whether the string is valid UTF-8.

## validate() [3/3]

bool Glib::ustring::validate | ( | const_iterator& | first_invalid | ) | const

Check whether the string is valid UTF-8.

## Friends And Related Function Documentation

## operator!=() [1/3]

bool operator!= | ( | const ustring& | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator!=() [2/3]

bool operator!= | ( | const ustring& | lhs,
|  | const char * | rhs
| ) |  |

related

## operator!=() [3/3]

bool operator!= | ( | const char * | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator+() [1/7]

ustring operator+ | ( | const ustring& | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator+() [2/7]

ustring operator+ | ( | const ustring& | lhs,
|  | const char * | rhs
| ) |  |

related

## operator+() [3/7]

ustring operator+ | ( | const char * | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator+() [4/7]

ustring operator+ | ( | const ustring& | lhs,
|  | gunichar | rhs
| ) |  |

related

## operator+() [5/7]

ustring operator+ | ( | gunichar | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator+() [6/7]

ustring operator+ | ( | const ustring& | lhs,
|  | char | rhs
| ) |  |

related

## operator+() [7/7]

ustring operator+ | ( | char | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator<() [1/3]

bool operator< | ( | const ustring& | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator<() [2/3]

bool operator< | ( | const ustring& | lhs,
|  | const char * | rhs
| ) |  |

related

## operator<() [3/3]

bool operator< | ( | const char * | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator<<() [1/2]

std::ostream & operator<< | ( | std::ostream & | os,
|  | const Glib::ustring& | utf8_string
| ) |  |

related

Stream output operator.

Exceptions

  Glib::ConvertError |

## operator<<() [2/2]

std::wostream & operator<< | ( | std::wostream & | os,
|  | const ustring& | utf8_string
| ) |  |

related

Wide stream output operator.

Exceptions

  Glib::ConvertError |

## operator<=() [1/3]

bool operator<= | ( | const ustring& | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator<=() [2/3]

bool operator<= | ( | const ustring& | lhs,
|  | const char * | rhs
| ) |  |

related

## operator<=() [3/3]

bool operator<= | ( | const char * | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator==() [1/3]

bool operator== | ( | const ustring& | lhs,
|  | const ustring& | rhs
| ) |  |

related

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

bool operator== | ( | const ustring& | lhs,
|  | const char * | rhs
| ) |  |

related

## operator==() [3/3]

bool operator== | ( | const char * | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator>() [1/3]

bool operator> | ( | const ustring& | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator>() [2/3]

bool operator> | ( | const ustring& | lhs,
|  | const char * | rhs
| ) |  |

related

## operator>() [3/3]

bool operator> | ( | const char * | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator>=() [1/3]

bool operator>= | ( | const ustring& | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator>=() [2/3]

bool operator>= | ( | const ustring& | lhs,
|  | const char * | rhs
| ) |  |

related

## operator>=() [3/3]

bool operator>= | ( | const char * | lhs,
|  | const ustring& | rhs
| ) |  |

related

## operator>>() [1/2]

std::istream & operator>> | ( | std::istream & | is,
|  | Glib::ustring& | utf8_string
| ) |  |

related

Stream input operator.

Exceptions

  Glib::ConvertError |

## operator>>() [2/2]

std::wistream & operator>> | ( | std::wistream & | is,
|  | ustring& | utf8_string
| ) |  |

related

Wide stream input operator.

Exceptions

  Glib::ConvertError |

## swap()

void swap | ( | ustring& | lhs,
|  | ustring& | rhs
| ) |  |

related

## Member Data Documentation

## npos

const size_type Glib::ustring::npos = std::string::npos

static