# codecvt.h

Go to the documentation of this file.

    00001 // Locale support (codecvt) -*- C++ -*-
    00002
    00003 // Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005
    00004 //  Free Software Foundation, Inc.
    00005 //
    00006 // This file is part of the GNU ISO C++ Library.  This library is free
    00007 // software; you can redistribute it and/or modify it under the
    00008 // terms of the GNU General Public License as published by the
    00009 // Free Software Foundation; either version 2, or (at your option)
    00010 // any later version.
    00011
    00012 // This library is distributed in the hope that it will be useful,
    00013 // but WITHOUT ANY WARRANTY; without even the implied warranty of
    00014 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    00015 // GNU General Public License for more details.
    00016
    00017 // You should have received a copy of the GNU General Public License along
    00018 // with this library; see the file COPYING.  If not, write to the Free
    00019 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
    00020 // USA.
    00021
    00022 // As a special exception, you may use this file as part of a free software
    00023 // library without restriction.  Specifically, if other files instantiate
    00024 // templates or use macros or inline functions from this file, or you compile
    00025 // this file and link it with other files to produce an executable, this
    00026 // file does not by itself cause the resulting executable to be covered by
    00027 // the GNU General Public License.  This exception does not however
    00028 // invalidate any other reasons why the executable file might be covered by
    00029 // the GNU General Public License.
    00030
    00031 //
    00032 // ISO C++ 14882: 22.2.1.5 Template class codecvt
    00033 //
    00034
    00035 // Written by Benjamin Kosnik <bkoz@redhat.com>
    00036
    00037 /** @file bits/codecvt.h
    00038  *  This is an internal header file, included by other library headers.
    00039  *  You should not attempt to use it directly.
    00040  */
    00041
    00042 #ifndef _CODECVT_H
    00043 #define _CODECVT_H 1
    00044
    00045 #pragma GCC system_header
    00046
    00047   /// @brief  Empty base class for codecvt facet [22.2.1.5].
    00048   class codecvt_base
    00049   {
    00050   public:
    00051     enum result
    00052     {
    00053       ok,
    00054       partial,
    00055       error,
    00056       noconv
    00057     };
    00058   };
    00059
    00060   /**
    00061    *  @brief  Common base for codecvt functions.
    00062    *
    00063    *  This template class provides implementations of the public functions
    00064    *  that forward to the protected virtual functions.
    00065    *
    00066    *  This template also provides abstract stubs for the protected virtual
    00067    *  functions.
    00068   */
    00069   template<typename _InternT, typename _ExternT, typename _StateT>
    00070     class __codecvt_abstract_base
    00071     : public locale::facet, public codecvt_base
    00072     {
    00073     public:
    00074       // Types:
    00075       typedef codecvt_base::result  result;
    00076       typedef _InternT          intern_type;
    00077       typedef _ExternT          extern_type;
    00078       typedef _StateT           state_type;
    00079
    00080       // 22.2.1.5.1 codecvt members
    00081       /**
    00082        *  @brief  Convert from internal to external character set.
    00083        *
    00084        *  Converts input string of intern_type to output string of
    00085        *  extern_type.  This is analogous to wcsrtombs.  It does this by
    00086        *  calling codecvt::do_out.
    00087        *
    00088        *  The source and destination character sets are determined by the
    00089        *  facet's locale, internal and external types.
    00090        *
    00091        *  The characters in [from,from_end) are converted and written to
    00092        *  [to,to_end).  from_next and to_next are set to point to the
    00093        *  character following the last successfully converted character,
    00094        *  respectively.  If the result needed no conversion, from_next and
    00095        *  to_next are not affected.
    00096        *
    00097        *  The @a state argument should be intialized if the input is at the
    00098        *  beginning and carried from a previous call if continuing
    00099        *  conversion.  There are no guarantees about how @a state is used.
    00100        *
    00101        *  The result returned is a member of codecvt_base::result.  If
    00102        *  all the input is converted, returns codecvt_base::ok.  If no
    00103        *  conversion is necessary, returns codecvt_base::noconv.  If
    00104        *  the input ends early or there is insufficient space in the
    00105        *  output, returns codecvt_base::partial.  Otherwise the
    00106        *  conversion failed and codecvt_base::error is returned.
    00107        *
    00108        *  @param  state  Persistent conversion state data.
    00109        *  @param  from  Start of input.
    00110        *  @param  from_end  End of input.
    00111        *  @param  from_next  Returns start of unconverted data.
    00112        *  @param  to  Start of output buffer.
    00113        *  @param  to_end  End of output buffer.
    00114        *  @param  to_next  Returns start of unused output area.
    00115        *  @return  codecvt_base::result.
    00116       */
    00117       result
    00118       out(state_type& __state, const intern_type* __from,
    00119       const intern_type* __from_end, const intern_type*& __from_next,
    00120       extern_type* __to, extern_type* __to_end,
    00121       extern_type*& __to_next) const
    00122       {
    00123     return this->do_out(__state, __from, __from_end, __from_next,
    00124                 __to, __to_end, __to_next);
    00125       }
    00126
    00127       /**
    00128        *  @brief  Reset conversion state.
    00129        *
    00130        *  Writes characters to output that would restore @a state to initial
    00131        *  conditions.  The idea is that if a partial conversion occurs, then
    00132        *  the converting the characters written by this function would leave
    00133        *  the state in initial conditions, rather than partial conversion
    00134        *  state.  It does this by calling codecvt::do_unshift().
    00135        *
    00136        *  For example, if 4 external characters always converted to 1 internal
    00137        *  character, and input to in() had 6 external characters with state
    00138        *  saved, this function would write two characters to the output and
    00139        *  set the state to initialized conditions.
    00140        *
    00141        *  The source and destination character sets are determined by the
    00142        *  facet's locale, internal and external types.
    00143        *
    00144        *  The result returned is a member of codecvt_base::result.  If the
    00145        *  state could be reset and data written, returns codecvt_base::ok.  If
    00146        *  no conversion is necessary, returns codecvt_base::noconv.  If the
    00147        *  output has insufficient space, returns codecvt_base::partial.
    00148        *  Otherwise the reset failed and codecvt_base::error is returned.
    00149        *
    00150        *  @param  state  Persistent conversion state data.
    00151        *  @param  to  Start of output buffer.
    00152        *  @param  to_end  End of output buffer.
    00153        *  @param  to_next  Returns start of unused output area.
    00154        *  @return  codecvt_base::result.
    00155       */
    00156       result
    00157       unshift(state_type& __state, extern_type* __to, extern_type* __to_end,
    00158           extern_type*& __to_next) const
    00159       { return this->do_unshift(__state, __to,__to_end,__to_next); }
    00160
    00161       /**
    00162        *  @brief  Convert from external to internal character set.
    00163        *
    00164        *  Converts input string of extern_type to output string of
    00165        *  intern_type.  This is analogous to mbsrtowcs.  It does this by
    00166        *  calling codecvt::do_in.
    00167        *
    00168        *  The source and destination character sets are determined by the
    00169        *  facet's locale, internal and external types.
    00170        *
    00171        *  The characters in [from,from_end) are converted and written to
    00172        *  [to,to_end).  from_next and to_next are set to point to the
    00173        *  character following the last successfully converted character,
    00174        *  respectively.  If the result needed no conversion, from_next and
    00175        *  to_next are not affected.
    00176        *
    00177        *  The @a state argument should be intialized if the input is at the
    00178        *  beginning and carried from a previous call if continuing
    00179        *  conversion.  There are no guarantees about how @a state is used.
    00180        *
    00181        *  The result returned is a member of codecvt_base::result.  If
    00182        *  all the input is converted, returns codecvt_base::ok.  If no
    00183        *  conversion is necessary, returns codecvt_base::noconv.  If
    00184        *  the input ends early or there is insufficient space in the
    00185        *  output, returns codecvt_base::partial.  Otherwise the
    00186        *  conversion failed and codecvt_base::error is returned.
    00187        *
    00188        *  @param  state  Persistent conversion state data.
    00189        *  @param  from  Start of input.
    00190        *  @param  from_end  End of input.
    00191        *  @param  from_next  Returns start of unconverted data.
    00192        *  @param  to  Start of output buffer.
    00193        *  @param  to_end  End of output buffer.
    00194        *  @param  to_next  Returns start of unused output area.
    00195        *  @return  codecvt_base::result.
    00196       */
    00197       result
    00198       in(state_type& __state, const extern_type* __from,
    00199      const extern_type* __from_end, const extern_type*& __from_next,
    00200      intern_type* __to, intern_type* __to_end,
    00201      intern_type*& __to_next) const
    00202       {
    00203     return this->do_in(__state, __from, __from_end, __from_next,
    00204                __to, __to_end, __to_next);
    00205       }
    00206
    00207       int
    00208       encoding() const throw()
    00209       { return this->do_encoding(); }
    00210
    00211       bool
    00212       always_noconv() const throw()
    00213       { return this->do_always_noconv(); }
    00214
    00215       int
    00216       length(state_type& __state, const extern_type* __from,
    00217          const extern_type* __end, size_t __max) const
    00218       { return this->do_length(__state, __from, __end, __max); }
    00219
    00220       int
    00221       max_length() const throw()
    00222       { return this->do_max_length(); }
    00223
    00224     protected:
    00225       explicit
    00226       __codecvt_abstract_base(size_t __refs = 0) : locale::facet(__refs) { }
    00227
    00228       virtual
    00229       ~__codecvt_abstract_base() { }
    00230
    00231       /**
    00232        *  @brief  Convert from internal to external character set.
    00233        *
    00234        *  Converts input string of intern_type to output string of
    00235        *  extern_type.  This function is a hook for derived classes to change
    00236        *  the value returned.  @see out for more information.
    00237       */
    00238       virtual result
    00239       do_out(state_type& __state, const intern_type* __from,
    00240          const intern_type* __from_end, const intern_type*& __from_next,
    00241          extern_type* __to, extern_type* __to_end,
    00242          extern_type*& __to_next) const = 0;
    00243
    00244       virtual result
    00245       do_unshift(state_type& __state, extern_type* __to,
    00246          extern_type* __to_end, extern_type*& __to_next) const = 0;
    00247
    00248       virtual result
    00249       do_in(state_type& __state, const extern_type* __from,
    00250         const extern_type* __from_end, const extern_type*& __from_next,
    00251         intern_type* __to, intern_type* __to_end,
    00252         intern_type*& __to_next) const = 0;
    00253
    00254       virtual int
    00255       do_encoding() const throw() = 0;
    00256
    00257       virtual bool
    00258       do_always_noconv() const throw() = 0;
    00259
    00260       virtual int
    00261       do_length(state_type&, const extern_type* __from,
    00262         const extern_type* __end, size_t __max) const = 0;
    00263
    00264       virtual int
    00265       do_max_length() const throw() = 0;
    00266     };
    00267
    00268   /// @brief class codecvt [22.2.1.5].
    00269   /// NB: Generic, mostly useless implementation.
    00270   template<typename _InternT, typename _ExternT, typename _StateT>
    00271     class codecvt
    00272     : public __codecvt_abstract_base<_InternT, _ExternT, _StateT>
    00273     {
    00274     public:
    00275       // Types:
    00276       typedef codecvt_base::result  result;
    00277       typedef _InternT          intern_type;
    00278       typedef _ExternT          extern_type;
    00279       typedef _StateT           state_type;
    00280
    00281     protected:
    00282       __c_locale            _M_c_locale_codecvt;
    00283
    00284     public:
    00285       static locale::id         id;
    00286
    00287       explicit
    00288       codecvt(size_t __refs = 0)
    00289       : __codecvt_abstract_base<_InternT, _ExternT, _StateT> (__refs) { }
    00290
    00291       explicit
    00292       codecvt(__c_locale __cloc, size_t __refs = 0);
    00293
    00294     protected:
    00295       virtual
    00296       ~codecvt() { }
    00297
    00298       virtual result
    00299       do_out(state_type& __state, const intern_type* __from,
    00300          const intern_type* __from_end, const intern_type*& __from_next,
    00301          extern_type* __to, extern_type* __to_end,
    00302          extern_type*& __to_next) const;
    00303
    00304       virtual result
    00305       do_unshift(state_type& __state, extern_type* __to,
    00306          extern_type* __to_end, extern_type*& __to_next) const;
    00307
    00308       virtual result
    00309       do_in(state_type& __state, const extern_type* __from,
    00310         const extern_type* __from_end, const extern_type*& __from_next,
    00311         intern_type* __to, intern_type* __to_end,
    00312         intern_type*& __to_next) const;
    00313
    00314       virtual int
    00315       do_encoding() const throw();
    00316
    00317       virtual bool
    00318       do_always_noconv() const throw();
    00319
    00320       virtual int
    00321       do_length(state_type&, const extern_type* __from,
    00322         const extern_type* __end, size_t __max) const;
    00323
    00324       virtual int
    00325       do_max_length() const throw();
    00326     };
    00327
    00328   template<typename _InternT, typename _ExternT, typename _StateT>
    00329     locale::id codecvt<_InternT, _ExternT, _StateT>::id;
    00330
    00331   /// @brief class codecvt<char, char, mbstate_t> specialization.
    00332   template<>
    00333     class codecvt<char, char, mbstate_t>
    00334     : public __codecvt_abstract_base<char, char, mbstate_t>
    00335     {
    00336     public:
    00337       // Types:
    00338       typedef char          intern_type;
    00339       typedef char          extern_type;
    00340       typedef mbstate_t         state_type;
    00341
    00342     protected:
    00343       __c_locale            _M_c_locale_codecvt;
    00344
    00345     public:
    00346       static locale::id id;
    00347
    00348       explicit
    00349       codecvt(size_t __refs = 0);
    00350
    00351       explicit
    00352       codecvt(__c_locale __cloc, size_t __refs = 0);
    00353
    00354     protected:
    00355       virtual
    00356       ~codecvt();
    00357
    00358       virtual result
    00359       do_out(state_type& __state, const intern_type* __from,
    00360          const intern_type* __from_end, const intern_type*& __from_next,
    00361          extern_type* __to, extern_type* __to_end,
    00362          extern_type*& __to_next) const;
    00363
    00364       virtual result
    00365       do_unshift(state_type& __state, extern_type* __to,
    00366          extern_type* __to_end, extern_type*& __to_next) const;
    00367
    00368       virtual result
    00369       do_in(state_type& __state, const extern_type* __from,
    00370         const extern_type* __from_end, const extern_type*& __from_next,
    00371         intern_type* __to, intern_type* __to_end,
    00372         intern_type*& __to_next) const;
    00373
    00374       virtual int
    00375       do_encoding() const throw();
    00376
    00377       virtual bool
    00378       do_always_noconv() const throw();
    00379
    00380       virtual int
    00381       do_length(state_type&, const extern_type* __from,
    00382         const extern_type* __end, size_t __max) const;
    00383
    00384       virtual int
    00385       do_max_length() const throw();
    00386   };
    00387
    00388 #ifdef _GLIBCXX_USE_WCHAR_T
    00389   /// @brief  class codecvt<wchar_t, char, mbstate_t> specialization.
    00390   template<>
    00391     class codecvt<wchar_t, char, mbstate_t>
    00392     : public __codecvt_abstract_base<wchar_t, char, mbstate_t>
    00393     {
    00394     public:
    00395       // Types:
    00396       typedef wchar_t           intern_type;
    00397       typedef char          extern_type;
    00398       typedef mbstate_t         state_type;
    00399
    00400     protected:
    00401       __c_locale            _M_c_locale_codecvt;
    00402
    00403     public:
    00404       static locale::id         id;
    00405
    00406       explicit
    00407       codecvt(size_t __refs = 0);
    00408
    00409       explicit
    00410       codecvt(__c_locale __cloc, size_t __refs = 0);
    00411
    00412     protected:
    00413       virtual
    00414       ~codecvt();
    00415
    00416       virtual result
    00417       do_out(state_type& __state, const intern_type* __from,
    00418          const intern_type* __from_end, const intern_type*& __from_next,
    00419          extern_type* __to, extern_type* __to_end,
    00420          extern_type*& __to_next) const;
    00421
    00422       virtual result
    00423       do_unshift(state_type& __state,
    00424          extern_type* __to, extern_type* __to_end,
    00425          extern_type*& __to_next) const;
    00426
    00427       virtual result
    00428       do_in(state_type& __state,
    00429          const extern_type* __from, const extern_type* __from_end,
    00430          const extern_type*& __from_next,
    00431          intern_type* __to, intern_type* __to_end,
    00432          intern_type*& __to_next) const;
    00433
    00434       virtual
    00435       int do_encoding() const throw();
    00436
    00437       virtual
    00438       bool do_always_noconv() const throw();
    00439
    00440       virtual
    00441       int do_length(state_type&, const extern_type* __from,
    00442             const extern_type* __end, size_t __max) const;
    00443
    00444       virtual int
    00445       do_max_length() const throw();
    00446     };
    00447 #endif //_GLIBCXX_USE_WCHAR_T
    00448
    00449   /// @brief class codecvt_byname [22.2.1.6].
    00450   template<typename _InternT, typename _ExternT, typename _StateT>
    00451     class codecvt_byname : public codecvt<_InternT, _ExternT, _StateT>
    00452     {
    00453     public:
    00454       explicit
    00455       codecvt_byname(const char* __s, size_t __refs = 0)
    00456       : codecvt<_InternT, _ExternT, _StateT>(__refs)
    00457       {
    00458     if (std::strcmp(__s, "C") != 0 && std::strcmp(__s, "POSIX") != 0)
    00459       {
    00460         this->_S_destroy_c_locale(this->_M_c_locale_codecvt);
    00461         this->_S_create_c_locale(this->_M_c_locale_codecvt, __s);
    00462       }
    00463       }
    00464
    00465     protected:
    00466       virtual
    00467       ~codecvt_byname() { }
    00468     };
    00469
    00470 #endif // _CODECVT_H