glibmm: Character Set Conversion

glibmm 2.52.1

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

Classes | Enumerations | 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...

## Enumerations
enum | Glib::ConvertError::Code { Glib::ConvertError::NO_CONVERSION, Glib::ConvertError::ILLEGAL_SEQUENCE, Glib::ConvertError::FAILED, Glib::ConvertError::PARTIAL_INPUT, Glib::ConvertError::BAD_URI, Glib::ConvertError::NOT_ABSOLUTE_PATH, Glib::ConvertError::NO_MEMORY }
| Error codes returned by character set conversion routines. More...

## Functions
bool | Glib::get_charset ()
| Get the charset used by the current locale. More...
bool | Glib::get_charset (std::string& charset)
| Get the charset used by the current locale. More...
std::string | Glib::convert (const std::string& str, const std::string& to_codeset, const std::string& from_codeset)
| Convert from one encoding to another. More...
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. More...
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. More...
Glib::ustring | Glib::locale_to_utf8 (const std::string& opsys_string)
| Convert from the current locale's encoding to UTF-8. More...
std::string | Glib::locale_from_utf8 (const Glib::ustring& utf8_string)
| Convert from UTF-8 to the current locale's encoding. More...
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. More...
std::string | Glib::filename_from_utf8 (const Glib::ustring& utf8_string)
| Converts a string from UTF-8 to the encoding used for filenames. More...
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. More...
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. More...
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. More...
Glib::ustring | Glib::filename_to_uri (const std::string& filename)
| Converts an absolute filename to an escaped UTF-8 encoded URI. More...
Glib::ustring | Glib::filename_display_basename (const std::string& filename)
| Returns the display basename for the particular filename, guaranteed to be valid UTF-8. More...
Glib::ustring | Glib::filename_display_name (const std::string& filename)
| Converts a filename into a valid UTF-8 string. More...

## Detailed Description

Utility functions for converting strings between different character sets.

## Enumeration Type Documentation

enum Glib::ConvertError::Code

Error codes returned by character set conversion routines.

Enumerator
NO_CONVERSION | Conversion between the requested character sets is not supported.
ILLEGAL_SEQUENCE | Invalid byte sequence in conversion input.
FAILED | Conversion failed for some reason.
PARTIAL_INPUT | Partial character sequence at end of input.
BAD_URI | URI is invalid.
NOT_ABSOLUTE_PATH | Pathname is not an absolute path.
NO_MEMORY | No memory available. Since glibmm 2.40:

## Function Documentation

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

  str | The string to convert.
  to_codeset | Name of the target charset.
  from_codeset | Name of the source charset.

Returns
  The converted string.

Exceptions

  Glib::ConvertError |

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

  str | The string to convert.
  to_codeset | Name of the target charset.
  from_codeset | Name of the source charset.

Returns
  The converted string.

Exceptions

  Glib::ConvertError |

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

  str | The string to convert.
  to_codeset | Name of the target charset.
  from_codeset | Name of the source charset.
  fallback | UTF-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 |

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

  filename | An absolute pathname in the GLib file name encoding.

Returns
  A string containing a rendition of the basename of the filename in valid UTF-8

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

  filename | a pathname hopefully in the GLib file name encoding

Returns
  A string containing a rendition of the filename in valid UTF-8.

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

  uri | A string in the encoding for filenames.
  hostname | Location 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 |

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

  uri | A string in the encoding for filenames.

Returns
  The resulting filename.

Exceptions

  Glib::ConvertError |

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_string | A UTF-8 encoded string.

Returns
  The converted string.

Exceptions

  Glib::ConvertError |

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

  filename | An absolute filename specified in the encoding used for filenames by the operating system.
  hostname | A UTF-8 encoded hostname.

Returns
  The resulting URI.

Exceptions

  Glib::ConvertError |

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

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

Parameters

  filename | An absolute filename specified in the encoding used for filenames by the operating system.

Returns
  The resulting URI.

Exceptions

  Glib::ConvertError |

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_string | A string in the encoding for filenames.

Returns
  The converted string.

Exceptions

  Glib::ConvertError |

bool Glib::get_charset | ( |  | ) |

Get the charset used by the current locale.

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

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

Get the charset used by the current locale.

Parameters

  charset | Will be filled with the charset's name.

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

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_string | The UTF-8 string to convert.

Returns
  The input string converted to the charset used by the operating system's current locale.

Exceptions

  Glib::ConvertError |

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_string | The 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 |