glibmm  2.62.0
About: glibmm is a set of C++ bindings for glib, including cross-platform APIs such as a std::string-like UTF8 string class, string utility methods, such as a text encoding converter API, file access, and threads.
  Fossies Dox: glibmm-2.62.0.tar.xz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

Glib::ustring Class Reference

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

#include <ustring.h>

Inheritance diagram for Glib::ustring:
[legend]
Collaboration 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)
 
ustringoperator= (const ustring &other)
 
ustringoperator= (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.
ustringoperator= (const std::string &src)
 
ustringoperator= (std::string &&src)
 
ustringoperator= (const char *src)
 
ustringoperator= (gunichar uc)
 
ustringoperator= (char c)
 
ustringassign (const ustring &src)
 
ustringassign (ustring &&src)
 
ustringassign (const ustring &src, size_type i, size_type n)
 
ustringassign (const char *src, size_type n)
 
ustringassign (const char *src)
 
ustringassign (size_type n, gunichar uc)
 
ustringassign (size_type n, char c)
 
template<class In >
ustringassign (In pbegin, In pend)
 
Append to the string.
ustringoperator+= (const ustring &src)
 
ustringoperator+= (const char *src)
 
ustringoperator+= (gunichar uc)
 
ustringoperator+= (char c)
 
void push_back (gunichar uc)
 
void push_back (char c)
 
ustringappend (const ustring &src)
 
ustringappend (const ustring &src, size_type i, size_type n)
 
ustringappend (const char *src, size_type n)
 
ustringappend (const char *src)
 
ustringappend (size_type n, gunichar uc)
 
ustringappend (size_type n, char c)
 
template<class In >
ustringappend (In pbegin, In pend)
 
Insert into the string.
ustringinsert (size_type i, const ustring &src)
 
ustringinsert (size_type i, const ustring &src, size_type i2, size_type n)
 
ustringinsert (size_type i, const char *src, size_type n)
 
ustringinsert (size_type i, const char *src)
 
ustringinsert (size_type i, size_type n, gunichar uc)
 
ustringinsert (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.
ustringreplace (size_type i, size_type n, const ustring &src)
 
ustringreplace (size_type i, size_type n, const ustring &src, size_type i2, size_type n2)
 
ustringreplace (size_type i, size_type n, const char *src, size_type n2)
 
ustringreplace (size_type i, size_type n, const char *src)
 
ustringreplace (size_type i, size_type n, size_type n2, gunichar uc)
 
ustringreplace (size_type i, size_type n, size_type n2, char c)
 
ustringreplace (iterator pbegin, iterator pend, const ustring &src)
 
ustringreplace (iterator pbegin, iterator pend, const char *src, size_type n)
 
ustringreplace (iterator pbegin, iterator pend, const char *src)
 
ustringreplace (iterator pbegin, iterator pend, size_type n, gunichar uc)
 
ustringreplace (iterator pbegin, iterator pend, size_type n, char c)
 
template<class In >
ustringreplace (iterator pbegin, iterator pend, In pbegin2, In pend2)
 
Erase sub-strings.
void clear ()
 
ustringerase (size_type i, size_type n=npos)
 
ustringerase ()
 
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
 
ustring make_valid () 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)
 
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)
 

Static Public Attributes

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

Private Attributes

std::string string_
 

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.
You cannot always use Glib::ustring instead of std::string.
Glib::ustring u("a_string_with_underscores");
std::replace(u.begin(), u.end(), '_', ' '); // does not compile
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("")); // 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.
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.

Definition at line 223 of file ustring.h.

Member Typedef Documentation

◆ const_iterator

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

Definition at line 234 of file ustring.h.

◆ const_reference

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

Definition at line 231 of file ustring.h.

◆ const_reverse_iterator

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

Definition at line 239 of file ustring.h.

◆ difference_type

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

Definition at line 227 of file ustring.h.

◆ iterator

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

Definition at line 233 of file ustring.h.

◆ reference

using Glib::ustring::reference = gunichar&

Definition at line 230 of file ustring.h.

◆ reverse_iterator

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

Definition at line 238 of file ustring.h.

◆ size_type

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

Definition at line 226 of file ustring.h.

◆ value_type

using Glib::ustring::value_type = gunichar

Definition at line 229 of file ustring.h.

Constructor & Destructor Documentation

◆ ustring() [1/11]

Glib::ustring::ustring ( )

Default constructor, which creates an empty string.

Definition at line 276 of file ustring.cc.

Referenced by append(), compare(), insert(), and replace().

◆ ~ustring()

Glib::ustring::~ustring ( )
noexcept

Definition at line 331 of file ustring.cc.

◆ ustring() [2/11]

Glib::ustring::ustring ( const ustring other)

Construct a ustring as a copy of another ustring.

Parameters
otherA source string.

Definition at line 280 of file ustring.cc.

◆ ustring() [3/11]

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

Construct a ustring by moving from another ustring.

Parameters
otherA source string.

Definition at line 284 of file ustring.cc.

◆ ustring() [4/11]

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

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

Parameters
srcA source std::string containing text encoded as UTF-8.

Definition at line 323 of file ustring.cc.

◆ ustring() [5/11]

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

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

Parameters
srcA source std::string containing text encoded as UTF-8.

Definition at line 327 of file ustring.cc.

◆ ustring() [6/11]

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

Construct a ustring as a copy of a substring.

Parameters
srcSource ustring.
iIndex of first character to copy from.
nNumber of UTF-8 characters to copy (defaults to copying the remainder).

Definition at line 288 of file ustring.cc.

References string_.

◆ ustring() [7/11]

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

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

Parameters
srcSource C string encoded as UTF-8.
nNumber of UTF-8 characters to copy.

Definition at line 294 of file ustring.cc.

◆ ustring() [8/11]

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

Construct a ustring as a copy of a C string.

Parameters
srcSource C string encoded as UTF-8.

Definition at line 298 of file ustring.cc.

◆ ustring() [9/11]

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

Construct a ustring as multiple characters.

Parameters
nNumber of characters.
ucUCS-4 code point to use.

Definition at line 302 of file ustring.cc.

References string_.

◆ ustring() [10/11]

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

Construct a ustring as multiple characters.

Parameters
nNumber of characters.
cASCII character to use.

Definition at line 319 of file ustring.cc.

◆ ustring() [11/11]

template<class In >
Glib::ustring::ustring ( In  pbegin,
In  pend 
)

Construct a ustring as a copy of a range.

Parameters
pbeginStart of range.
pendEnd of range.

Member Function Documentation

◆ append() [1/7]

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

Definition at line 517 of file ustring.cc.

References string_.

◆ append() [2/7]

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

Definition at line 510 of file ustring.cc.

References string_.

◆ append() [3/7]

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

Definition at line 495 of file ustring.cc.

References string_.

Referenced by resize().

◆ append() [4/7]

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

Definition at line 502 of file ustring.cc.

References string_.

◆ append() [5/7]

template<class In >
ustring& Glib::ustring::append ( In  pbegin,
In  pend 
)

◆ append() [6/7]

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

Definition at line 531 of file ustring.cc.

References string_.

◆ append() [7/7]

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

Definition at line 524 of file ustring.cc.

References string_, and ustring().

◆ assign() [1/8]

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

Definition at line 425 of file ustring.cc.

References string_.

◆ assign() [2/8]

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

Definition at line 418 of file ustring.cc.

References string_.

◆ assign() [3/8]

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

◆ assign() [4/8]

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

Definition at line 410 of file ustring.cc.

References string_.

◆ assign() [5/8]

template<class In >
ustring& Glib::ustring::assign ( In  pbegin,
In  pend 
)

◆ assign() [6/8]

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

Definition at line 440 of file ustring.cc.

References string_.

◆ assign() [7/8]

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

Definition at line 432 of file ustring.cc.

References string_.

◆ assign() [8/8]

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

Definition at line 403 of file ustring.cc.

References string_.

◆ at()

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

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

Exceptions
std::out_of_range

Definition at line 785 of file ustring.cc.

References string_.

◆ begin() [1/2]

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

Definition at line 796 of file ustring.cc.

References string_.

◆ begin() [2/2]

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

Definition at line 808 of file ustring.cc.

References string_.

◆ bytes()

ustring::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()

Definition at line 1124 of file ustring.cc.

References string_.

Referenced by Glib::Markup::escape_text(), Glib::filename_from_utf8(), Glib::KeyFile::load_from_data(), Glib::locale_from_utf8(), Glib::PatternSpec::match(), Glib::Markup::ParseContext::parse(), and Glib::IOChannel::write().

◆ c_str()

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

Definition at line 1176 of file ustring.cc.

References string_.

Referenced by Gio::ActionGroup::action_added(), Gio::ActionGroup::action_enabled_changed(), Gio::ActionGroup::action_removed(), Gio::ActionGroup::action_state_changed(), Gio::RemoteActionGroup::activate_action(), Gio::ActionGroup::activate_action(), Gio::RemoteActionGroup::activate_action_vfunc(), Gio::SocketClient::add_application_proxy(), Gio::Notification::add_button(), Gio::Notification::add_button_variant(), Gio::Application::add_main_option_entry_private(), Gio::Menu::append(), Gio::Menu::append_section(), Gio::Menu::append_submenu(), Glib::TimeVal::assign_from_iso8601(), Gio::Settings::bind(), Gio::Settings::bind_writable(), Gio::DBus::Proxy::call(), Gio::DBus::Connection::call(), Gio::DBus::Proxy::call_sync(), Gio::DBus::Connection::call_sync(), Gio::RemoteActionGroup::change_action_state(), Gio::ActionGroup::change_action_state(), Gio::RemoteActionGroup::change_action_state_vfunc(), Glib::Regex::check_replacement(), Glib::SignalProxyDetailed::connect_impl_(), Gio::SocketClient::connect_to_host(), Gio::SocketClient::connect_to_host_async(), Gio::SocketClient::connect_to_service(), Gio::SocketClient::connect_to_service_async(), Gio::SocketClient::connect_to_uri(), Gio::SocketClient::connect_to_uri_async(), Glib::VariantDict::contains(), Gio::content_type_equals(), Gio::content_type_from_mime_type(), Gio::content_type_is_a(), Glib::convert_with_fallback(), Glib::TimeZone::create(), Glib::Regex::create(), Glib::Variant< Glib::ustring >::create(), Glib::Variant< Glib::DBusObjectPathString >::create(), Glib::Variant< Glib::DBusSignatureString >::create(), Gio::Settings::create_action(), Gio::ApplicationCommandLine::create_file_for_arg(), Gio::File::create_for_parse_name(), Gio::DBus::NodeInfo::create_for_xml(), Glib::DateTime::create_from_iso8601(), Gio::DBus::Message::create_method_call(), Gio::DBus::Message::create_method_error_literal(), Gio::DBus::Message::create_signal(), Glib::SignalProxyDetailed::emission_stop(), Gio::DBus::Connection::emit_signal(), Glib::MatchInfo::expand_references(), Gio::DBus::Connection::export_action_group(), Gio::DBus::InterfaceSkeleton::export_interface_skeleton(), Gio::DBus::Connection::export_menu_model(), Glib::filename_from_uri(), Glib::filename_to_uri(), Glib::DateTime::format(), Gio::DBus::MenuModel::get(), Gio::DBus::ActionGroup::get(), Gio::ActionGroup::get_action_enabled(), Gio::DesktopAppInfo::get_action_name(), Gio::ActionGroup::get_action_parameter_type(), Gio::ActionGroup::get_action_state(), Gio::ActionGroup::get_action_state_hint(), Gio::ActionGroup::get_action_state_hint_variant(), Gio::ActionGroup::get_action_state_type(), Gio::ActionGroup::get_action_state_variant(), Gio::MenuItem::get_attribute(), Gio::MenuItem::get_attribute_value(), Gio::DesktopAppInfo::get_boolean(), Gio::Settings::get_boolean(), Glib::KeyFile::get_boolean(), Gio::DBus::Proxy::get_cached_property(), Gio::File::get_child_for_display_name(), Glib::KeyFile::get_comment(), Gio::Proxy::get_default_for_protocol(), Gio::Settings::get_default_value(), Gio::Settings::get_double(), Glib::KeyFile::get_double(), Glib::KeyFile::get_double_list(), Gio::Settings::get_enum(), Gio::Settings::get_flags(), Gio::Settings::get_int(), Gio::Settings::get_int64(), Glib::KeyFile::get_int64(), Glib::KeyFile::get_integer(), Gio::DBus::Object::get_interface(), Gio::DBus::ObjectManager::get_interface(), Gio::DBus::Object::get_interface_vfunc(), Gio::DBus::ObjectManager::get_interface_vfunc(), Gio::MenuItem::get_link(), Glib::KeyFile::get_locale_for_key(), Gio::DesktopAppInfo::get_locale_string(), Glib::KeyFile::get_locale_string(), Glib::KeyFile::get_locale_string_list(), Gio::DBus::ObjectManager::get_object(), Gio::DBus::ObjectManager::get_object_vfunc(), Glib::ObjectBase::get_property_value(), Gio::DesktopAppInfo::get_string(), Glib::KeyFile::get_string(), Gio::Settings::get_string(), Gio::Settings::get_string_array(), Gio::Settings::get_uint(), Gio::Settings::get_uint64(), Glib::KeyFile::get_uint64(), Gio::Settings::get_user_value(), Gio::Settings::get_value(), Glib::KeyFile::get_value(), Gio::ActionGroup::has_action(), Glib::KeyFile::has_group(), Gio::DesktopAppInfo::has_key(), Glib::KeyFile::has_key(), Gio::hostname_is_ascii_encoded(), Gio::hostname_is_ip_address(), Gio::hostname_is_non_ascii(), Gio::hostname_to_ascii(), Gio::hostname_to_unicode(), Gio::Application::id_is_valid(), Gio::Menu::insert(), Gio::Menu::insert_section(), Gio::Menu::insert_submenu(), Glib::VariantDict::insert_value_variant(), Gio::DesktopAppInfo::launch_action(), Glib::KeyFile::load_from_data(), Gio::SettingsSchemaSource::lookup(), Gio::SimpleActionGroup::lookup(), Gio::ProxyResolver::lookup(), Gio::ActionMap::lookup_action(), Gio::ProxyResolver::lookup_async(), Gio::Resolver::lookup_by_name(), Gio::Resolver::lookup_by_name_async(), Gio::TlsDatabase::lookup_certificate_for_handle(), Gio::TlsDatabase::lookup_certificate_for_handle_async(), Gio::TlsDatabase::lookup_certificate_for_handle_async_vfunc(), Gio::TlsDatabase::lookup_certificate_for_handle_vfunc(), Gio::Resolver::lookup_records(), Gio::Resolver::lookup_service(), Gio::Resolver::lookup_service_async(), Glib::VariantDict::lookup_value_variant(), Glib::PatternSpec::match(), Glib::Regex::match_simple(), Gio::Action::name_is_valid(), Gio::ActionGroup::on_action_added(), Gio::ActionGroup::on_action_enabled_changed(), Gio::ActionGroup::on_action_removed(), Gio::ActionGroup::on_action_state_changed(), Gio::MountOperation::on_ask_password(), Gio::MountOperation::on_ask_question(), Gio::Settings::on_changed(), Gio::DBus::ObjectManagerClient::on_interface_proxy_signal(), Gio::Application::on_open(), Gio::DBus::Proxy::on_signal(), Gio::Settings::on_writable_changed(), Gio::Application::open(), Gio::Action::parse_detailed_name_variant(), Gio::Menu::prepend(), Gio::Menu::prepend_section(), Gio::Menu::prepend_submenu(), Gio::ApplicationCommandLine::print(), Gio::Action::print_detailed_name_variant(), Gio::ApplicationCommandLine::printerr(), Gio::ActionGroup::query_action(), Gio::Settings::range_check(), Gio::DBus::Connection::register_object(), Gio::DBus::Connection::register_subtree(), Glib::VariantDict::remove(), Gio::SimpleActionGroup::remove(), Gio::ActionMap::remove_action(), Glib::KeyFile::remove_comment(), Glib::KeyFile::remove_group(), Gio::DBus::ObjectSkeleton::remove_interface(), Glib::KeyFile::remove_key(), Glib::Regex::replace(), Glib::Regex::replace_literal(), Gio::Settings::reset(), Gio::DBus::MethodInvocation::return_dbus_error(), Gio::DBus::MethodInvocation::return_error(), Glib::Value< Glib::ustring >::set(), Gio::MenuItem::set_action(), Gio::MenuItem::set_action_and_target(), Glib::set_application_name(), Gio::MenuItem::set_attribute(), Gio::MenuItem::set_attribute_value(), Gio::Notification::set_body(), Gio::Settings::set_boolean(), Glib::KeyFile::set_boolean(), Glib::KeyFile::set_boolean_list(), Gio::DBus::Proxy::set_cached_property(), Glib::KeyFile::set_comment(), Gio::Notification::set_default_action(), Gio::Notification::set_default_action_variant(), Gio::TlsPassword::set_description(), Glib::OptionContext::set_description(), Gio::DBus::Message::set_destination(), Gio::MenuItem::set_detailed_action(), Gio::File::set_display_name(), Gio::File::set_display_name_async(), Gio::MountOperation::set_domain(), Gio::Settings::set_double(), Glib::KeyFile::set_double(), Glib::KeyFile::set_double_list(), Gio::Settings::set_enum(), Gio::DBus::Message::set_error_name(), Gio::Settings::set_flags(), Gio::Application::set_id(), Gio::Settings::set_int(), Gio::Settings::set_int64(), Glib::KeyFile::set_int64(), Glib::KeyFile::set_integer(), Glib::KeyFile::set_integer_list(), Gio::DBus::Message::set_interface(), Gio::MenuItem::set_label(), Gio::MenuItem::set_link(), Glib::KeyFile::set_locale_string(), Glib::KeyFile::set_locale_string_list(), Gio::DBus::Message::set_member(), Gio::DBus::ObjectSkeleton::set_object_path(), Gio::Application::set_option_context_description(), Gio::Application::set_option_context_parameter_string(), Gio::Application::set_option_context_summary(), Glib::Date::set_parse(), Gio::MountOperation::set_password(), Gio::DBus::Message::set_path(), Glib::ObjectBase::set_property_value(), Gio::NetworkService::set_scheme(), Gio::DBus::Message::set_sender(), Gio::DBus::Message::set_signature(), Gio::Settings::set_string(), Glib::KeyFile::set_string(), Gio::Settings::set_string_array(), Glib::KeyFile::set_string_list(), Glib::OptionContext::set_summary(), Gio::Notification::set_title(), Glib::OptionGroup::set_translation_domain(), Glib::OptionContext::set_translation_domain(), Gio::Settings::set_uiint(), Gio::Settings::set_uint(), Gio::Settings::set_uint64(), Glib::KeyFile::set_uint64(), Gio::MountOperation::set_username(), Gio::Settings::set_value(), Glib::KeyFile::set_value(), Gio::TlsPassword::set_warning(), Gio::AppLaunchContext::setenv(), Glib::OptionContextPrivate::SignalProxy_translate_gtk_callback(), Glib::Regex::split_simple(), Gio::DBus::ObjectManagerServer::unexport(), Gio::AppLaunchContext::unsetenv(), Gio::TlsDatabase::verify_chain(), Gio::TlsDatabase::verify_chain_async(), Gio::TlsDatabase::verify_chain_async_vfunc(), and Gio::TlsDatabase::verify_chain_vfunc().

◆ capacity()

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

Definition at line 1130 of file ustring.cc.

References string_.

◆ 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.

Definition at line 1262 of file ustring.cc.

References string_.

◆ 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.

Definition at line 1274 of file ustring.cc.

References string_.

◆ cbegin()

ustring::const_iterator Glib::ustring::cbegin ( ) const
Since @PACKAGE_NAME@ 2.52:

Definition at line 844 of file ustring.cc.

References string_.

◆ cend()

ustring::const_iterator Glib::ustring::cend ( ) const
Since @PACKAGE_NAME@ 2.52:

Definition at line 850 of file ustring.cc.

References string_.

◆ clear()

void Glib::ustring::clear ( )

Definition at line 702 of file ustring.cc.

References string_.

◆ 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.

Definition at line 1268 of file ustring.cc.

References string_.

◆ compare() [1/6]

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

Definition at line 746 of file ustring.cc.

References string_.

◆ compare() [2/6]

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

Definition at line 740 of file ustring.cc.

References string_.

Referenced by operator!=(), operator<(), operator<=(), operator==(), operator>(), and operator>=().

◆ compare() [3/6]

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

Definition at line 772 of file ustring.cc.

References ustring().

◆ compare() [4/6]

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

Definition at line 765 of file ustring.cc.

References ustring().

◆ compare() [5/6]

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

Definition at line 752 of file ustring.cc.

References ustring().

◆ compare() [6/6]

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

Definition at line 758 of file ustring.cc.

References ustring().

◆ compose() [1/10]

template<class T1 >
static ustring Glib::ustring::compose ( const ustring fmt)
inlinestatic

◆ compose() [2/10]

template<class T1 >
static ustring Glib::ustring::compose ( const ustring fmt,
const T1 &  a1 
)
inlinestatic

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:
const int percentage = 50;
const ustring text = ustring::compose("%1%% done", percentage);
Parameters
fmtA template string in qt-format.
a1The argument to substitute for "%1".
Returns
The substituted message string.
Exceptions
Glib::ConvertError
Since @PACKAGE_NAME@ 2.16:

◆ compose() [3/10]

template<class T1 , class T2 >
static ustring Glib::ustring::compose ( const ustring fmt,
const T1 &  a1,
const T2 &  a2 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ copy()

ustring::size_type Glib::ustring::copy ( char *  dest,
ustring::size_type  n,
ustring::size_type  i = 0 
) const
Returns
Number of copied bytes, not characters.

Definition at line 1185 of file ustring.cc.

References string_.

◆ data()

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

◆ empty()

◆ end() [1/2]

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

Definition at line 802 of file ustring.cc.

References string_.

◆ end() [2/2]

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

Definition at line 814 of file ustring.cc.

References string_.

◆ erase() [1/4]

ustring & Glib::ustring::erase ( )

Definition at line 716 of file ustring.cc.

References string_.

Referenced by resize().

◆ erase() [2/4]

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

Definition at line 723 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ erase() [3/4]

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

Definition at line 732 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ erase() [4/4]

◆ find() [1/5]

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

Definition at line 884 of file ustring.cc.

References string_.

◆ find() [2/5]

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

Definition at line 864 of file ustring.cc.

References string_.

◆ find() [3/5]

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

Definition at line 871 of file ustring.cc.

References string_.

◆ find() [4/5]

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

Definition at line 858 of file ustring.cc.

References string_.

Referenced by find_first_of().

◆ find() [5/5]

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

Definition at line 877 of file ustring.cc.

References string_.

◆ find_first_not_of() [1/5]

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

Definition at line 1029 of file ustring.cc.

References npos, and string_.

◆ find_first_not_of() [2/5]

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

Definition at line 996 of file ustring.cc.

References string_.

◆ find_first_not_of() [3/5]

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

Definition at line 1002 of file ustring.cc.

References string_.

◆ find_first_not_of() [4/5]

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

Definition at line 990 of file ustring.cc.

References string_.

◆ find_first_not_of() [5/5]

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

Definition at line 1011 of file ustring.cc.

References npos, and string_.

◆ find_first_of() [1/5]

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

Definition at line 950 of file ustring.cc.

References find().

◆ find_first_of() [2/5]

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

Definition at line 932 of file ustring.cc.

References string_.

◆ find_first_of() [3/5]

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

Definition at line 938 of file ustring.cc.

References string_.

◆ find_first_of() [4/5]

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

Definition at line 926 of file ustring.cc.

References string_.

◆ find_first_of() [5/5]

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

Definition at line 944 of file ustring.cc.

References find().

◆ find_last_not_of() [1/5]

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

Definition at line 1086 of file ustring.cc.

References npos, and string_.

◆ find_last_not_of() [2/5]

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

Definition at line 1055 of file ustring.cc.

References string_.

◆ find_last_not_of() [3/5]

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

Definition at line 1061 of file ustring.cc.

References string_.

◆ find_last_not_of() [4/5]

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

Definition at line 1049 of file ustring.cc.

References string_.

◆ find_last_not_of() [5/5]

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

Definition at line 1070 of file ustring.cc.

References npos, and string_.

◆ find_last_of() [1/5]

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

Definition at line 982 of file ustring.cc.

References rfind().

◆ find_last_of() [2/5]

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

Definition at line 964 of file ustring.cc.

References string_.

◆ find_last_of() [3/5]

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

Definition at line 970 of file ustring.cc.

References string_.

◆ find_last_of() [4/5]

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

Definition at line 958 of file ustring.cc.

References string_.

◆ find_last_of() [5/5]

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

Definition at line 976 of file ustring.cc.

References rfind().

◆ format() [1/8]

template<class T1 >
static ustring Glib::ustring::format ( const T1 &  a1)
inlinestatic

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.

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.
// Insert leading zeroes to fill in at least six digits
ustring text = ustring::format(std::setfill(L'0'), std::setw(6), 123);
Parameters
a1A streamable value or an I/O manipulator.
Returns
The string representation of the argument stream.
Exceptions
Glib::ConvertError
Since @PACKAGE_NAME@ 2.16:

◆ format() [2/8]

template<class T1 , class T2 >
static ustring Glib::ustring::format ( const T1 &  a1,
const T2 &  a2 
)
inlinestatic

◆ format() [3/8]

template<class T1 , class T2 , class T3 >
static ustring Glib::ustring::format ( const T1 &  a1,
const T2 &  a2,
const T3 &  a3 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ 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 
)
inlinestatic

◆ insert() [1/11]

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

Definition at line 593 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ insert() [2/11]

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

Definition at line 584 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ insert() [3/11]

template<class In >
void Glib::ustring::insert ( iterator  p,
In  pbegin,
In  pend 
)

◆ insert() [4/11]

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

Definition at line 605 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ insert() [5/11]

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

Definition at line 599 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), string_, and ustring().

◆ insert() [6/11]

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

Definition at line 563 of file ustring.cc.

References string_.

◆ insert() [7/11]

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

Definition at line 556 of file ustring.cc.

References string_.

◆ insert() [8/11]

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

Definition at line 540 of file ustring.cc.

References string_.

◆ insert() [9/11]

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

Definition at line 547 of file ustring.cc.

References string_.

◆ insert() [10/11]

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

Definition at line 577 of file ustring.cc.

References string_.

◆ insert() [11/11]

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

Definition at line 570 of file ustring.cc.

References string_, and ustring().

◆ 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.

Definition at line 1228 of file ustring.cc.

References string_.

◆ length()

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

This is the same as size().

Definition at line 1117 of file ustring.cc.

References string_.

◆ 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.

Definition at line 1256 of file ustring.cc.

References string_.

◆ make_valid()

ustring Glib::ustring::make_valid ( ) const

Return a copy that is a valid UTF-8 string replacing invalid bytes in the original with Unicode replacement character (U+FFFD). If the string is valid, return a copy of it.

Definition at line 1222 of file ustring.cc.

References string_.

◆ max_size()

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

Definition at line 1136 of file ustring.cc.

References string_.

◆ normalize()

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

"Normalize" the Unicode character representation of the string.

Definition at line 1243 of file ustring.cc.

References string_.

◆ operator std::string()

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

◆ operator+=() [1/4]

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

Definition at line 471 of file ustring.cc.

References string_.

◆ operator+=() [2/4]

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

Definition at line 456 of file ustring.cc.

References string_.

◆ operator+=() [3/4]

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

Definition at line 449 of file ustring.cc.

References string_.

◆ operator+=() [4/4]

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

Definition at line 463 of file ustring.cc.

References string_.

◆ operator=() [1/7]

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

Definition at line 387 of file ustring.cc.

References string_.

◆ operator=() [2/7]

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

Definition at line 372 of file ustring.cc.

References string_.

◆ operator=() [3/7]

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

Definition at line 358 of file ustring.cc.

References string_.

◆ operator=() [4/7]

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

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

Parameters
otherA source string.

Definition at line 344 of file ustring.cc.

References string_.

◆ operator=() [5/7]

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

Definition at line 379 of file ustring.cc.

References string_.

◆ operator=() [6/7]

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

Definition at line 365 of file ustring.cc.

References string_.

◆ operator=() [7/7]

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

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

Parameters
otherA source string.

Definition at line 351 of file ustring.cc.

References string_.

◆ operator[]()

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

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

Definition at line 779 of file ustring.cc.

References string_.

◆ push_back() [1/2]

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

Definition at line 487 of file ustring.cc.

References string_.

◆ push_back() [2/2]

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

Definition at line 480 of file ustring.cc.

References string_.

◆ raw()

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

◆ rbegin() [1/2]

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

Definition at line 820 of file ustring.cc.

References string_.

◆ rbegin() [2/2]

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

Definition at line 832 of file ustring.cc.

References string_.

◆ rend() [1/2]

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

Definition at line 826 of file ustring.cc.

References string_.

◆ rend() [2/2]

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

Definition at line 838 of file ustring.cc.

References string_.

◆ replace() [1/12]

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

Definition at line 678 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ replace() [2/12]

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

Definition at line 670 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ replace() [3/12]

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

Definition at line 663 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ replace() [4/12]

template<class In >
ustring& Glib::ustring::replace ( iterator  pbegin,
iterator  pend,
In  pbegin2,
In  pend2 
)

◆ replace() [5/12]

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

Definition at line 693 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), and string_.

◆ replace() [6/12]

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

Definition at line 685 of file ustring.cc.

References Glib::ustring_Iterator< T >::base(), string_, and ustring().

◆ replace() [7/12]

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

Definition at line 639 of file ustring.cc.

References string_.

◆ replace() [8/12]

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

Definition at line 631 of file ustring.cc.

References string_.

◆ replace() [9/12]

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

Definition at line 613 of file ustring.cc.

References string_.

◆ replace() [10/12]

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

Definition at line 621 of file ustring.cc.

References string_.

◆ replace() [11/12]

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

Definition at line 655 of file ustring.cc.

References string_.

◆ replace() [12/12]

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

Definition at line 647 of file ustring.cc.

References string_.

◆ reserve()

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

Definition at line 1162 of file ustring.cc.

References string_.

◆ resize() [1/2]

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

Definition at line 1152 of file ustring.cc.

References erase(), npos, size(), and string_.

◆ resize() [2/2]

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

Definition at line 1142 of file ustring.cc.

References append(), erase(), npos, and size().

◆ rfind() [1/5]

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

Definition at line 918 of file ustring.cc.

References string_.

◆ rfind() [2/5]

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

Definition at line 898 of file ustring.cc.

References string_.

◆ rfind() [3/5]

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

Definition at line 905 of file ustring.cc.

References string_.

◆ rfind() [4/5]

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

Definition at line 892 of file ustring.cc.

References string_.

Referenced by find_last_of().

◆ rfind() [5/5]

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

Definition at line 911 of file ustring.cc.

References string_.

◆ size()

ustring::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()

Definition at line 1110 of file ustring.cc.

References string_.

Referenced by resize().

◆ sprintf() [1/4]

static ustring Glib::ustring::sprintf ( const char *  fmt)
inlinestatic

Overload of sprintf() for a format string only, which returns it unchanged and avoids creating a temporary ustring as the argument.

Parameters
fmtThe string
Returns
The same string, as a ustring.
Since @PACKAGE_NAME@ 2.62:

◆ sprintf() [2/4]

template<class... Ts>
static ustring Glib::ustring::sprintf ( const char *  fmt,
const Ts &...  args 
)
inlinestatic

Overload of sprintf() taking a string literal.

The main benefit of this is not constructing a temporary ustring if fmt is a string literal. A secondary effect is that it might encourage compilers to check if the given format fmt matches the variadic arguments args. The latter effect is a convenience at best; you must not rely on it to find errors in your code, as your compiler might not always be able to do so.

Parameters
fmtThe template string, in the format used by printf() et al.
argsA set of arguments having the count/types/order required by fmt.
Returns
The substituted string.
Since @PACKAGE_NAME@ 2.62:

◆ sprintf() [3/4]

static ustring Glib::ustring::sprintf ( const ustring fmt)
inlinestatic

Overload of sprintf() for a format string only, which returns it unchanged.

If no args to be substituted are given, there is nothing to do, so the fmt string is returned as-is without substitution. This is an obvious case of mismatched format/args that we can check. Not doing so causes warnings/errors with common compiler options, as it is a security risk.

Parameters
fmtThe string
Returns
The same string.
Since @PACKAGE_NAME@ 2.62:

◆ sprintf() [4/4]

template<class... Ts>
static ustring Glib::ustring::sprintf ( const ustring fmt,
const Ts &...  args 
)
inlinestatic

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 name = Glib::ustring{"Dennis"};
const auto your_cows = 3;
const auto my_cows = 11;
const auto cow_percentage = 100.0 * your_cows / my_cows;
const auto text = Glib::ustring::sprintf(
"%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;
// Hi, Dennis! You have 3 cows. That's about 27.27% of the 11 cows I have.
Parameters
fmtThe template string, in the format used by printf() et al.
argsA set of arguments having the count/types/order required by fmt.
Returns
The substituted string.
Since @PACKAGE_NAME@ 2.62:

◆ 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
otherString to swap with.

Definition at line 336 of file ustring.cc.

References string_.

Referenced by swap().

◆ 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 "ß".

Definition at line 1250 of file ustring.cc.

References string_.

◆ validate() [1/3]

bool Glib::ustring::validate ( ) const

Check whether the string is valid UTF-8.

Definition at line 1194 of file ustring.cc.

References string_.

◆ validate() [2/3]

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

Check whether the string is valid UTF-8.

Definition at line 1211 of file ustring.cc.

References string_.

◆ validate() [3/3]

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

Check whether the string is valid UTF-8.

Definition at line 1200 of file ustring.cc.

References string_.

Friends And Related Function Documentation

◆ operator!=() [1/3]

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

Definition at line 1723 of file ustring.h.

References compare().

◆ operator!=() [2/3]

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

Definition at line 1716 of file ustring.h.

References compare().

◆ operator!=() [3/3]

bool operator!= ( const ustring lhs,
const ustring rhs 
)
related

Definition at line 1709 of file ustring.h.

References compare().

◆ operator+() [1/7]

ustring operator+ ( char  lhs,
const ustring rhs 
)
related

Definition at line 1889 of file ustring.h.

◆ operator+() [2/7]

ustring operator+ ( const char *  lhs,
const ustring rhs 
)
related

Definition at line 1853 of file ustring.h.

◆ operator+() [3/7]

ustring operator+ ( const ustring lhs,
char  rhs 
)
related

Definition at line 1880 of file ustring.h.

◆ operator+() [4/7]

ustring operator+ ( const ustring lhs,
const char *  rhs 
)
related

Definition at line 1844 of file ustring.h.

◆ operator+() [5/7]

ustring operator+ ( const ustring lhs,
const ustring rhs 
)
related

Definition at line 1835 of file ustring.h.

◆ operator+() [6/7]

ustring operator+ ( const ustring lhs,
gunichar  rhs 
)
related

Definition at line 1862 of file ustring.h.

◆ operator+() [7/7]

ustring operator+ ( gunichar  lhs,
const ustring rhs 
)
related

Definition at line 1871 of file ustring.h.

◆ operator<() [1/3]

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

Definition at line 1744 of file ustring.h.

References compare().

◆ operator<() [2/3]

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

Definition at line 1737 of file ustring.h.

References compare().

◆ operator<() [3/3]

bool operator< ( const ustring lhs,
const ustring rhs 
)
related

Definition at line 1730 of file ustring.h.

References compare().

◆ operator<<() [1/2]

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

Stream output operator.

Exceptions
Glib::ConvertError

Definition at line 1424 of file ustring.cc.

◆ operator<<() [2/2]

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

Wide stream output operator.

Exceptions
Glib::ConvertError

Definition at line 1483 of file ustring.cc.

◆ operator<=() [1/3]

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

Definition at line 1786 of file ustring.h.

References compare().

◆ operator<=() [2/3]

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

Definition at line 1779 of file ustring.h.

References compare().

◆ operator<=() [3/3]

bool operator<= ( const ustring lhs,
const ustring rhs 
)
related

Definition at line 1772 of file ustring.h.

References compare().

◆ operator==() [1/3]

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

Definition at line 1702 of file ustring.h.

References compare().

◆ operator==() [2/3]

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

Definition at line 1695 of file ustring.h.

References compare().

◆ operator==() [3/3]

bool operator== ( const ustring lhs,
const ustring rhs 
)
related

Definition at line 1688 of file ustring.h.

References compare().

◆ operator>() [1/3]

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

Definition at line 1765 of file ustring.h.

References compare().

◆ operator>() [2/3]

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

Definition at line 1758 of file ustring.h.

References compare().

◆ operator>() [3/3]

bool operator> ( const ustring lhs,
const ustring rhs 
)
related

Definition at line 1751 of file ustring.h.

References compare().

◆ operator>=() [1/3]

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

Definition at line 1807 of file ustring.h.

References compare().

◆ operator>=() [2/3]

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

Definition at line 1800 of file ustring.h.

References compare().

◆ operator>=() [3/3]

bool operator>= ( const ustring lhs,
const ustring rhs 
)
related

Definition at line 1793 of file ustring.h.

References compare().

◆ operator>>() [1/2]

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

Stream input operator.

Exceptions
Glib::ConvertError

Definition at line 1403 of file ustring.cc.

◆ operator>>() [2/2]

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

Wide stream input operator.

Exceptions
Glib::ConvertError

Definition at line 1449 of file ustring.cc.

◆ swap()

void swap ( ustring lhs,
ustring rhs 
)
related

Definition at line 1679 of file ustring.h.

References swap().

Member Data Documentation

◆ npos

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

Definition at line 258 of file ustring.h.

Referenced by find_first_not_of(), find_last_not_of(), and resize().

◆ string_


The documentation for this class was generated from the following files:
Glib::ustring::sprintf
static ustring sprintf(const ustring &fmt, const Ts &... args)
Glib::ustring::format
static ustring format(const T1 &a1)
Glib::ustring::ustring
ustring()
Definition: ustring.cc:276
docextract_to_xml.name
name
Definition: docextract_to_xml.py:134
Glib::ustring
Glib::ustring has much the same interface as std::string, but contains Unicode characters encoded as ...
Definition: ustring.h:223
Glib::ustring::compose
static ustring compose(const ustring &fmt)
Glib::locale_to_utf8
Glib::ustring locale_to_utf8(const std::string &opsys_string)
Convert from the current locale's encoding to UTF-8.
Definition: convert.cc:170