1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GLIBMM_CONVERT_H 3 #define _GLIBMM_CONVERT_H 4 5 6 /* Copyright (C) 2002 The gtkmm Development Team 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 23 #include <glibmmconfig.h> 24 #include <glibmm/error.h> 25 #include <glibmm/ustring.h> 26 #include <glib.h> /* for gsize */ 27 28 #ifndef DOXYGEN_SHOULD_SKIP_THIS 29 extern "C" { typedef struct _GIConv* GIConv; } 30 #endif 31 32 33 namespace Glib 34 { 35 36 /** @defgroup CharsetConv Character Set Conversion 37 * Utility functions for converting strings between different character sets. 38 * @{ 39 */ 40 41 /** %Exception class for charset conversion errors. 42 * Glib::convert() and friends throw a ConvertError exception if the charset 43 * conversion failed for some reason. When writing non-trivial applications 44 * you should always catch those errors, and then try to recover, or tell the 45 * user the input was invalid. 46 */ 47 class GLIBMM_API ConvertError : public Glib::Error 48 { 49 public: 50 /** @var Code NO_CONVERSION 51 * Conversion between the requested character 52 * sets is not supported. 53 * 54 * @var Code ILLEGAL_SEQUENCE 55 * Invalid byte sequence in conversion input; 56 * or the character sequence could not be represented in the target 57 * character set. 58 * 59 * @var Code FAILED 60 * Conversion failed for some reason. 61 * 62 * @var Code PARTIAL_INPUT 63 * Partial character sequence at end of input. 64 * 65 * @var Code BAD_URI 66 * URI is invalid. 67 * 68 * @var Code NOT_ABSOLUTE_PATH 69 * Pathname is not an absolute path. 70 * 71 * @var Code NO_MEMORY 72 * No memory available. @newin{2,40} 73 * 74 * @var Code EMBEDDED_NUL 75 * An embedded NUL character is present in 76 * conversion output where a NUL-terminated string is expected. 77 * @newin{2,56} 78 * 79 * @enum Code 80 * 81 * %Error codes returned by character set conversion routines. 82 */ 83 enum Code 84 { 85 NO_CONVERSION, 86 ILLEGAL_SEQUENCE, 87 FAILED, 88 PARTIAL_INPUT, 89 BAD_URI, 90 NOT_ABSOLUTE_PATH, 91 NO_MEMORY, 92 EMBEDDED_NUL 93 }; 94 95 ConvertError(Code error_code, const Glib::ustring& error_message); 96 explicit ConvertError(GError* gobject); 97 Code code() const; 98 99 #ifndef DOXYGEN_SHOULD_SKIP_THIS 100 private: 101 102 static void throw_func(GError* gobject); 103 104 friend GLIBMM_API void wrap_init(); // uses throw_func() 105 106 #endif //DOXYGEN_SHOULD_SKIP_THIS 107 }; 108 109 110 /** Thin %iconv() wrapper. 111 * glibmm provides Glib::convert() and Glib::locale_to_utf8() which 112 * are likely more convenient than the raw iconv wrappers. However, 113 * creating an IConv object once and using the convert() method could 114 * be useful when converting multiple times between the same charsets. 115 */ 116 class GLIBMM_API IConv 117 { 118 public: 119 /** Open new conversion descriptor. 120 * @param to_codeset Destination codeset. 121 * @param from_codeset %Source codeset. 122 * @throw Glib::ConvertError 123 */ 124 IConv(const std::string& to_codeset, const std::string& from_codeset); 125 126 127 IConv(const IConv&) = delete; 128 IConv& operator=(const IConv&) = delete; 129 130 explicit IConv(GIConv gobject); 131 132 /** Close conversion descriptor. 133 */ 134 ~IConv(); 135 136 137 /** Same as the standard UNIX routine %iconv(), but may be implemented 138 * via libiconv on UNIX flavors that lack a native implementation. glibmm 139 * provides Glib::convert() and Glib::locale_to_utf8() which are likely 140 * more convenient than the raw iconv wrappers. 141 * @param inbuf Bytes to convert. 142 * @param inbytes_left In/out parameter, bytes remaining to convert in @a inbuf. 143 * @param outbuf Converted output bytes. 144 * @param outbytes_left In/out parameter, bytes available to fill in @a outbuf. 145 * @return Count of non-reversible conversions, or <tt>static_cast<std::size_t>(-1)</tt> on error. 146 */ 147 std::size_t iconv(char** inbuf, gsize* inbytes_left, char** outbuf, gsize* outbytes_left); 148 149 150 /** Reset conversion descriptor to initial state. 151 * Same as <tt>iconv(0, 0, 0, 0)</tt>, but implemented slightly differently 152 * in order to work on Sun Solaris <= 7. It's also more obvious so you're 153 * encouraged to use it. 154 */ 155 void reset(); 156 157 /** Convert from one encoding to another. 158 * @param str The string to convert. 159 * @return The converted string. 160 * @throw Glib::ConvertError 161 */ 162 std::string convert(const std::string& str); 163 gobj()164 GIConv gobj() { return gobject_; } 165 166 private: 167 GIConv gobject_; 168 }; 169 170 171 /** Get the charset used by the current locale. 172 * @return Whether the current locale uses the UTF-8 charset. 173 */ 174 GLIBMM_API 175 bool get_charset(); 176 177 /** Get the charset used by the current locale. 178 * @param charset Will be filled with the charset's name. 179 * @return Whether the current locale uses the UTF-8 charset. 180 */ 181 GLIBMM_API 182 bool get_charset(std::string& charset); 183 184 /** Convert from one encoding to another. 185 * @param str The string to convert. 186 * @param to_codeset Name of the target charset. 187 * @param from_codeset Name of the source charset. 188 * @return The converted string. 189 * @throw Glib::ConvertError 190 */ 191 GLIBMM_API 192 std::string convert(const std::string& str, 193 const std::string& to_codeset, 194 const std::string& from_codeset); 195 196 /** Converts a string from one character set to another, possibly including 197 * fallback sequences for characters not representable in the output. 198 * Characters not in the target encoding will be represented as Unicode 199 * escapes <tt>\\x{XXXX}</tt> or <tt>\\x{XXXXXX}</tt>. 200 * @param str The string to convert. 201 * @param to_codeset Name of the target charset. 202 * @param from_codeset Name of the source charset. 203 * @return The converted string. 204 * @throw Glib::ConvertError 205 */ 206 GLIBMM_API 207 std::string convert_with_fallback(const std::string& str, 208 const std::string& to_codeset, 209 const std::string& from_codeset); 210 211 /** Converts a string from one character set to another, possibly including 212 * fallback sequences for characters not representable in the output. 213 * @note It is not guaranteed that the specification for the fallback sequences 214 * in @a fallback will be honored. Some systems may do a approximate conversion 215 * from @a from_codeset to @a to_codeset in their iconv() functions, in which 216 * case Glib will simply return that approximate conversion. 217 * 218 * @param str The string to convert. 219 * @param to_codeset Name of the target charset. 220 * @param from_codeset Name of the source charset. 221 * @param fallback UTF-8 string to be used in place of characters which aren't 222 * available in the target encoding. All characters in the fallback string 223 * @em must be available in the target encoding. 224 * @return The converted string. 225 * @throw Glib::ConvertError 226 */ 227 GLIBMM_API 228 std::string convert_with_fallback(const std::string& str, 229 const std::string& to_codeset, 230 const std::string& from_codeset, 231 const Glib::ustring& fallback); 232 233 /** Convert from the current locale's encoding to UTF-8. 234 * Convenience wrapper around Glib::convert(). 235 * @param opsys_string The string to convert. Must be encoded in the charset 236 * used by the operating system's current locale. 237 * @return The input string converted to UTF-8 encoding. 238 * @throw Glib::ConvertError 239 */ 240 GLIBMM_API 241 Glib::ustring locale_to_utf8(const std::string& opsys_string); 242 243 /** Convert from UTF-8 to the current locale's encoding. 244 * Convenience wrapper around Glib::convert(). 245 * @param utf8_string The UTF-8 string to convert. 246 * @return The input string converted to the charset used by the operating 247 * system's current locale. 248 * @throw Glib::ConvertError 249 */ 250 GLIBMM_API 251 std::string locale_from_utf8(const Glib::ustring& utf8_string); 252 253 /** Converts a string which is in the encoding used for filenames into 254 * a UTF-8 string. 255 * @param opsys_string A string in the encoding for filenames. 256 * @return The converted string. 257 * @throw Glib::ConvertError 258 */ 259 GLIBMM_API 260 Glib::ustring filename_to_utf8(const std::string& opsys_string); 261 262 /** Converts a string from UTF-8 to the encoding used for filenames. 263 * @param utf8_string A UTF-8 encoded string. 264 * @return The converted string. 265 * @throw Glib::ConvertError 266 */ 267 GLIBMM_API 268 std::string filename_from_utf8(const Glib::ustring& utf8_string); 269 270 /** Converts an escaped UTF-8 encoded URI to a local filename 271 * in the encoding used for filenames. 272 * @param uri A string in the encoding for filenames. 273 * @param hostname Location to store hostname for the URI. If there is no 274 * hostname in the URI, <tt>""</tt> will be stored in this location. 275 * @return The resulting filename. 276 * @throw Glib::ConvertError 277 */ 278 GLIBMM_API 279 std::string filename_from_uri(const Glib::ustring& uri, Glib::ustring& hostname); 280 281 /** Converts an escaped UTF-8 encoded URI to a local filename in the encoding 282 * used for filenames. 283 * @param uri A string in the encoding for filenames. 284 * @return The resulting filename. 285 * @throw Glib::ConvertError 286 */ 287 GLIBMM_API 288 std::string filename_from_uri(const Glib::ustring& uri); 289 290 /** Converts an absolute filename to an escaped UTF-8 encoded URI. 291 * @param filename An absolute filename specified in the encoding used 292 * for filenames by the operating system. 293 * @param hostname A UTF-8 encoded hostname. 294 * @return The resulting URI. 295 * @throw Glib::ConvertError 296 */ 297 GLIBMM_API 298 Glib::ustring filename_to_uri(const std::string& filename, const Glib::ustring& hostname); 299 300 /** Converts an absolute filename to an escaped UTF-8 encoded URI. 301 * @param filename An absolute filename specified in the encoding used 302 * for filenames by the operating system. 303 * @return The resulting URI. 304 * @throw Glib::ConvertError 305 */ 306 GLIBMM_API 307 Glib::ustring filename_to_uri(const std::string& filename); 308 309 /** Returns the display basename for the particular filename, guaranteed 310 * to be valid UTF-8. The display name might not be identical to the filename, 311 * for instance there might be problems converting it to UTF-8, and some files 312 * can be translated in the display 313 * 314 * You must pass the whole absolute pathname to this function so that 315 * translation of well known locations can be done. 316 * 317 * This function is preferred over filename_display_name() if you know the 318 * whole path, as it allows translation. 319 * 320 * @param filename An absolute pathname in the GLib file name encoding. 321 * @result A string containing a rendition of the basename of the filename in valid UTF-8 322 */ 323 GLIBMM_API 324 Glib::ustring filename_display_basename(const std::string& filename); 325 326 /** Converts a filename into a valid UTF-8 string. The 327 * conversion is not necessarily reversible, so you 328 * should keep the original around and use the return 329 * value of this function only for display purposes. 330 * Unlike g_filename_to_utf8(), the result is guaranteed 331 * to be non-empty even if the filename actually isn't in the GLib 332 * file name encoding. 333 * 334 * If you know the whole pathname of the file you should use 335 * g_filename_display_basename(), since that allows location-based 336 * translation of filenames. 337 * 338 * @param filename: a pathname hopefully in the GLib file name encoding 339 * @result A string containing a rendition of the filename in valid UTF-8. 340 */ 341 GLIBMM_API 342 Glib::ustring filename_display_name(const std::string& filename); 343 344 /** @} group CharsetConv */ 345 346 } // namespace Glib 347 348 349 #endif /* _GLIBMM_CONVERT_H */ 350 351