glibmm 2.80.0
Classes | Functions
Character Set Conversion

Utility functions for converting strings between different character sets. More...

Classes

class  Glib::ConvertError
 Exception class for charset conversion errors. More...
 
class  Glib::IConv
 Thin iconv() wrapper. More...
 

Functions

bool Glib::get_charset ()
 Get the charset used by the current locale.
 
bool Glib::get_charset (std::string & charset)
 Get the charset used by the current locale.
 
std::string Glib::convert (const std::string & str, const std::string & to_codeset, const std::string & from_codeset)
 Convert from one encoding to another.
 
std::string Glib::convert_with_fallback (const std::string & str, const std::string & to_codeset, const std::string & from_codeset)
 Converts a string from one character set to another, possibly including fallback sequences for characters not representable in the output.
 
std::string Glib::convert_with_fallback (const std::string & str, const std::string & to_codeset, const std::string & from_codeset, const Glib::ustring & fallback)
 Converts a string from one character set to another, possibly including fallback sequences for characters not representable in the output.
 
Glib::ustring Glib::locale_to_utf8 (const std::string & opsys_string)
 Convert from the current locale's encoding to UTF-8.
 
std::string Glib::locale_from_utf8 (const Glib::ustring & utf8_string)
 Convert from UTF-8 to the current locale's encoding.
 
Glib::ustring Glib::filename_to_utf8 (const std::string & opsys_string)
 Converts a string which is in the encoding used for filenames into a UTF-8 string.
 
std::string Glib::filename_from_utf8 (const Glib::ustring & utf8_string)
 Converts a string from UTF-8 to the encoding used for filenames.
 
std::string Glib::filename_from_uri (const Glib::ustring & uri, Glib::ustring & hostname)
 Converts an escaped UTF-8 encoded URI to a local filename in the encoding used for filenames.
 
std::string Glib::filename_from_uri (const Glib::ustring & uri)
 Converts an escaped UTF-8 encoded URI to a local filename in the encoding used for filenames.
 
Glib::ustring Glib::filename_to_uri (const std::string & filename, const Glib::ustring & hostname)
 Converts an absolute filename to an escaped UTF-8 encoded URI.
 
Glib::ustring Glib::filename_to_uri (const std::string & filename)
 Converts an absolute filename to an escaped UTF-8 encoded URI.
 
Glib::ustring Glib::filename_display_basename (const std::string & filename)
 Returns the display basename for the particular filename, guaranteed to be valid UTF-8.
 
Glib::ustring Glib::filename_display_name (const std::string & filename)
 Converts a filename into a valid UTF-8 string.
 
std::wstring Glib::wide_from_utf8 (const Glib::ustring & utf8_string)
 Converts from utf-8 encoding to wide character strings.
 
Glib::ustring Glib::wide_to_utf8 (const std::wstring & wide_string)
 Converts from a wide character string to a utf-8 encoding.
 

Detailed Description

Utility functions for converting strings between different character sets.

Function Documentation

◆ convert()

std::string Glib::convert ( const std::string &  str,
const std::string &  to_codeset,
const std::string &  from_codeset 
)

Convert from one encoding to another.

Parameters
strThe string to convert.
to_codesetName of the target charset.
from_codesetName of the source charset.
Returns
The converted string.
Exceptions
Glib::ConvertError

◆ convert_with_fallback() [1/2]

std::string Glib::convert_with_fallback ( const std::string &  str,
const std::string &  to_codeset,
const std::string &  from_codeset 
)

Converts a string from one character set to another, possibly including fallback sequences for characters not representable in the output.

Characters not in the target encoding will be represented as Unicode escapes \x{XXXX} or \x{XXXXXX}.

Parameters
strThe string to convert.
to_codesetName of the target charset.
from_codesetName of the source charset.
Returns
The converted string.
Exceptions
Glib::ConvertError

◆ convert_with_fallback() [2/2]

std::string Glib::convert_with_fallback ( const std::string &  str,
const std::string &  to_codeset,
const std::string &  from_codeset,
const Glib::ustring &  fallback 
)

Converts a string from one character set to another, possibly including fallback sequences for characters not representable in the output.

Note
It is not guaranteed that the specification for the fallback sequences in fallback will be honored. Some systems may do a approximate conversion from from_codeset to to_codeset in their iconv() functions, in which case Glib will simply return that approximate conversion.
Parameters
strThe string to convert.
to_codesetName of the target charset.
from_codesetName of the source charset.
fallbackUTF-8 string to be used in place of characters which aren't available in the target encoding. All characters in the fallback string must be available in the target encoding.
Returns
The converted string.
Exceptions
Glib::ConvertError

◆ filename_display_basename()

Glib::ustring Glib::filename_display_basename ( const std::string &  filename)

Returns the display basename for the particular filename, guaranteed to be valid UTF-8.

The display name might not be identical to the filename, for instance there might be problems converting it to UTF-8, and some files can be translated in the display

You must pass the whole absolute pathname to this function so that translation of well known locations can be done.

This function is preferred over filename_display_name() if you know the whole path, as it allows translation.

Parameters
filenameAn absolute pathname in the GLib file name encoding.
Returns
A string containing a rendition of the basename of the filename in valid UTF-8

◆ filename_display_name()

Glib::ustring Glib::filename_display_name ( const std::string &  filename)

Converts a filename into a valid UTF-8 string.

The conversion is not necessarily reversible, so you should keep the original around and use the return value of this function only for display purposes. Unlike g_filename_to_utf8(), the result is guaranteed to be non-empty even if the filename actually isn't in the GLib file name encoding.

If you know the whole pathname of the file you should use g_filename_display_basename(), since that allows location-based translation of filenames.

Parameters
filenamea pathname hopefully in the GLib file name encoding
Returns
A string containing a rendition of the filename in valid UTF-8.

◆ filename_from_uri() [1/2]

std::string Glib::filename_from_uri ( const Glib::ustring &  uri)

Converts an escaped UTF-8 encoded URI to a local filename in the encoding used for filenames.

Parameters
uriA string in the encoding for filenames.
Returns
The resulting filename.
Exceptions
Glib::ConvertError

◆ filename_from_uri() [2/2]

std::string Glib::filename_from_uri ( const Glib::ustring &  uri,
Glib::ustring &  hostname 
)

Converts an escaped UTF-8 encoded URI to a local filename in the encoding used for filenames.

Parameters
uriA string in the encoding for filenames.
hostnameLocation to store hostname for the URI. If there is no hostname in the URI, "" will be stored in this location.
Returns
The resulting filename.
Exceptions
Glib::ConvertError

◆ filename_from_utf8()

std::string Glib::filename_from_utf8 ( const Glib::ustring &  utf8_string)

Converts a string from UTF-8 to the encoding used for filenames.

Parameters
utf8_stringA UTF-8 encoded string.
Returns
The converted string.
Exceptions
Glib::ConvertError

◆ filename_to_uri() [1/2]

Glib::ustring Glib::filename_to_uri ( const std::string &  filename)

Converts an absolute filename to an escaped UTF-8 encoded URI.

Parameters
filenameAn absolute filename specified in the encoding used for filenames by the operating system.
Returns
The resulting URI.
Exceptions
Glib::ConvertError

◆ filename_to_uri() [2/2]

Glib::ustring Glib::filename_to_uri ( const std::string &  filename,
const Glib::ustring &  hostname 
)

Converts an absolute filename to an escaped UTF-8 encoded URI.

Parameters
filenameAn absolute filename specified in the encoding used for filenames by the operating system.
hostnameA UTF-8 encoded hostname.
Returns
The resulting URI.
Exceptions
Glib::ConvertError

◆ filename_to_utf8()

Glib::ustring Glib::filename_to_utf8 ( const std::string &  opsys_string)

Converts a string which is in the encoding used for filenames into a UTF-8 string.

Parameters
opsys_stringA string in the encoding for filenames.
Returns
The converted string.
Exceptions
Glib::ConvertError

◆ get_charset() [1/2]

bool Glib::get_charset ( )

Get the charset used by the current locale.

Returns
Whether the current locale uses the UTF-8 charset.

◆ get_charset() [2/2]

bool Glib::get_charset ( std::string &  charset)

Get the charset used by the current locale.

Parameters
charsetWill be filled with the charset's name.
Returns
Whether the current locale uses the UTF-8 charset.

◆ locale_from_utf8()

std::string Glib::locale_from_utf8 ( const Glib::ustring &  utf8_string)

Convert from UTF-8 to the current locale's encoding.

Convenience wrapper around Glib::convert().

Parameters
utf8_stringThe UTF-8 string to convert.
Returns
The input string converted to the charset used by the operating system's current locale.
Exceptions
Glib::ConvertError

◆ locale_to_utf8()

Glib::ustring Glib::locale_to_utf8 ( const std::string &  opsys_string)

Convert from the current locale's encoding to UTF-8.

Convenience wrapper around Glib::convert().

Parameters
opsys_stringThe string to convert. Must be encoded in the charset used by the operating system's current locale.
Returns
The input string converted to UTF-8 encoding.
Exceptions
Glib::ConvertError

◆ wide_from_utf8()

std::wstring Glib::wide_from_utf8 ( const Glib::ustring &  utf8_string)

Converts from utf-8 encoding to wide character strings.

The encoding of the returned wide string will be utf-16 for Windows platforms where the size of wchar_t is 2, and ucs-4/utf32 for Unix-like platforms where the size of wchar_t is 4.

For this function to work correctly, the current locale for wide character strings should have been set with for example a call to std::locale::global(std::locale("")). Glib::init() usually does that.

Note that unless the character set is limited to the Basic Multilingual Plane (UCS-2), in Windows platforms where utf-16 is used, the wide character set will not be of fixed size, so the number of complete UCS code points may be less than the value given by calling std::wstring::size() on the returned string.

Since glibmm 2.80:
Parameters
utf8_stringThe utf-8 string to convert.
Returns
The wide character string.
Exceptions
Glib::ConvertError

◆ wide_to_utf8()

Glib::ustring Glib::wide_to_utf8 ( const std::wstring &  wide_string)

Converts from a wide character string to a utf-8 encoding.

The encoding of the wide string must be utf-16 for Windows platforms where the size of wchar_t is 2, and ucs-4/utf32 for Unix-like platforms where the size of wchar_t is 4.

For this function to work correctly, the current locale for wide character strings should have been set with for example a call to std::locale::global(std::locale("")). Glib::init() usually does that.

Note that unless the character set is limited to the Basic Multilingual Plane (UCS-2), in Windows platforms where utf-16 is used, the wide character set will not be of fixed size. For the conversion to work correctly where the wide character string passed to the function is in utf-16 encoding, it must contain only complete utf-16 characters - that is, there must not be a trailing partly-formed character at the end of the string.

Likewise, the last UCS code point in the wide string should not form a combining character or an incomplete suffix of such a character.

Since glibmm 2.80:
Parameters
wide_stringThe wide character string to convert.
Returns
The string in utf-8 encoding.
Exceptions
Glib::ConvertError
Generated on Thu Jun 6 2024 12:18:21 for glibmm by doxygen 1.9.8