Main Page
Widgets
Namespaces
Book
Glib::ustring Class Reference Glib::ustring has much the same interface as std::string, but contains Unicode characters encoded as UTF-8.
More...
List of all members.
Public Types
typedef std::string::size_type size_type
typedef std::string::difference_type difference_type
typedef gunichar value_type
typedef gunichar& reference
typedef const gunichar& const_reference
typedef ustring_Iterator <
std::string::iterator > iterator
typedef ustring_Iterator <
std::string::const_iterator > const_iterator
typedef std::reverse_iterator<
iterator > reverse_iterator
typedef std::reverse_iterator<
const_iterator > const_reverse_iterator
Public Methods
ustring ()
~ustring ()
ustring (const ustring& other)
ustring& operator= (const ustring& other)
void swap (ustring& other)
ustring (const std::string& src)
ustring (const ustring& src, size_type i, size_type n=npos )
ustring (const char* src, size_type n)
ustring (const char* src)
ustring (size_type n, gunichar uc)
ustring (size_type n, char c)
template <class In> ustring (In pbegin, In pend)
ustring& operator= (const std::string& src)
ustring& operator= (const char* src)
ustring& operator= (gunichar uc)
ustring& operator= (char c)
ustring& assign (const ustring& src)
ustring& assign (const ustring& src, size_type i, size_type n)
ustring& assign (const char* src, size_type n)
ustring& assign (const char* src)
ustring& assign (size_type n, gunichar uc)
ustring& assign (size_type n, char c)
template <class In> ustring& assign (In pbegin, In pend)
ustring& operator+= (const ustring& src)
ustring& operator+= (const char* src)
ustring& operator+= (gunichar uc)
ustring& operator+= (char c)
void push_back (gunichar uc)
void push_back (char c)
ustring& append (const ustring& src)
ustring& append (const ustring& src, size_type i, size_type n)
ustring& append (const char* src, size_type n)
ustring& append (const char* src)
ustring& append (size_type n, gunichar uc)
ustring& append (size_type n, char c)
template <class In> ustring& append (In pbegin, In pend)
ustring& insert (size_type i, const ustring& src)
ustring& insert (size_type i, const ustring& src, size_type i2, size_type n)
ustring& insert (size_type i, const char* src, size_type n)
ustring& insert (size_type i, const char* src)
ustring& insert (size_type i, size_type n, gunichar uc)
ustring& insert (size_type i, size_type n, char c)
iterator insert (iterator p, gunichar uc)
iterator insert (iterator p, char c)
void insert (iterator p, size_type n, gunichar uc)
void insert (iterator p, size_type n, char c)
template <class In> void insert (iterator p, In pbegin, In pend)
ustring& replace (size_type i, size_type n, const ustring& src)
ustring& replace (size_type i, size_type n, const ustring& src, size_type i2, size_type n2)
ustring& replace (size_type i, size_type n, const char* src, size_type n2)
ustring& replace (size_type i, size_type n, const char* src)
ustring& replace (size_type i, size_type n, size_type n2, gunichar uc)
ustring& replace (size_type i, size_type n, size_type n2, char c)
ustring& replace (iterator pbegin, iterator pend, const ustring& src)
ustring& replace (iterator pbegin, iterator pend, const char* src, size_type n)
ustring& replace (iterator pbegin, iterator pend, const char* src)
ustring& replace (iterator pbegin, iterator pend, size_type n, gunichar uc)
ustring& replace (iterator pbegin, iterator pend, size_type n, char c)
template <class In> ustring& replace (iterator pbegin, iterator pend, In pbegin2, In pend2)
void clear ()
ustring& erase (size_type i, size_type n=npos )
ustring& erase ()
iterator erase (iterator p)
iterator erase (iterator pbegin, iterator pend)
int compare (const ustring& rhs) const
int compare (const char* rhs) const
int compare (size_type i, size_type n, const ustring& rhs) const
int compare (size_type i, size_type n, const ustring& rhs, size_type i2, size_type n2) const
int compare (size_type i, size_type n, const char* rhs, size_type n2) const
int compare (size_type i, size_type n, const char* rhs) const
std::string collate_key () const
std::string casefold_collate_key () const
value_type operator[] (size_type i) const
value_type at (size_type i) const
ustring substr (size_type i=0, size_type n=npos ) const
iterator begin ()
iterator end ()
const_iterator begin () const
const_iterator end () const
reverse_iterator rbegin ()
reverse_iterator rend ()
const_reverse_iterator rbegin () const
const_reverse_iterator rend () const
size_type find (const ustring& str, size_type i=0) const
size_type find (const char* str, size_type i, size_type n) const
size_type find (const char* str, size_type i=0) const
size_type find (gunichar uc, size_type i=0) const
size_type find (char c, size_type i=0) const
size_type rfind (const ustring& str, size_type i=npos ) const
size_type rfind (const char* str, size_type i, size_type n) const
size_type rfind (const char* str, size_type i=npos ) const
size_type rfind (gunichar uc, size_type i=npos ) const
size_type rfind (char c, size_type i=npos ) const
size_type find_first_of (const ustring& match, size_type i=0) const
size_type find_first_of (const char* match, size_type i, size_type n) const
size_type find_first_of (const char* match, size_type i=0) const
size_type find_first_of (gunichar uc, size_type i=0) const
size_type find_first_of (char c, size_type i=0) const
size_type find_last_of (const ustring& match, size_type i=npos ) const
size_type find_last_of (const char* match, size_type i, size_type n) const
size_type find_last_of (const char* match, size_type i=npos ) const
size_type find_last_of (gunichar uc, size_type i=npos ) const
size_type find_last_of (char c, size_type i=npos ) const
size_type find_first_not_of (const ustring& match, size_type i=0) const
size_type find_first_not_of (const char* match, size_type i, size_type n) const
size_type find_first_not_of (const char* match, size_type i=0) const
size_type find_first_not_of (gunichar uc, size_type i=0) const
size_type find_first_not_of (char c, size_type i=0) const
size_type find_last_not_of (const ustring& match, size_type i=npos ) const
size_type find_last_not_of (const char* match, size_type i, size_type n) const
size_type find_last_not_of (const char* match, size_type i=npos ) const
size_type find_last_not_of (gunichar uc, size_type i=npos ) const
size_type find_last_not_of (char c, size_type i=npos ) const
bool empty () const
size_type size () const
size_type length () const
size_type bytes () const
void resize (size_type n, gunichar uc)
void resize (size_type n, char c='\0')
size_type capacity () const
size_type max_size () const
void reserve (size_type n=0)
operator std::string () const
const std::string& raw () const
const char* data () const
const char* c_str () const
size_type copy (char* dest, size_type n, size_type i=0) const
bool validate () const
bool validate (iterator & first_invalid)
bool validate (const_iterator & first_invalid) const
bool is_ascii () const
ustring normalize (NormalizeMode mode=NORMALIZE_DEFAULT_COMPOSE) const
ustring uppercase () const
ustring lowercase () const
ustring casefold () const
Static Public Attributes
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.
std::ostream& operator<< (std::ostream& os, const Glib::ustring& utf8_string)
Stream output operator.
void swap (ustring& lhs, ustring& rhs)
bool operator== (const ustring& lhs, const ustring& rhs)
bool operator== (const ustring& lhs, const char* rhs)
bool operator== (const char* lhs, const ustring& rhs)
bool operator!= (const ustring& lhs, const ustring& rhs)
bool operator!= (const ustring& lhs, const char* rhs)
bool operator!= (const char* lhs, const ustring& rhs)
bool operator< (const ustring& lhs, const ustring& rhs)
bool operator< (const ustring& lhs, const char* rhs)
bool operator< (const char* lhs, const ustring& rhs)
bool operator> (const ustring& lhs, const ustring& rhs)
bool operator> (const ustring& lhs, const char* rhs)
bool operator> (const char* lhs, const ustring& rhs)
bool operator<= (const ustring& lhs, const ustring& rhs)
bool operator<= (const ustring& lhs, const char* rhs)
bool operator<= (const char* lhs, const ustring& rhs)
bool operator>= (const ustring& lhs, const ustring& rhs)
bool operator>= (const ustring& lhs, const char* rhs)
bool operator>= (const char* lhs, const ustring& rhs)
ustring operator+ (const ustring& lhs, const ustring& rhs)
ustring operator+ (const ustring& lhs, const char* rhs)
ustring operator+ (const char* lhs, const ustring& rhs)
ustring operator+ (const ustring& lhs, gunichar rhs)
ustring operator+ (gunichar lhs, const ustring& rhs)
ustring operator+ (const ustring& lhs, char rhs)
ustring operator+ (char lhs, const ustring& rhs)
Detailed Description
Glib::ustring has much the same interface as std::string, but contains Unicode characters encoded as UTF-8.
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 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.
In a perfect world the C++ Standard Library would contain a UTF-8 string class. Unfortunately, the C++ standard doesn't mention UTF-8 at all. 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).
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 intented (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::ostringstream output;
output.imbue(std::locale("" ));
output << percentage << " % done" ;
label->set_text(Glib::locale_to_utf8(output.str()));
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
typedef ustring_Iterator <std::string::const_iterator> Glib::ustring::const_iterator
typedef const gunichar& Glib::ustring::const_reference
typedef std::reverse_iterator<const_iterator > Glib::ustring::const_reverse_iterator
typedef std::string::difference_type Glib::ustring::difference_type
typedef gunichar& Glib::ustring::reference
typedef std::reverse_iterator<iterator > Glib::ustring::reverse_iterator
typedef std::string::size_type Glib::ustring::size_type
typedef gunichar Glib::ustring::value_type
Constructor & Destructor Documentation
Glib::ustring::ustring
(
)
Glib::ustring::~ustring
(
)
Glib::ustring::ustring
(
const ustring&
other
)
Glib::ustring::ustring
(
const std::string&
src
)
Glib::ustring::ustring
(
const char*
src ,
size_type
n
)
Glib::ustring::ustring
(
const char*
src
)
Glib::ustring::ustring
(
size_type
n ,
gunichar
uc
)
Glib::ustring::ustring
(
size_type
n ,
char
c
)
template <class In>
Glib::ustring::ustring
(
In
pbegin ,
In
pend
)
Member Function Documentation
template <class In>
ustring& Glib::ustring::append
(
In
pbegin ,
In
pend
)
ustring& Glib::ustring::append
(
size_type
n ,
char
c
)
ustring& Glib::ustring::append
(
size_type
n ,
gunichar
uc
)
ustring& Glib::ustring::append
(
const char*
src
)
ustring& Glib::ustring::append
(
const char*
src ,
size_type
n
)
ustring& Glib::ustring::append
(
const ustring&
src
)
template <class In>
ustring& Glib::ustring::assign
(
In
pbegin ,
In
pend
)
ustring& Glib::ustring::assign
(
size_type
n ,
char
c
)
ustring& Glib::ustring::assign
(
size_type
n ,
gunichar
uc
)
ustring& Glib::ustring::assign
(
const char*
src
)
ustring& Glib::ustring::assign
(
const char*
src ,
size_type
n
)
ustring& Glib::ustring::assign
(
const ustring&
src
)
No reference return; use replace() to write characters.
Exceptions:
const char* Glib::ustring::c_str
(
)
const
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.
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.
void Glib::ustring::clear
(
)
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.
int Glib::ustring::compare
(
const char*
rhs
)
const
int Glib::ustring::compare
(
const ustring&
rhs
)
const
Returns: Number of copied bytes, not characters.
const char* Glib::ustring::data
(
)
const
bool Glib::ustring::empty
(
)
const
ustring& Glib::ustring::erase
(
)
size_type Glib::ustring::find_first_not_of
(
const ustring&
match ,
size_type
i = 0
)
const
template <class In>
void Glib::ustring::insert
(
iterator
p ,
In
pbegin ,
In
pend
)
ustring& Glib::ustring::insert
(
size_type
i ,
const char*
src
)
ustring& Glib::ustring::insert
(
size_type
i ,
const ustring&
src
)
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.
ustring Glib::ustring::lowercase
(
)
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.
ustring Glib::ustring::normalize
(
NormalizeMode
mode = NORMALIZE_DEFAULT_COMPOSE
)
const
"Normalize" the Unicode character representation of the string.
Glib::ustring::operator std::string
(
)
const [inline]
ustring& Glib::ustring::operator+=
(
char
c
)
ustring& Glib::ustring::operator+=
(
gunichar
uc
)
ustring& Glib::ustring::operator+=
(
const char*
src
)
ustring& Glib::ustring::operator+=
(
const ustring&
src
)
ustring& Glib::ustring::operator=
(
char
c
)
ustring& Glib::ustring::operator=
(
gunichar
uc
)
ustring& Glib::ustring::operator=
(
const char*
src
)
ustring& Glib::ustring::operator=
(
const std::string&
src
)
ustring& Glib::ustring::operator=
(
const ustring&
other
)
No reference return; use replace() to write characters.
void Glib::ustring::push_back
(
char
c
)
void Glib::ustring::push_back
(
gunichar
uc
)
const std::string& Glib::ustring::raw
(
)
const [inline]
template <class In>
ustring& Glib::ustring::replace
(
iterator
pbegin ,
iterator
pend ,
In
pbegin2 ,
In
pend2
)
ustring& Glib::ustring::replace
(
iterator
pbegin ,
iterator
pend ,
const char*
src
)
ustring& Glib::ustring::replace
(
iterator
pbegin ,
iterator
pend ,
const ustring&
src
)
void Glib::ustring::reserve
(
size_type
n = 0
)
void Glib::ustring::resize
(
size_type
n ,
char
c = '\0'
)
void Glib::ustring::resize
(
size_type
n ,
gunichar
uc
)
void Glib::ustring::swap
(
ustring&
other
)
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 "ß"
.
bool Glib::ustring::validate
(
iterator &
first_invalid
)
bool Glib::ustring::validate
(
)
const
Check whether the string is valid UTF-8.
Friends And Related Function Documentation
bool operator!=
(
const char*
lhs ,
const ustring&
rhs
)
[related]
bool operator!=
(
const ustring&
lhs ,
const char*
rhs
)
[related]
bool operator!=
(
const ustring&
lhs ,
const ustring&
rhs
)
[related]
ustring operator+
(
char
lhs ,
const ustring&
rhs
)
[related]
ustring operator+
(
const ustring&
lhs ,
char
rhs
)
[related]
ustring operator+
(
gunichar
lhs ,
const ustring&
rhs
)
[related]
ustring operator+
(
const ustring&
lhs ,
gunichar
rhs
)
[related]
ustring operator+
(
const char*
lhs ,
const ustring&
rhs
)
[related]
ustring operator+
(
const ustring&
lhs ,
const char*
rhs
)
[related]
ustring operator+
(
const ustring&
lhs ,
const ustring&
rhs
)
[related]
bool operator<
(
const char*
lhs ,
const ustring&
rhs
)
[related]
bool operator<
(
const ustring&
lhs ,
const char*
rhs
)
[related]
bool operator<
(
const ustring&
lhs ,
const ustring&
rhs
)
[related]
std::ostream& operator<<
(
std::ostream&
os ,
const Glib::ustring&
utf8_string
)
[related]
Stream output operator.
Exceptions:
bool operator<=
(
const char*
lhs ,
const ustring&
rhs
)
[related]
bool operator<=
(
const ustring&
lhs ,
const char*
rhs
)
[related]
bool operator<=
(
const ustring&
lhs ,
const ustring&
rhs
)
[related]
bool operator==
(
const char*
lhs ,
const ustring&
rhs
)
[related]
bool operator==
(
const ustring&
lhs ,
const char*
rhs
)
[related]
bool operator==
(
const ustring&
lhs ,
const ustring&
rhs
)
[related]
bool operator>
(
const char*
lhs ,
const ustring&
rhs
)
[related]
bool operator>
(
const ustring&
lhs ,
const char*
rhs
)
[related]
bool operator>
(
const ustring&
lhs ,
const ustring&
rhs
)
[related]
bool operator>=
(
const char*
lhs ,
const ustring&
rhs
)
[related]
bool operator>=
(
const ustring&
lhs ,
const char*
rhs
)
[related]
bool operator>=
(
const ustring&
lhs ,
const ustring&
rhs
)
[related]
std::istream& operator>>
(
std::istream&
is ,
Glib::ustring&
utf8_string
)
[related]
Stream input operator.
Exceptions:
void swap
(
ustring&
lhs ,
ustring&
rhs
)
[related]
Member Data Documentation
const size_type Glib::ustring::npos = std::string::npos [static]
The documentation for this class was generated from the following file:
Generated for gtkmm by
Doxygen 1.3-rc1 © 1997-2001