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

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