Main Page Widgets Namespaces Book

# Character Set Conversion

## Detailed Description

Utility functions for converting strings between different character sets.

## Classes

class | ConvertError
| Exception class for charset conversion errors. More...
class | 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.

## Function Documentation

std::string 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 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 |

std::string 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 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 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 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 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 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 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 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.

bool get_charset | ( |  | ) |

Get the charset used by the current locale.

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

std::string 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 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 |