libs/glibmm2/glib/src/convert.hg

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