interface/encconv.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        encconv.h
   3 // Purpose:     interface of wxEncodingConverter
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxEncodingConverter
  11     @wxheader{encconv.h}
  12
  13     This class is capable of converting strings between two 8-bit encodings/charsets.
  14     It can also convert from/to Unicode (but only if you compiled wxWidgets
  15     with wxUSE_WCHAR_T set to 1).
  16
  17     Only a limited subset of encodings is supported by wxEncodingConverter:
  18     @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and
  19     @c wxFONTENCODING_KOI8.
  20
  21     @note
  22
  23     Please use wxMBConv classes instead if possible. wxCSConv has much better
  24     support for various encodings than wxEncodingConverter.
  25     wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode
  26     of operation (see wxEncodingConverter::Init()).
  27
  28     @library{wxbase}
  29     @category{misc}
  30
  31     @see wxFontMapper, wxMBConv, @ref overview_nonenglish
  32 */
  33 class wxEncodingConverter : public wxObject
  34 {
  35 public:
  36     /**
  37         Constructor.
  38     */
  39     wxEncodingConverter();
  40
  41     /**
  42         Return @true if (any text in) multibyte encoding @a encIn can be converted to
  43         another one (@a encOut) losslessly.
  44
  45         Do not call this method with @c wxFONTENCODING_UNICODE as either parameter,
  46         it doesn't make sense (always works in one sense and always depends
  47         on the text to convert in the other).
  48     */
  49     static bool CanConvert(wxFontEncoding encIn,
  50                            wxFontEncoding encOut);
  51
  52     /**
  53         @name Conversion functions
  54
  55         @{
  56     */
  57     /**
  58         Convert input string according to settings passed to Init() and writes
  59         the result to output.
  60
  61         All the Convert() function overloads return @true if the conversion was
  62         lossless and @false if at least one of the characters couldn't be converted
  63         was and replaced with '?' in the output.
  64
  65         Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is
  66         considered a lossless operation.
  67
  68         @note You must call Init() before using this method!
  69
  70         @note wchar_t versions of the method are not available if wxWidgets was
  71               compiled with @c wxUSE_WCHAR_T set to 0.
  72     */
  73     bool Convert(const char* input, char* output) const;
  74     bool Convert(const wchar_t* input, wchar_t* output) const;
  75     bool Convert(const char* input, wchar_t* output) const;
  76     bool Convert(const wchar_t* input, char* output) const;
  77
  78     /**
  79         Convert input string according to settings passed to Init() in-place,
  80         i.e. write the result to the same memory area.
  81
  82         See the Convert(const char*,char*) const overload for more info.
  83     */
  84     bool Convert(char* str) const;
  85     bool Convert(wchar_t* str) const;
  86
  87     /**
  88         Convert a wxString and return a new wxString object.
  89
  90         See the Convert(const char*,char*) const overload for more info.
  91     */
  92     wxString Convert(const wxString& input) const;
  93     //@}
  94
  95
  96     /**
  97         Similar to GetPlatformEquivalents(), but this one will return ALL
  98         equivalent encodings, regardless of the platform, and including itself.
  99
 100         This platform's encodings are before others in the array.
 101         And again, if @a enc is in the array, it is the very first item in it.
 102     */
 103     static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc);
 104
 105     /**
 106         Return equivalents for given font that are used under given platform.
 107
 108         Supported platforms:
 109         @li wxPLATFORM_UNIX
 110         @li wxPLATFORM_WINDOWS
 111         @li wxPLATFORM_OS2
 112         @li wxPLATFORM_MAC
 113         @li wxPLATFORM_CURRENT
 114
 115         wxPLATFORM_CURRENT means the platform this binary was compiled for.
 116
 117         Examples:
 118
 119         @verbatim
 120         current platform   enc          returned value
 121         ----------------------------------------------
 122         unix            CP1250             {ISO8859_2}
 123         unix         ISO8859_2             {ISO8859_2}
 124         windows      ISO8859_2                {CP1250}
 125         unix            CP1252  {ISO8859_1,ISO8859_15}
 126         @endverbatim
 127
 128         Equivalence is defined in terms of convertibility: two encodings are
 129         equivalent if you can convert text between then without losing
 130         information (it may - and will - happen that you lose special chars
 131         like quotation marks or em-dashes but you shouldn't lose any diacritics
 132         and language-specific characters when converting between equivalent encodings).
 133
 134         Remember that this function does @b NOT check for presence of
 135         fonts in system. It only tells you what are most suitable
 136         encodings. (It usually returns only one encoding.)
 137
 138         @note Note that argument enc itself may be present in the returned array,
 139               so that you can, as a side-effect, detect whether the encoding is
 140               native for this platform or not.
 141
 142         @note Convert() is not limited to converting between equivalent encodings,
 143               it can convert between two arbitrary encodings.
 144
 145         @note If @a enc is present in the returned array, then it is always the first
 146               item of it.
 147
 148         @note Please note that the returned array may contain no items at all.
 149     */
 150     static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc,
 151                                                       int platform = wxPLATFORM_CURRENT);
 152
 153     /**
 154         Initialize the conversion.
 155
 156         Both output or input encoding may be wxFONTENCODING_UNICODE, but only
 157         if wxUSE_ENCODING is set to 1.
 158
 159         All subsequent calls to Convert() will interpret its argument
 160         as a string in @a input_enc encoding and will output string in
 161         @a output_enc encoding.
 162
 163         You must call this method before calling Convert. You may call
 164         it more than once in order to switch to another conversion.
 165
 166         @a method affects behaviour of Convert() in case input character
 167         cannot be converted because it does not exist in output encoding:
 168
 169         @li @b wxCONVERT_STRICT: follow behaviour of GNU Recode - just copy
 170             unconvertible  characters to output and don't change them
 171             (its integer value will stay the same)
 172         @li @b wxCONVERT_SUBSTITUTE:  try some (lossy) substitutions - e.g.
 173             replace unconvertible latin capitals with acute by ordinary
 174             capitals, replace en-dash or em-dash by '-' etc.
 175
 176         Both modes guarantee that output string will have same length
 177         as input string.
 178
 179         @return @false if given conversion is impossible, @true otherwise
 180                 (conversion may be impossible either if you try to convert
 181                 to Unicode with non-Unicode build of wxWidgets or if input
 182                 or output encoding is not supported).
 183     */
 184     bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc,
 185               int method = wxCONVERT_STRICT);
 186 };
 187