libstdc++-v3/include/bits/codecvt.h

   1 // Locale support (codecvt) -*- C++ -*-
   2
   3 // Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
   4 //
   5 // This file is part of the GNU ISO C++ Library.  This library is free
   6 // software; you can redistribute it and/or modify it under the
   7 // terms of the GNU General Public License as published by the
   8 // Free Software Foundation; either version 2, or (at your option)
   9 // any later version.
  10
  11 // This library is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15
  16 // You should have received a copy of the GNU General Public License along
  17 // with this library; see the file COPYING.  If not, write to the Free
  18 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  19 // USA.
  20
  21 // As a special exception, you may use this file as part of a free software
  22 // library without restriction.  Specifically, if other files instantiate
  23 // templates or use macros or inline functions from this file, or you compile
  24 // this file and link it with other files to produce an executable, this
  25 // file does not by itself cause the resulting executable to be covered by
  26 // the GNU General Public License.  This exception does not however
  27 // invalidate any other reasons why the executable file might be covered by
  28 // the GNU General Public License.
  29
  30 //
  31 // ISO C++ 14882: 22.2.1.5 Template class codecvt
  32 //
  33
  34 // Written by Benjamin Kosnik <bkoz@cygnus.com>
  35
  36 /** @file codecvt.h
  37  *  This is an internal header file, included by other library headers.
  38  *  You should not attempt to use it directly.
  39  */
  40
  41 #ifndef _CODECVT_H
  42 #define _CODECVT_H 1
  43
  44 #pragma GCC system_header
  45
  46   //  22.2.1.5  Template class codecvt
  47   /**
  48    *  @brief  Base class for codecvt facet providing conversion result enum.
  49    */
  50   class codecvt_base
  51   {
  52   public:
  53     enum result
  54     {
  55       ok,
  56       partial,
  57       error,
  58       noconv
  59     };
  60   };
  61
  62   // Template class __codecvt_abstract_base
  63   // NB: An abstract base class that fills in the public inlines, so
  64   // that the specializations don't have to re-copy the public
  65   // interface.
  66   /**
  67    *  @brief  Common base for codecvt facet
  68    *
  69    *  This template class provides implementations of the public functions
  70    *  that forward to the protected virtual functions.
  71    *
  72    *  This template also provides abstract stubs for the protected virtual
  73    *  functions.
  74   */
  75   template<typename _InternT, typename _ExternT, typename _StateT>
  76     class __codecvt_abstract_base
  77     : public locale::facet, public codecvt_base
  78     {
  79     public:
  80       // Types:
  81       typedef codecvt_base::result      result;
  82       typedef _InternT                  intern_type;
  83       typedef _ExternT                  extern_type;
  84       typedef _StateT                   state_type;
  85
  86       // 22.2.1.5.1 codecvt members
  87       /**
  88        *  @brief  Convert from internal to external character set.
  89        *
  90        *  Converts input string of intern_type to output string of
  91        *  extern_type.  This is analogous to wcsrtombs.  It does this by
  92        *  calling codecvt::do_out.
  93        *
  94        *  The source and destination character sets are determined by the
  95        *  facet's locale, internal and external types.
  96        *
  97        *  The characters in [from,from_end) are converted and written to
  98        *  [to,to_end).  from_next and to_next are set to point to the
  99        *  character following the last successfully converted character,
 100        *  respectively.  If the result needed no conversion, from_next and
 101        *  to_next are not affected.
 102        *
 103        *  The @a state argument should be intialized if the input is at the
 104        *  beginning and carried from a previous call if continuing
 105        *  conversion.  There are no guarantees about how @a state is used.
 106        *
 107        *  The result returned is a member of codecvt_base::result.  If
 108        *  all the input is converted, returns codecvt_base::ok.  If no
 109        *  conversion is necessary, returns codecvt_base::noconv.  If
 110        *  the input ends early or there is insufficient space in the
 111        *  output, returns codecvt_base::partial.  Otherwise the
 112        *  conversion failed and codecvt_base::error is returned.
 113        *
 114        *  @param  state  Persistent conversion state data.
 115        *  @param  from  Start of input.
 116        *  @param  from_end  End of input.
 117        *  @param  from_next  Returns start of unconverted data.
 118        *  @param  to  Start of output buffer.
 119        *  @param  to_end  End of output buffer.
 120        *  @param  to_next  Returns start of unused output area.
 121        *  @return  codecvt_base::result.
 122       */
 123       result
 124       out(state_type& __state, const intern_type* __from,
 125           const intern_type* __from_end, const intern_type*& __from_next,
 126           extern_type* __to, extern_type* __to_end,
 127           extern_type*& __to_next) const
 128       {
 129         return this->do_out(__state, __from, __from_end, __from_next,
 130                             __to, __to_end, __to_next);
 131       }
 132
 133       /**
 134        *  @brief  Reset conversion state.
 135        *
 136        *  Writes characters to output that would restore @a state to initial
 137        *  conditions.  The idea is that if a partial conversion occurs, then
 138        *  the converting the characters written by this function would leave
 139        *  the state in initial conditions, rather than partial conversion
 140        *  state.  It does this by calling codecvt::do_unshift().
 141        *
 142        *  For example, if 4 external characters always converted to 1 internal
 143        *  character, and input to in() had 6 external characters with state
 144        *  saved, this function would write two characters to the output and
 145        *  set the state to initialized conditions.
 146        *
 147        *  The source and destination character sets are determined by the
 148        *  facet's locale, internal and external types.
 149        *
 150        *  The result returned is a member of codecvt_base::result.  If the
 151        *  state could be reset and data written, returns codecvt_base::ok.  If
 152        *  no conversion is necessary, returns codecvt_base::noconv.  If the
 153        *  output has insufficient space, returns codecvt_base::partial.
 154        *  Otherwise the reset failed and codecvt_base::error is returned.
 155        *
 156        *  @param  state  Persistent conversion state data.
 157        *  @param  to  Start of output buffer.
 158        *  @param  to_end  End of output buffer.
 159        *  @param  to_next  Returns start of unused output area.
 160        *  @return  codecvt_base::result.
 161       */
 162       result
 163       unshift(state_type& __state, extern_type* __to, extern_type* __to_end,
 164               extern_type*& __to_next) const
 165       { return this->do_unshift(__state, __to,__to_end,__to_next); }
 166
 167       /**
 168        *  @brief  Convert from external to internal character set.
 169        *
 170        *  Converts input string of extern_type to output string of
 171        *  intern_type.  This is analogous to mbsrtowcs.  It does this by
 172        *  calling codecvt::do_in.
 173        *
 174        *  The source and destination character sets are determined by the
 175        *  facet's locale, internal and external types.
 176        *
 177        *  The characters in [from,from_end) are converted and written to
 178        *  [to,to_end).  from_next and to_next are set to point to the
 179        *  character following the last successfully converted character,
 180        *  respectively.  If the result needed no conversion, from_next and
 181        *  to_next are not affected.
 182        *
 183        *  The @a state argument should be intialized if the input is at the
 184        *  beginning and carried from a previous call if continuing
 185        *  conversion.  There are no guarantees about how @a state is used.
 186        *
 187        *  The result returned is a member of codecvt_base::result.  If
 188        *  all the input is converted, returns codecvt_base::ok.  If no
 189        *  conversion is necessary, returns codecvt_base::noconv.  If
 190        *  the input ends early or there is insufficient space in the
 191        *  output, returns codecvt_base::partial.  Otherwise the
 192        *  conversion failed and codecvt_base::error is returned.
 193        *
 194        *  @param  state  Persistent conversion state data.
 195        *  @param  from  Start of input.
 196        *  @param  from_end  End of input.
 197        *  @param  from_next  Returns start of unconverted data.
 198        *  @param  to  Start of output buffer.
 199        *  @param  to_end  End of output buffer.
 200        *  @param  to_next  Returns start of unused output area.
 201        *  @return  codecvt_base::result.
 202       */
 203       result
 204       in(state_type& __state, const extern_type* __from,
 205          const extern_type* __from_end, const extern_type*& __from_next,
 206          intern_type* __to, intern_type* __to_end,
 207          intern_type*& __to_next) const
 208       {
 209         return this->do_in(__state, __from, __from_end, __from_next,
 210                            __to, __to_end, __to_next);
 211       }
 212
 213       int
 214       encoding() const throw()
 215       { return this->do_encoding(); }
 216
 217       bool
 218       always_noconv() const throw()
 219       { return this->do_always_noconv(); }
 220
 221       int
 222       length(state_type& __state, const extern_type* __from,
 223              const extern_type* __end, size_t __max) const
 224       { return this->do_length(__state, __from, __end, __max); }
 225
 226       int
 227       max_length() const throw()
 228       { return this->do_max_length(); }
 229
 230     protected:
 231       explicit
 232       __codecvt_abstract_base(size_t __refs = 0) : locale::facet(__refs) { }
 233
 234       virtual
 235       ~__codecvt_abstract_base() { }
 236
 237       /**
 238        *  @brief  Convert from internal to external character set.
 239        *
 240        *  Converts input string of intern_type to output string of
 241        *  extern_type.  This function is a hook for derived classes to change
 242        *  the value returned.  @see out for more information.
 243       */
 244       virtual result
 245       do_out(state_type& __state, const intern_type* __from,
 246              const intern_type* __from_end, const intern_type*& __from_next,
 247              extern_type* __to, extern_type* __to_end,
 248              extern_type*& __to_next) const = 0;
 249
 250       virtual result
 251       do_unshift(state_type& __state, extern_type* __to,
 252                  extern_type* __to_end, extern_type*& __to_next) const = 0;
 253
 254       virtual result
 255       do_in(state_type& __state, const extern_type* __from,
 256             const extern_type* __from_end, const extern_type*& __from_next,
 257             intern_type* __to, intern_type* __to_end,
 258             intern_type*& __to_next) const = 0;
 259
 260       virtual int
 261       do_encoding() const throw() = 0;
 262
 263       virtual bool
 264       do_always_noconv() const throw() = 0;
 265
 266       virtual int
 267       do_length(state_type&, const extern_type* __from,
 268                 const extern_type* __end, size_t __max) const = 0;
 269
 270       virtual int
 271       do_max_length() const throw() = 0;
 272     };
 273
 274   /// @brief  22.2.1.5 Template class codecvt
 275   // NB: Generic, mostly useless implementation.
 276   template<typename _InternT, typename _ExternT, typename _StateT>
 277     class codecvt
 278     : public __codecvt_abstract_base<_InternT, _ExternT, _StateT>
 279     {
 280     public:
 281       // Types:
 282       typedef codecvt_base::result      result;
 283       typedef _InternT                  intern_type;
 284       typedef _ExternT                  extern_type;
 285       typedef _StateT                   state_type;
 286
 287     protected:
 288       __c_locale                        _M_c_locale_codecvt;
 289
 290     public:
 291       static locale::id                 id;
 292
 293       explicit
 294       codecvt(size_t __refs = 0)
 295       : __codecvt_abstract_base<_InternT, _ExternT, _StateT> (__refs) { }
 296
 297       explicit
 298       codecvt(__c_locale __cloc, size_t __refs = 0);
 299
 300     protected:
 301       virtual
 302       ~codecvt() { }
 303
 304       virtual result
 305       do_out(state_type& __state, const intern_type* __from,
 306              const intern_type* __from_end, const intern_type*& __from_next,
 307              extern_type* __to, extern_type* __to_end,
 308              extern_type*& __to_next) const;
 309
 310       virtual result
 311       do_unshift(state_type& __state, extern_type* __to,
 312                  extern_type* __to_end, extern_type*& __to_next) const;
 313
 314       virtual result
 315       do_in(state_type& __state, const extern_type* __from,
 316             const extern_type* __from_end, const extern_type*& __from_next,
 317             intern_type* __to, intern_type* __to_end,
 318             intern_type*& __to_next) const;
 319
 320       virtual int
 321       do_encoding() const throw();
 322
 323       virtual bool
 324       do_always_noconv() const throw();
 325
 326       virtual int
 327       do_length(state_type&, const extern_type* __from,
 328                 const extern_type* __end, size_t __max) const;
 329
 330       virtual int
 331       do_max_length() const throw();
 332     };
 333
 334   template<typename _InternT, typename _ExternT, typename _StateT>
 335     locale::id codecvt<_InternT, _ExternT, _StateT>::id;
 336
 337   /// @brief  codecvt<char, char, mbstate_t> required specialization
 338   template<>
 339     class codecvt<char, char, mbstate_t>
 340     : public __codecvt_abstract_base<char, char, mbstate_t>
 341     {
 342     public:
 343       // Types:
 344       typedef char                      intern_type;
 345       typedef char                      extern_type;
 346       typedef mbstate_t                 state_type;
 347
 348     protected:
 349       __c_locale                        _M_c_locale_codecvt;
 350
 351     public:
 352       static locale::id id;
 353
 354       explicit
 355       codecvt(size_t __refs = 0);
 356
 357       explicit
 358       codecvt(__c_locale __cloc, size_t __refs = 0);
 359
 360     protected:
 361       virtual
 362       ~codecvt();
 363
 364       virtual result
 365       do_out(state_type& __state, const intern_type* __from,
 366              const intern_type* __from_end, const intern_type*& __from_next,
 367              extern_type* __to, extern_type* __to_end,
 368              extern_type*& __to_next) const;
 369
 370       virtual result
 371       do_unshift(state_type& __state, extern_type* __to,
 372                  extern_type* __to_end, extern_type*& __to_next) const;
 373
 374       virtual result
 375       do_in(state_type& __state, const extern_type* __from,
 376             const extern_type* __from_end, const extern_type*& __from_next,
 377             intern_type* __to, intern_type* __to_end,
 378             intern_type*& __to_next) const;
 379
 380       virtual int
 381       do_encoding() const throw();
 382
 383       virtual bool
 384       do_always_noconv() const throw();
 385
 386       virtual int
 387       do_length(state_type&, const extern_type* __from,
 388                 const extern_type* __end, size_t __max) const;
 389
 390       virtual int
 391       do_max_length() const throw();
 392   };
 393
 394 #ifdef _GLIBCXX_USE_WCHAR_T
 395   /// @brief  codecvt<wchar_t, char, mbstate_t> required specialization
 396   template<>
 397     class codecvt<wchar_t, char, mbstate_t>
 398     : public __codecvt_abstract_base<wchar_t, char, mbstate_t>
 399     {
 400     public:
 401       // Types:
 402       typedef wchar_t                   intern_type;
 403       typedef char                      extern_type;
 404       typedef mbstate_t                 state_type;
 405
 406     protected:
 407       __c_locale                        _M_c_locale_codecvt;
 408
 409     public:
 410       static locale::id                 id;
 411
 412       explicit
 413       codecvt(size_t __refs = 0);
 414
 415       explicit
 416       codecvt(__c_locale __cloc, size_t __refs = 0);
 417
 418     protected:
 419       virtual
 420       ~codecvt();
 421
 422       virtual result
 423       do_out(state_type& __state, const intern_type* __from,
 424              const intern_type* __from_end, const intern_type*& __from_next,
 425              extern_type* __to, extern_type* __to_end,
 426              extern_type*& __to_next) const;
 427
 428       virtual result
 429       do_unshift(state_type& __state,
 430                  extern_type* __to, extern_type* __to_end,
 431                  extern_type*& __to_next) const;
 432
 433       virtual result
 434       do_in(state_type& __state,
 435              const extern_type* __from, const extern_type* __from_end,
 436              const extern_type*& __from_next,
 437              intern_type* __to, intern_type* __to_end,
 438              intern_type*& __to_next) const;
 439
 440       virtual
 441       int do_encoding() const throw();
 442
 443       virtual
 444       bool do_always_noconv() const throw();
 445
 446       virtual
 447       int do_length(state_type&, const extern_type* __from,
 448                     const extern_type* __end, size_t __max) const;
 449
 450       virtual int
 451       do_max_length() const throw();
 452     };
 453 #endif //_GLIBCXX_USE_WCHAR_T
 454
 455   /// @brief  22.2.1.6  Template class codecvt_byname
 456   template<typename _InternT, typename _ExternT, typename _StateT>
 457     class codecvt_byname : public codecvt<_InternT, _ExternT, _StateT>
 458     {
 459     public:
 460       explicit
 461       codecvt_byname(const char* __s, size_t __refs = 0)
 462       : codecvt<_InternT, _ExternT, _StateT>(__refs)
 463       {
 464         if (std::strcmp(__s, "C") != 0 && std::strcmp(__s, "POSIX") != 0)
 465           {
 466             this->_S_destroy_c_locale(this->_M_c_locale_codecvt);
 467             this->_S_create_c_locale(this->_M_c_locale_codecvt, __s);
 468           }
 469       }
 470
 471     protected:
 472       virtual
 473       ~codecvt_byname() { }
 474     };
 475
 476   // Include host and configuration specific partial specializations
 477   // with additional functionality, if possible.
 478 #ifdef _GLIBCXX_USE_WCHAR_T
 479   #include <bits/codecvt_specializations.h>
 480 #endif
 481
 482 #endif // _CODECVT_H