# codecvt.h

Go to the documentation of this file.

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