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, 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 //
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

Generated on Tue Dec 2 03:59:24 2008 for libstdc++ by  doxygen 1.5.7.1