______________________________________________________________________

  22   Localization library                 [lib.localization]

  ______________________________________________________________________

1 This clause describes components that C++ programs may use to encapsu­
  late  (and  therefore be more portable when confronting) cultural dif­
  ferences.  The locale facility includes  internationalization  support
  for  character classification and string collation, numeric, monetary,
  and date/time formatting and parsing, and message retrieval.

2 The following subclauses describe components for  locales  themselves,
  the  standard facets, and facilities from the ISO C library, as summa­
  rized in Table 1:

                  Table 1--Localization library summary

     +---------------------------------------------------------------+
     |                    Subclause                        Header(s) |
     +---------------------------------------------------------------+
     |_lib.locales_ Locales                                <locale>  |
     |_lib.locale.categories_ Standard locale Categories             |
     +---------------------------------------------------------------+
     |_lib.c.locales_ C library locales                    <clocale> |
     +---------------------------------------------------------------+

  22.1  Locales                                            [lib.locales]

  Header <locale> synopsis

  #include <limits>
  #include <string>
  #include <iosfwd>
  #include <stdexcept>    // for runtime_error
  #include <vector>       // for vector<char>

  namespace std {
  // subclause _lib.locale_, locale:
    class locale;
    template <class charT, class Traits>
      basic_ostream<charT,Traits>&
        operator<<(basic_ostream<charT,Traits>& s, const locale& loc);
    template <class charT, class Traits>
      basic_istream<charT,Traits>&
        operator>>(basic_istream<charT,Traits>& s, locale& loc);

  // subclause _lib.locale.convenience_, convenience interfaces:
    template <class charT> bool isspace (charT c, const locale& loc) const;
    template <class charT> bool isprint (charT c, const locale& loc) const;
    template <class charT> bool iscntrl (charT c, const locale& loc) const;
    template <class charT> bool isupper (charT c, const locale& loc) const;
    template <class charT> bool islower (charT c, const locale& loc) const;
    template <class charT> bool isalpha (charT c, const locale& loc) const;
    template <class charT> bool isdigit (charT c, const locale& loc) const;
    template <class charT> bool ispunct (charT c, const locale& loc) const;
    template <class charT> bool isxdigit(charT c, const locale& loc) const;
    template <class charT> bool isalnum (charT c, const locale& loc) const;
    template <class charT> bool isgraph (charT c, const locale& loc) const;
    template <class charT> charT toupper(charT c, const locale& loc) const;
    template <class charT> charT tolower(charT c, const locale& loc) const;
  // subclauses _lib.category.ctype_ and _lib.facet.ctype.special_, ctype:
    class ctype_base;
    template <class charT> class ctype;
                           class ctype<char>;        // specialization
    template <class charT> class ctype_byname;
                           class ctype_byname<char>; // specialization
    class codecvt_base;
    template <class fromT, class toT, class stateT> class codecvt;
    template <class fromT, class toT, class stateT> class codecvt_byname;
  // subclauses _lib.category.numeric_ and _lib.facet.numpunct_, numeric:
    template <class charT, class InputIterator>  class num_get;
    template <class charT, class OutputIterator> class num_put;
    template <class charT> class numpunct;
    template <class charT> class numpunct_byname;
  // subclause _lib.category.collate_, collation:
    template <class charT> class collate;
    template <class charT> class collate_byname;
  // subclause _lib.category.time_, date and time:
    class time_base;
    template <class charT, class InputIterator>  class time_get;
    template <class charT, class InputIterator>  class time_get_byname;
    template <class charT, class OutputIterator> class time_put;
    template <class charT, class OutputIterator> class time_put_byname;
  // subclauses _lib.category.monetary_, money:
    class money_base;
    template <class charT, class InputIterator>  class money_get;
    template <class charT, class OutputIterator> class money_put;
    template <class charT> class moneypunct;
    template <class charT> class moneypunct_byname;
  // subclause _lib.category.messages_, message retrieval:
    class messages_base;
    template <class charT> class messages;
    template <class charT> class messages_byname;
  }

1 The header <locale> defines classes and declares functions that encap­
  sulate and manipulate the information peculiar to a locale.1)
  _________________________
  1)  In  this  subclause, the type name struct tm is an incomplete type
  that is defined in <ctime>.

  22.1.1  Class locale                                      [lib.locale]
  namespace std {
    class locale {
    public:
    // types:
      class facet;
      class id;
      typedef unsigned category;
      static const category   // values assigned here are for exposition only
        none     = 0,
        collate  = 0x010, ctype    = 0x020,
        monetary = 0x040, numeric  = 0x080,
        time     = 0x100, messages = 0x200,
        all = collate | ctype | monetary | numeric | time  | messages;
    // construct/copy/destroy:
      locale();
      locale(const locale& other);
      explicit locale(const char* std_name);
      locale(const locale& other, const char* std_name, category);
      template <class Facet> locale(const locale& other, Facet* f);
      template <class Facet> locale(const locale& other, const locale& one);
      locale(const locale& other, const locale& one, category);
     ~locale();  // non-virtual
      const locale& operator=(const locale& other);
    // locale operations:
      template <class Facet> const Facet& use()  const;
      template <class Facet> bool         has()  const;
      basic_string<char>                  name() const;
      bool operator==(const locale& other) const;
      bool operator!=(const locale& other) const;
      template <class charT>
        bool operator()(const basic_string<charT>& s1,
                        const basic_string<charT>& s2) const;
    // global locale objects:
      static       locale  global(const locale&);
      static const locale& classic();
      static       locale  transparent();
    };
  }

  +-------                 BEGIN BOX 1                -------+
  Editorial proposal: Add exception specifications per 95-0020/N0620:
      locale() throw();
      locale(const locale& other) throw();
     ~locale() throw();  // non-virtual
      const locale& operator=(const locale& other) throw();
      template <class Facet> bool         has() throw() const;
  +-------                  END BOX 1                 -------+

1 Class locale implements a type-safe polymorphic set of facets, indexed
  by facet type.  In other words, a facet has a dual role: in one sense,
  it's just a class interface; at the same time, it's an  index  into  a
  locale's set of facets.

2 Access to the facets of a locale is via two member function templates,
  locale::use<facet>() and locale::has<facet>().

3 [Example: An iostream operator<< might be  implemented  (and  special­
  ized, for simplicity of exposition) as:
    ostream& operator<<(ostream& s, double f)
    {
      if (s.opfx()) {
        locale loc = s.getloc();
        loc.template use< num_put<char> >().put(s, s, loc, f);
      }
      s.osfx();
      return s;
    }
   --end example]

4 In  the call to loc.template use<Facet>(), the type argument chooses a
  facet, making available all members of the named type. If Facet is not
  present  in  a  locale  (or,  failing  that, in the global locale), it
  throws the standard exception bad_cast.  A C++ program can check if  a
  locale  implements  a  particular  facet with the member has<Facet>().
  User-defined facets may be installed in a locale, and used identically
  as may standard facets (_lib.facets.examples_).

5 All  locale  semantics  are accessed via use<>() and has<>(), with two
  exceptions:

  --Convenient global interfaces  are  provided  for  traditional  ctype
    functions  such  as  isdigit() and isspace(), so that given a locale
    object loc a C++ program can call isspace(c,loc).

  --A    member    operator    template     operator()(basic_string<C>&,
    basic_string<C>&)  is  provided  so  that  a locale may be used as a
    predicate argument to the standard collections, to collate  strings.

  +-------                 BEGIN BOX 2                -------+
  Editorial proposal: add a second template parameter T to each instance
  of basic_string above.
  +-------                  END BOX 2                 -------+

6 [Note: The purpose of this is  to  ease  the  conversion  of  existing
  extractors (_lib.istream.formatted_).   --end note]

7 A  locale  which  does  not  implement a facet delegates to the global
  locale in effect at the time that instantiation of  use<>()  is  first
  called on that facet (_lib.locale.statics_).

8 An instance of locale is immutable; once a facet reference is obtained
  from it, that reference remains usable as long  as  the  locale  value
  itself  exists.   The  effect  of imbuing on a stream (_lib.ios.base_,
  _lib.ios_), or installing as the global locale, the result  of  static
  member  locale::transparent() (or any locale with similar behavior) is
  unspecified.

9 Caching results from calls to locale  facet  member  functions  during
  calls  to iostream inserters and extractors, and in streambufs between
  calls   to    basic_streambuf::imbue,    is    explicitly    supported
  (_lib.streambuf_).2)

10A locale constructed from a name string (such  as  "POSIX"),  or  from
  parts  of  two  named  locales, or read from a stream, has a name; all
  others do not.  Named locales may be compared for equality; an unnamed
  locale  is  equal  only to (copies of) itself.  For an unnamed locale,
  locale::name() returns the string *".

  22.1.1.1  locale types                              [lib.locale.types]

  22.1.1.1.1  Type locale::category                [lib.locale.category]

  typedef unsigned category;

1 Valid category values include 0 and the locale member bitmask elements
  collate,  ctype,  monetary, numeric, time, and messages.  In addition,
  locale member all is defined such that the expression
    (collate | ctype | monetary | numeric | time | messages) == all
  is true.

  +-------                 BEGIN BOX 3                -------+
  Editorial proposal: change the expression above to
    (collate | ctype | monetary | numeric | time | messages | all) == all
  +-------                  END BOX 3                 -------+

  Further, the result of applying operators & and |  to  any  two  valid
  values is itself valid.

  +-------                 BEGIN BOX 4                -------+
  We need to say what the meaning of such values is.
  +-------                  END BOX 4                 -------+

2 locale member functions expecting a category argument require either a
  valid category value or one of the constants LC_CTYPE etc., defined in
  <cctype>.   Such  a  category  value  identifies a set of locale cate­
  gories.  Each locale category, in turn, identifies  a  set  of  locale
  facets, as shown in Table 2:

  _________________________
  2) This implies that member functions of iostream classes cannot safe­
  ly call imbue() themselves, except as specified elsewhere.

                     Table 2--Locale Category Facets

     +---------------------------------------------------------------+
     |Category                     Includes Facets                   |
     +---------------------------------------------------------------+
     |collate    collate<char>, collate<wchar_t>                     |
     +---------------------------------------------------------------+
     |ctype      ctype<char>, ctype<wchar_t>                         |
     |           codecvt<char,wchar_t,mbstate_t>,                    |
     |           codecvt<wchar_t,char,mbstate_t>                     |
     +---------------------------------------------------------------+
     |monetary   moneypunct<char>, moneypunct<wchar_t>               |
     |           moneypunct<char,true>, moneypunct<wchar_t,true>,    |
     |           money_get<char,InputIterator>,                      |
     |           money_get<wchar_t,InputIterator>,                   |
     |           money_put<char,OutputIterator>,                     |
     |           money_put<wchar_t,OutputIterator>                   |
     +---------------------------------------------------------------+
     |numeric    numpunct<char>, numpunct<wchar_t>,                  |
     |           num_get<C,InputIterator>, num_put<C,OutputIterator> |
     +---------------------------------------------------------------+
     |time       time_get<char,InputIterator>,                       |
     |           time_put<wchar_t,OutputIterator>,                   |
     |           time_put<char,OutputIterator>,                      |
     |           time_put<wchar_t,OutputIterator>                    |
     +---------------------------------------------------------------+
     |messages   messages<char>, messages<wchar_t>                   |
     +---------------------------------------------------------------+

3 An  implementation  is only required to provide instantiations for the
  facets  identified  as  implementing  a  category.   For  the   facets
  num_get<>  and  num_put<> the implementation provided must depend only
  on the facets numpunct<> and ctype<>, instantiated on the same charac­
  ter  type.  Other facets are allowed to depend on any other facet that
  is part of a standard category.

4 Each locale member function which takes a category  argument  operates
  on  the  corresponding set of facets.  Those facets represented with a
  template parameter InputIterator or OutputIterator indicate the set of
  all  possible  instantiations  on parameters that satisfy the require­
  ments of an Input Iterator or an Output Iterator, respectively.  Those
  facets  represented  with  a template parameter C represent the set of
  all possible instantiations on a parameter that satisfies the require­
  ments  for  a character on which any of the iostream components can be
  instantiated.

5 In declarations of facets,  a  template  formal  parameter  with  name
  InputIterator  or  OutputIterator indicates that instantiations depend
  only on the semantics specified for an Input  Iterator  or  an  Output
  Iterator as defined in _lib.iterator.requirements_.

  22.1.1.1.2  Class locale::facet                     [lib.locale.facet]
  namespace std {
    class locale::facet {
    protected:
      explicit facet(size_t refs = 0);
      virtual ~facet();
    private:
      facet(const facet&);          // not defined
      void operator=(const facet&); // not defined
    };
  }

1 Class  facet  is the base class for locale feature sets.  A class is a
  facet if it is publicly derived from another facet,  or  if  it  is  a
  class  derived from locale::facet and containing a declaration as fol­
  lows:
        static ::std::locale::id id;
  Template parameters in this Clause which  must  be  facets  are  those
  named Facet in declarations.  A program that passes a type that is not
  a facet, as an (explicit or deduced) template parameter  to  a  locale
  function expecting a facet, is ill-formed.

2 The  refs argument to the constructor is used for lifetime management.

  --If (refs == 0) the facet's lifetime is  managed  by  the  locale  or
    locales it is incorporated into;

  --if (refs == 1) its lifetime is until explicitly deleted.

3 Constructors  of  all facets defined in this Clause take such an argu­
  ment and pass it along to their facet  base  class  constructor.   All
  one-argument  constructors  defined  in this clause are explicit, pre­
  venting their participation in automatic conversions.

4 For some standard facets a standard _byname" class, derived  from  it,
  implements  the  semantics equivalent to that facet of the locale con­
  structed by locale(const char*).  Each such facet provides a construc­
  tor  that  takes a const char* argument, which names the locale, and a
  refs argument, which is passed to  the  base  class  constructor.   If
  there  is  no  _byname"  version of a facet, the base class implements
  such semantics  itself,  sometimes  with  the  help  of  other  facets
  obtained via a locale argument.

  22.1.1.1.3  Class locale::id                           [lib.locale.id]
  namespace std {
    class locale::id {
    public:
      id();
    private:
      void operator=(const id&); // not defined
      id(const id&);             // not defined
    };
  }

1 Identification  of  a  locale  facet  interface,  used as an index for
  lookup and to encapsulate initialization.

2 [Note: Because facets are used by iostreams, potentially while  static
  constructors  are  running, their initialization cannot depend on pro­
  grammed static initialization.3)  --end note]

  22.1.1.2  locale constructors and destructor         [lib.locale.cons]

  locale();

  +-------                 BEGIN BOX 5                -------+
  Editorial proposal: change this to
          locale() throw();
  +-------                  END BOX 5                 -------+

1 Default constructor: a snapshot of the current global locale.
  Effects:
    Constructs  a  locale instance whose value is a snapshot of the cur­
    rent global locale state as set by locale::global(locale&) or the  C
    function  setlocale().   This  constructor  is  commonly used as the
    default value for arguments of functions that take  a  locale  argu­
    ment.

  locale(const locale& other);

  +-------                 BEGIN BOX 6                -------+
  Editorial proposal: change this to
          locale(const locale& other) throw();
  +-------                  END BOX 6                 -------+

  Effects:
    Constructs a locale which is a copy of other.

  const locale& operator=(const locale& other);

  +-------                 BEGIN BOX 7                -------+
  Editorial proposal: change this to
          const locale& operator=(const locale& other) throw();
  +-------                  END BOX 7                 -------+
  _________________________
  3) One way to do this is for locale to initialize the  id  member  the
  first  time an instance of the facet is installed into a locale.  This
  depends only on static storage  being  zero  before  constructors  run
  (_basic.start.init_).

  Effects:
    Creates a copy of other, replacing the current value.
  Returns:
    *this

  explicit locale(const char* std_name);

  +-------                 BEGIN BOX 8                -------+
  Editorial proposal: change this to
          explicit locale(const char* std_name) throw(runtime_error);
  +-------                  END BOX 8                 -------+

  Effects:
    Constructs  a  locale  using  standard C locale names, e.g. "POSIX".
    The resulting locale implements semantics defined to  be  associated
    with that name.

  +-------                 BEGIN BOX 9                -------+
  Editorial proposal: Throws: runtime_error if the argument value is not
  valid.
  +-------                  END BOX 9                 -------+

  Requires:
    The set of valid string argument values is "C", "", and  any  imple­
    mentation-defined values.

  locale(const locale& other, const char* std_name, category);

  Effects:
    Constructs a locale as a copy of other except for the facets identi­
    fied by the category argument,  which  instead  implement  the  same
    semantics as locale(std_name).
  Notes:
    The locale has a name if and only if other has a name.

  template <class Facet> locale(const locale& other, Facet* f);

  Effects:
    Constructs a locale incorporating all facets from the first argument
    except that of type Facet, and installs the second argument  as  the
    remaining facet.
  Notes:
    The resulting locale has no name.

  template <class Facet> locale(const locale& other, const locale& one);

  Effects:
    Constructs a locale incorporating all facets from the first argument

    except that identified by Facet, and  that  facet  from  the  second
    argument instead.
  Throws:
    runtime_error if one.template has<Facet>() is false.
  Notes:
    The resulting locale has no name.

  locale(const locale& other, const locale& one, category cats);

  Effects:
    Constructs a locale incorporating all facets from the first argument
    except those that implement cats,  which  are  instead  incorporated
    from the second argument.
  Notes:
    The  resulting  locale has a name if and only if the first two argu­
    ments have names.

  ~locale();

  +-------                BEGIN BOX 10                -------+
  Editorial proposal: change this to
          ~locale() throw();
  +-------                 END BOX 10                 -------+

2 A non-virtual destructor.

  +-------                BEGIN BOX 11                -------+
  Editorial proposal: add ``that throws no exceptions.''
  +-------                 END BOX 11                 -------+

  22.1.1.3  locale members                          [lib.locale.members]

  template <class Facet> const Facet& use() const;

1 Get a reference to a facet of a locale.
  Effects:
    If the requested Facet is not present in *this, but  is  present  in
    the  current  global locale, returns the global locale's instance of
    Facet.  Because locale objects are immutable,  subsequent  calls  to
    use<Facet>()  return  the  same object, regardless of changes to the
    global locale.4)
  _________________________
  4) The only exception to this rule  is  the  locale  returned  by  lo­
  cale::transparent();  it  always returns the Facet found in the global
  locale at the time of each call.

  Throws:
    bad_cast  if  (this->template  has<Facet>()   ||   locale().template
    has<Facet>()) is false.
  Returns:
    A reference to the requested facet.
  Notes:
    The result is guaranteed by locale's value semantics to last as long
    as the value of *this.

  +-------                BEGIN BOX 12                -------+
  The syntax for calling use<>, as it has turned out, is unfortunate.  A
  global   template,   replacing   the   member   template  loc.template
  use<Facet>()" with use_facet<Facet>(loc)" is now preferable.
  +-------                 END BOX 12                 -------+

  template <class Facet> bool has() const;

  +-------                BEGIN BOX 13                -------+
  Editorial proposal: change this to
          template <class Facet> bool has() throw() const;
  +-------                 END BOX 13                 -------+

  Returns:
    An indication whether the facet requested is present in  *this.   If
    use<Facet>() has already been called successfully, returns true.
  Notes:
    locale::transparent().template has<Facet>() always returns false.

  +-------                BEGIN BOX 14                -------+
  The syntax for calling has<>, as it has turned out, is unfortunate.  A
  global  template,   replacing   the   member   template   loc.template
  has<Facet>()" with has_facet<Facet>(loc)" is now preferable.
  +-------                 END BOX 14                 -------+

  basic_string<char>  name() const;

  Returns:
    The name of *this, if it has one; otherwise, the string "*".

  22.1.1.4  locale operators                      [lib.locale.operators]

  bool operator==(const locale& other) const;

  Returns:
    true  if both arguments are the same locale, or one is a copy of the
    other, or each has a name and the names are identical; false  other­
    wise.

  bool operator!=(const locale& other) const;

  Returns:
    The result of the expression: !(*this == other)

  template <class charT>
    bool operator()(const basic_string<charT>& s1,
                    const basic_string<charT>& s2) const;

  +-------                BEGIN BOX 15                -------+
  Editorial proposal: Change this as follows:
          template <class charT, class Traits>
            bool operator()(const basic_string<charT,Traits>& s1,
                            const basic_string<charT,Traits>& s2) const;
  +-------                 END BOX 15                 -------+

  Effects:
    Compares two strings according to the collate<charT> facet.
  Notes:
    This  member  operator template (and therefore locale itself) satis­
    fies requirements  for  a  comparator  predicate  template  argument
    (_lib.algorithms_) applied to strings.
  Returns:
    The result of the following expression:
      use< collate<charT> >().compare(s1.data(), s1.data()+s1.size(),
                                      s2.data(), s2.data()+s2.size()) < 0;

1 [Example: A vector of strings v can be collated according to collation
  rules in locale loc simply by (_lib.alg.sort_, _lib.vector_):
    std::sort(v.begin(), v.end(), loc);
   --end example]

  template <class charT, class Traits>
    basic_ostream<charT,Traits>&
      operator<<(basic_ostream<charT,Traits>& s, const locale& loc);

2 The     regular     stream     output     operator     for     locales
  (_lib.ostream.formatted_).
  Effects:
    s << loc.name() << endl.
  Returns:
    The output stream argument s.

  template <class charT, class Traits>
    basic_istream<charT,Traits>&
      operator>>(basic_istream<charT,Traits>& s, loc& loc);

3 The      regular     stream     input     operator     for     locales
  (_lib.istream.formatted_).
  Effects:
    Read a line into a string and construct a locale from it.  If either
    operation     fails,     indicates     a    failure    by    calling
    s.setstate(ios_base::failbit)  (which  may  throw  ios_base::failure
    (_lib.iostate.flags_),  otherwise,  assigns  the  constructed locale
    object into the argument loc.
  Returns:
    s.

  22.1.1.5  locale static members                   [lib.locale.statics]

  static locale global(const locale& loc);

1 Replaces ::setlocale().
  Effects:
    Sets the global locale to its argument.   Subsequent  calls  to  the
    default  constructor, and of other library functions affected by the
    function setlocale(), use the locale loc until the next call to this
    member or setlocale().
  Returns:
    The previous global locale.

  static const locale& classic();

2 The "C" locale.
  Returns:
    A  locale  that implements the classic "C" locale semantics, equiva­
    lent to the value locale("C").
  Notes:
    This locale, its facets, and their member functions, do  not  change
    with time.

  static locale transparent();

3 The continuously updated global locale.
  Returns:
    A  locale  which  implements  semantics that vary dynamically as the
    global locale is changed.
  Notes:
    The effect of imbuing this locale into  an  iostreams  component  is
    unspecified (_lib.ios.members_).

  22.1.2  Convenience interfaces                [lib.locale.convenience]

  22.1.2.1  Character classification                [lib.classification]

  template <class charT> bool isspace (charT c, const locale& loc) const;
  template <class charT> bool isprint (charT c, const locale& loc) const;
  template <class charT> bool iscntrl (charT c, const locale& loc) const;
  template <class charT> bool isupper (charT c, const locale& loc) const;
  template <class charT> bool islower (charT c, const locale& loc) const;
  template <class charT> bool isalpha (charT c, const locale& loc) const;
  template <class charT> bool isdigit (charT c, const locale& loc) const;
  template <class charT> bool ispunct (charT c, const locale& loc) const;
  template <class charT> bool isxdigit(charT c, const locale& loc) const;
  template <class charT> bool isalnum (charT c, const locale& loc) const;
  template <class charT> bool isgraph (charT c, const locale& loc) const;

1 Each of these functions isF returns the result of the expression:
    loc.template use< ctype<charT> >().is(ctype<charT>::F, c)
  where  F  is  the  ctype_mask  value  corresponding  to  that function
  (_lib.category.ctype_).

  22.1.2.2  Character conversions                      [lib.conversions]

  template <class charT> charT toupper(charT c, const locale& loc) const;

  Returns:
    loc.template use<ctype<charT> >().toupper(c).

  template <class charT> charT tolower(charT c, const locale& loc) const;

  Returns:
    loc.template use<ctype<charT> >().tolower(c).

  22.2  Standard locale categories               [lib.locale.categories]

1 Each of the standard categories includes a family of facets.  Some  of
  these implement formatting or parsing, intended for use by standard or
  users' operators << and >>.  Those that take a basic_ios<charT>& argu­
  ment  obey  all  formatting  conventions specified for members of that
  class, including width() and fill() (_lib.ios.base_).

  +-------                BEGIN BOX 16                -------+
  In each facet taking an InputIterator template parameter, the previous
  Draft  listed  only  a single such parameter to its get() member func­
  tions.   As  this  is  incompatible  with  Iterator  semantics,  which
  requires  two  such parameters to specify a range, I have added an end
  argument to each such function.
  +-------                 END BOX 16                 -------+

  22.2.1  The ctype category                        [lib.category.ctype]
  namespace std {
    class ctype_base {
    public:
      enum ctype_mask {  // numeric values are for exposition only.
        space=1<<0, print=1<<1, cntrl=1<<2, upper=1<<3, lower=1<<4,
        alpha=1<<5, digit=1<<6, punct=1<<7, xdigit=1<<8,
        alnum=alpha|digit, graph=alnum|punct
      };
    };
  }

  +-------                BEGIN BOX 17                -------+
  This was changed as an editorial improvement from  enum  ctype  before
  the March 1995 meeting.
  +-------                 END BOX 17                 -------+

1 The type ctype_mask is a bitmask type.

  22.2.1.1  Template class ctype                      [lib.locale.ctype]
    template <class charT>
    class ctype : public locale::facet, public ctype_base {
    public:
      typedef charT char_type;
      explicit ctype(size_t refs = 0);
      bool         is(ctype_mask mask, charT c) const;
      const charT* is(const charT* low, const charT* high, ctype_mask* vec) const;
      const charT* scan_is(ctype_mask mask,
                           const charT* low, const charT* high) const;
      const charT* scan_not(ctype_mask mask,
                            const charT* low, const charT* high) const;
      charT        toupper(charT) const;
      const charT* toupper(charT* low, const charT* high) const;
      charT        tolower(charT c) const;
      const charT* tolower(charT* low, const charT* high) const;
      charT        widen(char c) const;
      const char*  widen(const char* low, const char* high, charT* to) const;
      char         narrow(charT c, char dfault) const;
      const charT* narrow(const charT* low, const charT*, char dfault,
                          char* to) const;
      static locale::id id;

    protected:
     ~ctype();  // virtual
      virtual bool         do_is(ctype_mask mask, charT c) const;
      virtual const charT* do_is(const charT* low, const charT* high,
                                 ctype_mask* vec) const;
      virtual const char*  do_scan_is(ctype_mask mask,
                                      const charT* low, const charT* high) const;
      virtual const char*  do_scan_not(ctype_mask mask,
                                       const charT* low, const charT* high) const;
      virtual charT        do_toupper(charT) const;
      virtual const charT* do_toupper(charT* low, const charT* high) const;
      virtual charT        do_tolower(charT) const;
      virtual const charT* do_tolower(charT* low, const charT* high) const;
      virtual charT        do_widen(char) const;
      virtual const char*  do_widen(const char* low, const char* high,
                                    charT* dest) const;
      virtual char         do_narrow(charT, char dfault) const;
      virtual const charT* do_narrow(const charT* low, const charT* high,
                                     char dfault, char* dest) const;
    };

1 Class  ctype  encapsulates  the  C library <cctype> features.  istream
  members are required to use  ctype<>  for  character  classing  during
  input parsing.

2 The  base class implementation implements character classing appropri­
  ate to the implementation's native character set.

  22.2.1.1.1  ctype members                   [lib.locale.ctype.members]

  bool         is(ctype_mask mask, charT c) const;
  const charT* is(const charT* low, const charT* high,
                  ctype_mask* vec) const;

  Returns:
    do_is(mask,c) or do_is(low,high,vec)

  const charT* scan_is(ctype_mask mask,
                       const charT* low, const charT* high) const;

  Returns:
    do_scan_is(mask,low,high)

  const charT* scan_not(ctype_mask mask,
                        const charT* low, const charT* high) const;

  Returns:
    do_scan_not(mask,low,high)

  charT        toupper(charT) const;
  const charT* toupper(charT* low, const charT* high) const;

  Returns:
    do_toupper(c) or do_toupper(low,high)

  charT        tolower(charT c) const;
  const charT* tolower(charT* low, const charT* high) const;

  Returns:
    do_tolower(c) or do_tolower(low,high)

  charT       widen(char c) const;
  const char* widen(const char* low, const char* high, charT* to) const;

  Returns:
    do_widen(c) or do_widen(low,high,to)

  char         narrow(charT c, char dfault) const;
  const charT* narrow(const charT* low, const charT*, char dfault,
                      char* to) const;

  Returns:
    do_narrow(c,dfault) or do_narrow(low,high,dfault,to)

  22.2.1.1.2  ctype virtual functions        [lib.locale.ctype.virtuals]

  bool         do_is(ctype_mask mask, charT c) const;
  const charT* do_is(const charT* low, const charT* high,
                     ctype_mask* vec) const;

  Effects:
    Classifies a character or sequence of characters.  For each argument
    character,  identifies  a  value M of type ctype_mask The first form
    returns the result of the expression (M & mask) !=  0.   The  second
    form  simply  places  M  for  all  *p where (low<=p && p<high), into
    vec[p-low].
  Returns:
    The first form returns true if the character has the characteristics
    specified.  The second form returns low.

  +-------                BEGIN BOX 18                -------+
  Editorial  proposal:  Chage  this  to ``returns high.''  to remove the
  accidental inconsistency with  to_upper(),  to_lower(),  widen(),  and
  narrow().
  +-------                 END BOX 18                 -------+

  const char* do_scan_is(ctype_mask mask,
                         const charT* low, const charT* high) const;

  Effects:
    Locates  a  character  in a buffer that conforms to a classification
    mask.
  Returns:
    The smallest pointer p in the range [low,  high)  such  that  is(*p)
    would return true; otherwise, returns high.

  const char* do_scan_not(ctype_mask mask,
                          const charT* low, const charT* high) const;

  Effects:
    Locates a character in a buffer that fails to conform to a classifi­
    cation mask.
  Returns:
    The smallest pointer p, if any, in the range [low, high)  such  that
    is(*p) would return false; otherwise, returns high.

  charT        do_toupper(charT c) const;
  const charT* do_toupper(charT* low, const charT* high) const;

  Effects:
    Converts a character or characters to upper case.
  Effects:
    The  second form replaces each character *p in the range [low, high)
    for which a corresponding upper-case  character  exists,  with  that
    character.
  Returns:
    The  first form returns the corresponding upper-case character if it
    is known to exist, or its argument if not.  The second form  returns
    high.

  charT        do_tolower(charT c) const;
  const charT* do_tolower(charT* low, const charT* high) const;

  Effects:
    Converts a character or characters to upper case.
  Effects:
    The  second form replaces each character *p in the range [low, high)
    and for which a corresponding lower-case character exists, with that
    character.
  Returns:
    The  first form returns the corresponding lower-case character if it
    is known to exist, or its argument if not.  The second form  returns
    high.

  charT        do_widen(char c) const;
  const char*  do_widen(const char* low, const char* high,
                        charT* dest) const;

  Effects:
    Applies  the simplest reasonable transformation from a char value or
    sequence of char values to the corresponding charT value or  values.
    The  only  characters  for which unique transformations are required
    are the digits, alphabetic characters, '-', '+', newline, and space.
    For any named ctype category with a ctype<charT> facet ctw and valid
    ctype_mask value M, however, (is(M, c) || !ctw.is(M, do_widen(c))  )
    is true.5)
    The second form transforms each character  *p  in  the  range  [low,
    high), placing the result in dest[p-low].
  Returns:
    The  first  form  returns  the  transformed  value.  The second form
    returns high

  char         do_narrow(charT c, char dfault) const;
  const charT* do_narrow(const charT* low, const charT* high,
                         char dfault, char* dest) const;

  Effects:
    Applies the simplest reasonable transformation from a charT value or
    sequence  of charT values to the corresponding char value or values.
    The only characters for which unique  transformations  are  required
    are the digits, alphabetic characters, '-', '+', newline, and space.
    For any named ctype category with a ctype<char> facet  ctc  however,
    and  valid ctype_mask value M, (is(M, c) || !ctc.is(M, do_narrow(c))
    ) is true.  In addition, for any digit character c,  the  expression
    (do_narrow(c)-'0') evaluates to the digit value of the character.
  Effects:
    The  second  form  transforms  each  character *p in the range [low,
    high), placing the result (or dfault if no simple transformation  is
    readly available) in dest[p-low].
  Returns:
    The  first  form returns the transformed value; or dfault if no map­
    ping is readily available.  The second form returns high.

  22.2.1.2  Template class ctype_byname        [lib.locale.ctype.byname]

  _________________________
  5)  In  other  words, the transformed character is not a member of any
  character classification that c is not also a member of.

    template <class charT>
    class ctype_byname : public ctype<charT> {
    public:
      explicit ctype_byname(const char*, size_t refs = 0);
    protected:
     ~ctype_byname();  // virtual
      virtual char        do_toupper(char) const;
      virtual const char* do_toupper(char* low, const char* high) const;
      virtual char        do_tolower(char) const;
      virtual const char* do_tolower(char* low, const char* high) const;
    };
  }

1 This class is specialized for at least char and wchar_t.

  22.2.1.3  ctype specializations              [lib.facet.ctype.special]
  namespace std {
    class ctype<char> : public locale::facet, public ctype_base {
    public:
      typedef char char_type;
      explicit ctype(const ctype_mask* tab = 0, bool del = false,
                     size_t refs = 0);
      bool is(ctype_mask mask, char c) const;
      const char* is(const char* low, const char* high, ctype_mask* vec) const;
      const char* scan_is (ctype_mask mask,
                           const char* low, const char* high) const;
      const char* scan_not(ctype_mask mask,
                           const char* low, const char* high) const;
      char        toupper(char c) const;
      const char* toupper(char* low, const char* high) const;
      char        tolower(char c) const;
      const char* tolower(char* low, const char* high) const;
      char  widen(char c) const;
      const char* widen(const char* low, const char* high, char* to) const;
      char  narrow(char c, char /*dfault*/) const;
      const char* narrow(const char* low, const char* high, char /*dfault*/,
                         char* to) const;
      static locale::id id;
    protected:
      const ctype_mask* const table_;
      static const ctype_mask classic_table_[numeric_limits<unsigned char>::max()+1];
     ~ctype();  // virtual
      virtual char        do_toupper(char) const;
      virtual const char* do_toupper(char* low, const char* high) const;
      virtual char        do_tolower(char) const;
      virtual const char* do_tolower(char* low, const char* high) const;
    };
    private:
      bool delete_it_              // exposition only
  }

  +-------                BEGIN BOX 19                -------+
  Members table_,  classic_table_,  and  delete_it_  should  be  clearly

  described  in  terms  of their (lack of) constraints on the details of
  the implementation.  In particular, it  must  be  made  clear  whether
  these  members must appear with these particular names, who can get to
  them, and so on.
  +-------                 END BOX 19                 -------+

1 A specialization ctype<char> is provided so that the member  functions
  on type char can be implemented inline.6)

  22.2.1.3.1  ctype<char> destructor         [lib.facet.ctype.char.dtor]

  ~ctype();

  Effects:
    if (delete_it_) delete[] table_;

  22.2.1.3.2  ctype<char> members         [lib.facet.ctype.char.members]

  explicit ctype(const ctype_mask* tab = 0, bool del = false,
                 size_t refs = 0);

  Effects:
    Passes its refs argument to its base class constructor,  initializes
    protected  member  table_  with  the tab argument if nonzero, or the
    static value classic_table_ otherwise, and initializes the protected
    member delete_it_ to (tab && del).

  bool        is(ctype_mask mask, char c) const;
  const char* is(const char* low, const char* high,
                 ctype_mask* vec) const;

  Effects:
    The second form, for all *p in the range [low, high), assigns vec[p-
    low] to table_[(unsigned char)*p].
  Returns:
    The first form returns table_[(unsigned char)c] & mask;  the  second
    form returns low.

  +-------                BEGIN BOX 20                -------+
  Editorial  proposal:  Chage  this  to ``returns high.''  to remove the
  accidental inconsistency with  to_upper(),  to_lower(),  widen(),  and
  narrow().
  +-------                 END BOX 20                 -------+
  _________________________
  6) Only the char (not unsigned char and signed char) form is provided.
  The specialization is specified in the standard, and not  left  as  an
  implementation detail, because it affects the derivation interface for
  ctype<char>.

  const char* scan_is(ctype_mask mask,
                      const char* low, const char* high) const;

  Returns:
    The  smallest  p in the range [low, high) such that (table[(unsigned
    char) *p] & mask) == true.

  const char* scan_not(ctype_mask mask,
                       const char* low, const char* high) const;

  Returns:
    The smallest p in the range [low, high) such  that  (table[(unsigned
    char) *p] & mask) == false.

  char        toupper(char c) const;
  const char* toupper(char* low, const char* high) const;

  Returns:
    do_toupper(c) or do_toupper(low,high)

  char        tolower(char c) const;
  const char* tolower(char* low, const char* high) const;

  Returns:
    do_tolower(c) or do_tolower(low,high)

  char  widen(char c) const;
  const char* widen(const char* low, const char* high,
      char* to) const;

  Effects:
    ::memcpy(to, low, high-low)
  Returns:
    c or hi

  char        narrow(char c, char /*dfault*/) const;
  const char* narrow(const char* low, const char* high,
                     char /*dfault*/, char* to) const;

  Effects:
    ::memcpy(to, low, high-low)
  Returns:
    c or high.

  22.2.1.3.3  ctype<char>                [lib.facet.ctype.char.virtuals]
       overridden virtual functions

  22.2.1.4  Template class codecvt                  [lib.locale.codecvt]
  namespace std {
    class codecvt_base {
    public:
      enum result { ok, partial, error, noconv };
    };
    template <class fromT, class toT, class stateT>
    class codecvt : public locale::facet, public codecvt_base {
    public:
      typedef fromT  from_type;
      typedef toT    to_type;
      typedef stateT state_type;
      explicit codecvt(size_t refs = 0)
      result convert(stateT& state,
          const fromT* from, const fromT* from_end, const fromT*& from_next,
                toT*   to,         toT*   to_limit,         toT*& to_next) const;

  +-------                BEGIN BOX 21                -------+
  The  trailing  const was added editorially before the March 1995 meet­
  ing.
  +-------                 END BOX 21                 -------+

      static locale::id id;
    protected:
     ~codecvt();  // virtual
      virtual result do_convert(stateT& state,
          const fromT* from, const fromT* from_end, const fromT*& from_next,
                toT*   to,   toT*         to_limit,       toT*&   to_next) const;
    };
  }

  +-------                BEGIN BOX 22                -------+
  This was changed editorially to add  the  trailing  const  before  the
  March 1995 meeting.
  +-------                 END BOX 22                 -------+

1 The  class  codecvt<fromT,toT,stateT>  is for use when converting from
  one codeset to another, such as  from  wide  characters  to  multibyte
  characters,  or  between  wide character sets such as Unicode and EUC.
  Instances of this facet are typically used in pairs instantiated oppo­
  sitely.

2 The stateT argument selects the pair of codesets being mapped between.

3 Implementations   are   required   to   provide   instantiations   for
  <char,wchar_t,mbstate_t> and <wchar_t,char,mbstate_t>.

  22.2.1.4.1  codecvt members               [lib.locale.codecvt.members]

  result convert(stateT& state,
    const fromT* from, const fromT* from_end, const fromT*& from_next,
            toT* to, toT* to_limit, toT*& to_next) const;

  Returns:
    do_convert(state, from,from_end,from_next, to,to_limit,to_next);

  22.2.1.4.2  codecvt virtual              [lib.locale.codecvt.virtuals]
       functions

  result do_convert(stateT& state,
    const fromT* from, const fromT* from_end, const fromT*& from_next,
            toT* to, toT* to_limit, toT*& to_next) const;

  Preconditions:
    (from<=from_end && to<=to_end) well-defined and true; state initial­
    ized, if at the beginning of a sequence, or else equal to the result
    of converting the preceding characters in the sequence.
  Effects:
    Translates characters in  the  range  [from,from_end),  placing  the
    results starting at to.
    Stops  when  it  runs out of characters to translate or space to put
    the results, or if it encounters a character it cannot convert.   It
    always leaves the from_next and to_next pointers pointing one beyond
    the last character successfully converted.
    If no translation is needed (returns noconv), sets to_next equal  to
    argument to.
  Notes:
    Does not write into *to_limit.  Its operations on state are unspeci­
    fied.
    [Note: This argument can be used, for  example,  to  maintain  shift
    state,  to  specify  conversion  options (such as count only), or to
    identify a cache of seek offsets.   --end note]
  Returns:
    An enumeration value, as summarized in Table 3:

                       Table 3--convert result values

     +-----------------------------------------------------------------+
     | Value                           Meaning                         |
     +-----------------------------------------------------------------+
     |ok        completed the conversion                               |
     |partial   ran out of space in the destination                    |
     |error     encountered a from_type character it could not convert |
     |noconv    no conversion was needed                               |
     +-----------------------------------------------------------------+

  22.2.1.5  Template class                   [lib.locale.codecvt.byname]
       codecvt_byname
  namespace std {
    template <class fromT, class toT, class stateT>
    class codecvt_byname : public codecvt<fromT, toT, stateT> {
    public:
      explicit codecvt_byname(const char*, size_t refs = 0);
    protected:
     ~codecvt_byname();  // virtual
      virtual result do_convert(stateT& state,
        const fromT* from, const fromT* from_end, const fromT*& from_next,
              toT*   to,   toT*         to_limit,       toT*&   to_next) const;
    };
  }

  22.2.2  The numeric category                    [lib.category.numeric]

1 The  classes  num_get<>  and  num_put<>  handle numeric formatting and
  parsing.  Virtual functions are provided for  several  numeric  types;
  implementations are allowed to delegate extraction of smaller types to
  extractors for larger types, but are not required to do so.

2 The functions take a locale argument because their base  class  imple­
  mentation relies on numpunct<> members to identify all numeric punctu­
  ation preferences, and on ctype<> members to perform character classi­
  fication.

3 Extractor  and inserter members of the standard iostreams are required
  to use num_get<> and num_put<> member  functions  for  formatting  and
  parsing                               (_lib.istream.formatted.reqmts_,
  _lib.ostream.formatted.reqmts_).  The ios& argument is used  both  for
  format  control,  and  to  report  errors,  as described in subclauses
  _lib.iostate.flags_ and _lib.fmtflags.state_.

  22.2.2.1  Template class num_get                  [lib.locale.num.get]
  namespace std {
    template <class charT, class InputIterator = istreambuf_iterator<charT> >
    class num_get : public locale::facet {
    public:
      typedef charT            char_type;
      typedef InputIterator    iter_type;
      typedef basic_ios<charT> ios;
      explicit num_get(size_t refs = 0);
      iter_type get(iter_type in, iter_type end, ios&,
                    const locale&, bool& v)          const;
      iter_type get(iter_type in, iter_type end, ios& ,
                    const locale&, long& v)          const;
      iter_type get(iter_type in, iter_type end, ios&,
                    const locale&, unsigned long& v) const;
      iter_type get(iter_type in, iter_type end, ios&,
                    const locale&, double& v)        const;
      iter_type get(iter_type in, iter_type end, ios&,
                    const locale&, long double& v)   const;

      static locale::id id;
    protected:
     ~num_get();  // virtual
      virtual iter_type do_get(iter_type, iter_type, ios&, const locale&,
                               bool& v) const;
      virtual iter_type do_get(iter_type, iter_type, ios&, const locale&,
                               long& v) const;
      virtual iter_type do_get(iter_type, iter_type, ios&, const locale&,
                               unsigned long& v) const;
      virtual iter_type do_get(iter_type, iter_type, ios&, const locale&,
                               double& v) const;
      virtual iter_type do_get(iter_type, iter_type, ios&, const locale&,
                               long double& v) const;
    };
  }

1 The facet num_get is used  to  parse  numeric  values  from  an  input
  sequence such as an istream.

  22.2.2.1.1  num_get members                [lib.facet.num.get.members]

  iter_type get(iter_type in, iter_type end, ios& str
                const locale& loc, bool& val) const;
  iter_type get(iter_type in, iter_type end, ios& str
                const locale& loc, long& val) const;
  iter_type get(iter_type in, iter_type end, ios& str
                const locale& loc, unsigned long& val) const;
  iter_type get(iter_type in, iter_type end, ios& str
                const locale& loc, double& val) const;
  iter_type get(iter_type in, iter_type end, ios& str
                const locale& loc, long double& val) const;

  Returns:
    do_get(in, end, str, loc, val).

  22.2.2.1.2  num_get virtual               [lib.facet.num.get.virtuals]
       functions

  iter_type do_get(iter_type in, iter_type end, ios& str
                   const locale& loc, bool& val) const;
  iter_type do_get(iter_type in, iter_type end, ios& str
                   const locale& loc, long& val) const;
  iter_type do_get(iter_type in, iter_type end, ios& str
                   const locale& loc, unsigned long& val) const;
  iter_type do_get(iter_type in, iter_type end, ios& str
                   const locale& loc, double& val) const;
  iter_type do_get(iter_type in, iter_type end, ios& str
                   const locale& loc, long double& val) const;

  Effects:
    Reads  characters  from   in,   interpreting   them   according   to

    str.flags(), loc.use template< ctype<charT> >, and loc.use template<
    numpunct<charT> >.  do_get() ignores  the  value  of  str.rdstate();
    however,  indicates  failure by calling str.setstate(failbit) (which
    may throw ios_base::failure (_lib.iostate.flags_)).
    If an error occurs, val is unchanged; otherwise it  is  set  to  the
    resulting value.
  Notes:
    Digit  group  separators are optional; if present, digit grouping is
    checked after the entire number is read.  When reading a non-numeric
    boolean value, the names are compared exactly.
  Returns:
    An iterator pointing one past the last character consumed as part of
    the converted field.

  22.2.2.2  Template class num_put                  [lib.locale.num.put]
  namespace std {
    template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
    class num_put : public locale::facet {
    public:
      typedef charT            char_type;
      typedef OutputIterator   iter_type;
      typedef basic_ios<charT> ios;
      explicit num_put(size_t refs = 0);
      iter_type put(iter_type s, ios& f, const locale& loc, bool v)          const;
      iter_type put(iter_type s, ios& f, const locale& loc, long v) const;
      iter_type put(iter_type s, ios& f, const locale& loc, unsigned long v) const;
      iter_type put(iter_type s, ios& f, const locale& loc, double v) const;
      iter_type put(iter_type s, ios& f, const locale& loc, long double v) const;
      static locale::id id;
    protected:
     ~num_put();  // virtual
      virtual iter_type do_put(iter_type, ios&, const locale&, bool v) const;
      virtual iter_type do_put(iter_type, ios&, const locale&, long v) const;
      virtual iter_type do_put(iter_type, ios&, const locale&, unsigned long) const;
      virtual iter_type do_put(iter_type, ios&, const locale&, double v) const;
      virtual iter_type do_put(iter_type, ios&, const locale&, long double v) const;
    };
  }

1 The facet num_put is used to format  numeric  values  to  a  character
  sequence such as an ostream.

  22.2.2.2.1  num_put members                [lib.facet.num.put.members]

  iter_type put(iter_type out, ios& str
                const locale& loc, bool val) const;
  iter_type put(iter_type out, ios& str
                const locale& loc, long val) const;
  iter_type put(iter_type out, ios& str
                const locale& loc, unsigned long val) const;
  iter_type put(iter_type out, ios& str
                const locale& loc, double val) const;
  iter_type put(iter_type out, ios& str
                const locale& loc, long double val) const;

  Returns:
    do_put(out, str, loc, val).

  22.2.2.2.2  num_put virtual               [lib.facet.num.put.virtuals]
       functions

  iter_type do_put(iter_type out, ios& str
                   const locale& loc, bool val) const;
  iter_type do_put(iter_type out, ios& str
                   const locale& loc, long val) const;
  iter_type do_put(iter_type out, ios& str
                   const locale& loc, unsigned long val) const;
  iter_type do_put(iter_type out, ios& str
                   const locale& loc, double val) const;
  iter_type do_put(iter_type out, ios& str
                   const locale& loc, long double val) const;

  Effects:
    Writes characters to the sequence out, formatting val  according  to
    str.flags(), loc.use template< ctype<charT> >, and loc.use template<
    numpunct<charT> >.  Inserts digit group separators as  specified  by
    numpunct<charT>::do_grouping.
  Notes:
    do_put()  ignores  and  does  not change the result of str.rdstate()
    (_lib.ios.base_).
  Returns:
    An iterator pointing immediately after the last character  produced.

  +-------                BEGIN BOX 23                -------+
  What  if do_put cannot produce all the characters requested?  Is there
  a way to bound how much storage do_put will consume?  If we don't know
  if  the puts fail, how can ostream member functions set badbit as they
  are required to do?  The same questions apply  to  the  put  functions
  later in this clause.
  +-------                 END BOX 23                 -------+

  22.2.3  The numeric punctuation facet             [lib.facet.numpunct]

  22.2.3.1  Template class numpunct                [lib.locale.numpunct]
  namespace std {
    template <class charT>
    class numpunct : public locale::facet {
    public:
      typedef charT               char_type;
      typedef basic_string<charT> string;
      explicit numpunct(size_t refs = 0);
      string decimal_point()   const;
      string thousands_sep()   const;
      vector<char>  grouping() const;
      string truename()        const;
      string falsename()       const;
      static locale::id id;
    protected:
     ~numpunct();  // virtual
      virtual string       do_decimal_point() const;
      virtual string       do_thousands_sep() const;
      virtual vector<char> do_grouping()      const;
      virtual string       do_truename()      const;  // for bool
      virtual string       do_falsename()     const;  // for bool
    };
  }

1 numpunct<>  specifies  numeric  punctuation.   The base class provides
  classic C" numeric formats, while the _byname" version supports  named
  locale (e.g. POSIX, X/Open) numeric formatting semantics.

2 The  syntax  for  number formats is as follows, where digit represents
  the radix set specified by the fmtflags argument value, whitespace  is
  as  determined  by  the  facet  ctype<charT> (_lib.locale.ctype_), and
  thousands-sep and  decimal-point  are  the  results  of  corresponding
  numpunct<charT> members.  Integer values have the format:
    integer   ::= [sign] units
    sign      ::= plusminus [whitespace]
    plusminus ::= '+' | '-'
    units     ::= digits [thousands-sep units]
    digits    ::= digit [digits]
  and floating-point values have:
    floatval ::= [sign] units [decimal-point [digits]] [e [sign] digits] |
                 [sign]        decimal-point  digits   [e [sign] digits]
    e        ::= 'e' | 'E'
  where  the  number of digits between thousands-seps is as specified by
  do_grouping().  For parsing, if the digits portion contains  no  thou­
  sands-separators, no grouping constraint is applied.

  +-------                BEGIN BOX 24                -------+
  Is  support for syntax like "0xFF" required for iostreams support?  If
  so, we need to add language describing it.
  +-------                 END BOX 24                 -------+

  22.2.3.1.1  numpunct members              [lib.facet.numpunct.members]

  string decimal_point() const;

  Returns:
    do_decimal_point()

  string thousands_sep() const;

  Returns:
    thousands_sep()

  vector<char> grouping()  const;

  Returns:
    do_grouping()

  string truename()  const;
  string falsename() const;

  Returns:
    do_truename() or do_falsename(), respectively.

  22.2.3.1.2  numpunct virtual             [lib.facet.numpunct.virtuals]
       functions

  string do_decimal_point() const;

  Returns:
    A  basic_string<charT>  for  use as the decimal radix separator.  If
    this is not a one-character string, num_get<charT,InputIterator>  is
    not required to recognize numbers formatted using it.
    The base class implementation returns ".".

  string do_thousands_sep() const;

  Returns:
    A basic_string<charT> for use as the digit group separator.  If this
    is longer than one character,  num_get<charT,InputIterator>  is  not
    required to recognize numbers formatted with it.
    The base class implementation returns the empty string.

  vector<char> do_grouping() const;

  Returns:
    A  vector  vec in which each element vec[i] represents the number of

    digits in the group at position i starting with 0 as  the  rightmost
    group.   If  vec.size() <= i, the number is the same as group (i-1);
    if (i<0 || vec[i]<=0), the size of the digit group is unlimited.
    The base class implementation returns the empty vector.

  string do_truename()  const;
  string do_falsename() const;

  Returns:
    A string representing the name of the boolean value true  or  false,
    respectively.
    In the base class implementation these names are "true" and "false".

  22.2.3.2  Template class                  [lib.locale.numpunct.byname]
       numpunct_byname
  namespace std {
    template <class charT>
    class numpunct_byname : public numpunct<charT> {
      // this class is specialized for char and wchar_t.
    public:
      explicit numpunct_byname(const char*, size_t refs = 0);
    protected:
     ~numpunct_byname();  // virtual
      virtual string       do_decimal_point() const;
      virtual string       do_thousands_sep() const;
      virtual vector<char> do_grouping()      const;
      virtual string       do_truename()      const;  // for bool
      virtual string       do_falsename()     const;  // for bool
    };
  }

  22.2.4  The collate category                    [lib.category.collate]

  22.2.4.1  Template class collate                  [lib.locale.collate]
  namespace std {
    template <class charT>
    class collate : public locale::facet {
    public:
      typedef charT               char_type;
      typedef basic_string<charT> string;
      explicit collate(size_t refs = 0);
      int compare(const charT* low1, const charT* high1,
                  const charT* low2, const charT* high2) const;
      string transform(const charT* low, const charT* high) const;
      long hash(const charT* low, const charT* high) const;
      static locale::id id;

    protected:
     ~collate();  // virtual
      virtual int    do_compare(const charT* low1, const charT* high1,
                                const charT* low2, const charT* high2) const;
      virtual string do_transform(const charT* low, const charT* high) const;
      virtual long   do_hash     (const charT* low, const charT* high) const;
    };
  }

  +-------                BEGIN BOX 25                -------+
  This  was  changed  editorially  to  insert trailing consts before the
  March 1995 meeting.
  +-------                 END BOX 25                 -------+

1 The class collate<charT> provides features for use  in  the  collation
  (comparison)  and  hashing  of strings.  A locale member function tem­
  plate, operator(), uses the collate facet to allow  a  locale  to  act
  directly   as   the   predicate   argument   for  standard  algorithms
  (_lib.algorithms_) and containers  operating  on  strings.   The  base
  class      implementation      applies      lexicographic     ordering
  (_lib.alg.lex.comparison_).

2 Each function  compares  a  string  of  characters  *p  in  the  range
  [low,high).

  22.2.4.1.1  collate members               [lib.locale.collate.members]

  int compare(const charT* low1, const charT* high1,
              const charT* low2, const charT* high2) const;

  Returns:
    do_compare(low1, high1, low2, high2)

  string transform(const charT* low, const charT* high) const;

  Returns:
    do_transform(low, high)

  long hash(const charT* low, const charT* high) const;

  Returns:
    do_hash(low, high)

  22.2.4.1.2  collate virtual              [lib.locale.collate.virtuals]
       functions

  int do_compare(const charT* low1, const charT* high1,
                 const charT* low2, const charT* high2) const;

  Returns:
    1 if the first string is greater than the second, -1 if  less,  zero
    otherwise.

  string transform(const charT* low, const charT* high) const;

  Returns:
    A  basic_string<charT>  value  that, compared lexicographically with
    the result of calling transform() on another string, yields the same
    result as calling compare() on the same two strings.7)

  long hash(const charT* low, const charT* high) const;

  Returns:
    An integer value equal to the result of calling hash() on any  other
    string  for  which  compare()  returns 0 (equal) when passed the two
    strings.
  Notes:
    The probability that the result equals that for another string which
    does   not   compare   equal   should  be  very  small,  approaching
    (2.0/numeric_limits<long>::max()) or less for longer strings.

  22.2.4.2  Template class                   [lib.locale.collate.byname]
       collate_byname
  namespace std {
    template <class charT>
    class collate_byname : public collate<charT> {
    public:
      explicit collate_byname(const char*, size_t refs = 0);
    protected:
     ~collate_byname();  // virtual
      virtual int    do_compare(const charT* low1, const charT* high1,
                                const charT* low2, const charT* high2) const;
      virtual string do_transform(const charT* low, const charT* high) const;
      virtual long   do_hash(     const charT* low, const charT* high) const;
    };

  22.2.5  The time category                          [lib.category.time]

1 The          classes         time_get<charT,InputIterator>         and
  time_put<charT,OutputIterator> provide date and  time  formatting  and
  parsing.   The  ios&  argument is used both for format control, and to
  report errors, as  described  in  subclauses  _lib.ios::fmtflags_  and
  _lib.ios::iostate_.

  _________________________
  7)  This  function is useful when one string is being compared to many
  other strings.

  22.2.5.1  Template class time_get                [lib.locale.time.get]
  namespace std {
    class time_base {
    public:
      enum dateorder { no_order, dmy, mdy, ymd, ydm };
    };

    template <class charT, class InputIterator = istreambuf_iterator<charT> >
    class time_get : public locale::facet, public time_base {
    public:
      typedef charT            char_type;
      typedef InputIterator    iter_type;
      typedef basic_ios<charT> ios;
      explicit time_get(size_t refs = 0);
      dateorder date_order()  const { return do_date_order(); }
      iter_type get_time(iter_type s, iter_type end, ios& f,
                         const locale& loc, tm* t)  const;
      iter_type get_date(iter_type s, iter_type end, ios& f,
                         const locale& loc, tm* t)  const;
      iter_type get_weekday(iter_type s, iter_type end, ios& f,
                            const locale& loc, tm* t) const;
      iter_type get_monthname(iter_type s, iter_type end, ios& f,
                              const locale& loc, tm* t) const;
      iter_type get_year(iter_type s, iter_type end, ios& f,
                         const locale& loc, tm* t\fP) const;
      static locale::id id;
    protected:
     ~time_get();  // virtual
      virtual dateorder do_date_order()  const;
      virtual iter_type do_get_time(iter_type s, iter_type end, ios&,
                                    const locale&, tm* t) const;
      virtual iter_type do_get_date(iter_type s, iter_type end, ios&,
                                    const locale&, tm* t) const;
      virtual iter_type do_get_weekday(iter_type s, iter_type end, ios&,
                                       const locale&, tm* t) const;
      virtual iter_type do_get_monthname(iter_type s, ios&,
                                         const locale&, tm* t) const;
      virtual iter_type do_get_year(iter_type s, iter_type end, ios&,
                                    const locale&, tm* t) const;
    };
  }

1 time_get  is used to parse a character sequence, extracting components
  of a time or date into a struct tm record.  Each get member  parses  a
  format   as   produced   by   a   corresponding  format  specifier  to
  time_put<>::put.  If the sequence being  parsed  matches  the  correct
  format, the corresponding members of the struct tm argument are set to
  the values used to produce the sequence; otherwise either an error  is
  reported or unspecified values are assigned.8)
  _________________________
  8)  In other words, user confirmation is required for reliable parsing
  of user-entered dates and times, but machine-generated formats can  be
  parsed  reliably.   This  allows parsers to be aggressive about inter­

  22.2.5.1.1  time_get members             [lib.locale.time.get.members]

  dateorder date_order() const;

  Returns:
    do_date_order()

  iter_type get_time(iter_type s, iter_type end, ios& str,
                     const locale& loc, tm* t) const;

  Returns:
    do_get_time(s, end, str, loc, t)

  iter_type get_date(iter_type s, iter_type end, ios& str,
                     const locale& loc, tm* t) const;

  Returns:
    do_get_date(s, end, str, loc, t)

  iter_type get_weekday(iter_type s, iter_type end, ios& str,
                        const locale&loc, tm* t) const;
  iter_type get_monthname(iter_type s, iter_type end, ios& str,
                          const locale& loc, tm* t) const;

  Returns:
    do_get_weekday(s, end, str, loc, t) or do_get_monthname(s, end, str,
    loc, t

  iter_type get_year(iter_type s, iter_type end, ios& str,
                     const locale& loc, tm* t) const;

  Returns:
    do_get_year(s, end, str, loc, t)

  22.2.5.1.2  time_get virtual            [lib.locale.time.get.virtuals]
       functions

  dateorder do_date_order() const;

  Returns:
    An enumeration value indicating the preferred  order  of  components
    for dates composed of day, month, and year.
    Returns  no_order if the date format specified by 'X' contains other
    variable components (e.g Julian day, week number, week day).
  _________________________
  preting user variations on standard formats.

  iter_type do_get_time(iter_type s, iter_type end, ios& str, const locale&,
                        tm* t) const;

  Effects:
    Reads characters starting at s until it has extracted  those  struct
    tm  members,  and  remaining  format characters, used to produce the
    format specified by 'X', or until it encounters an error or  end  of
    sequence.
    Indicates  an  error  by  calling,  str.setstate(failbit), which may
    throw ios_base::failure (_lib.iostate.flags_)).
  Returns:
    An iterator pointing immediately beyond the  last  character  recog­
    nized as part of the time, if no error occurred.

  iter_type do_get_date(iter_type s, iter_type end, ios& str, const locale&,
                        tm* t) const;

  Effects:
    Reads  characters  starting at s until it has extracted those struct
    tm members, and remaining format characters,  used  to  produce  the
    format specified by 'x', or until it encounters an error.
    Indicates  failure by calling str.setstate(failbit) (which may throw
    ios_base::failure (_lib.iostate.flags_)).
  Returns:
    An iterator pointing immediately beyond the  last  character  recog­
    nized as part of the date, if no error occurred.

  iter_type do_get_weekday(iter_type s, iter_type end, ios& str,
                           const locale&, tm* t) const;
  iter_type do_get_monthname(iter_type s, iter_type end, ios& str,
                             const locale&, tm* t) const;

  Effects:
    Reads  characters  starting at s until it has extracted the (perhaps
    abbreviated) name of a weekday or month.  If it finds  an  abbrevia­
    tion that is followed by characters that could match a full name, it
    continues reading until it matches the full name or fails.  It  sets
    the appropriate struct tm member accordingly.
    Indicates  failure by calling str.setstate(failbit) (which may throw
    ios_base::failure (_lib.iostate.flags_)).
  Returns:
    An iterator pointing immediately beyond the  last  character  recog­
    nized as part of a valid name.

  iter_type do_get_year(iter_type s, iter_type end, ios& str,
                        const locale&, tm* t) const;

  Effects:
    Reads characters starting at s until it has extracted an unambiguous

    year identifier.  It is unspecified whether two-digit  year  numbers
    are  accepted, or what century they are assumed to lie in.  Sets the
    t->tm_year member accordingly.
    Indicates failure by calling str.setstate(failbit) (which may  throw
    ios_base::failure (_lib.iostate.flags_)).
  Returns:
    An  iterator  pointing  immediately beyond the last character recog­
    nized as part of a valid year identifier.

  22.2.5.2  Template class                  [lib.locale.time.get.byname]
       time_get_byname
  namespace std {
    template <class charT, class InputIterator = istreambuf_iterator<charT> >
    class time_get_byname : public time_get<charT, InputIterator> {
    public:
      explicit time_get_byname(const char*, size_t refs = 0);
    protected:
     ~time_get_byname();  // virtual
      virtual dateorder do_date_order()  const;
      virtual iter_type do_get_time(iter_type s, iter_type end, ios&,
                                    const locale&, tm* t) const;
      virtual iter_type do_get_date(iter_type s, iter_type end, ios&,
                                    const locale&, tm* t) const;
      virtual iter_type do_get_weekday(iter_type s, iter_type end, ios&,
                                       const locale&, tm* t) const;
      virtual iter_type do_get_monthname(iter_type s, iter_type end, ios&,
                                         const locale&, tm* t) const;
      virtual iter_type do_get_year(iter_type s, iter_type end, ios&,
                                    const locale&, tm* t) const;
    };
  }

  22.2.5.3  Template class time_put                [lib.locale.time.put]
  namespace std {
    template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
    class time_put : public locale::facet {
    public:
      typedef charT            char_type;
      typedef OutputIterator   iter_type;
      typedef basic_ios<charT> ios;
      explicit time_put(size_t refs = 0);
        // the following is implemented in terms of other member functions.
      iter_type put(iter_type s, ios& f, const locale& loc, const tm* tmb,
                    const charT* pattern, const charT* pat_end) const;
      iter_type put(iter_type s, ios& f, const locale& loc,
                    const tm* t, char format, char modifier = 0) const;
      static locale::id id;
    protected:
     ~time_put();  // virtual
      virtual iter_type do_put(iter_type s, ios&, const locale&, const tm* t,
                               char format, char modifier) const;
    };
  }

  22.2.5.3.1  time_put members             [lib.locale.time.put.members]

  iter_type put(iter_type s, ios&, const locale&, const tm* t,
                const charT* pattern, const charT* pat_end) const;
  iter_type put(iter_type s, ios&, const locale&, const tm* t,
                char format, char modifier = 0) const;

  Effects:
    The first form interprets the characters between pattern and pat_end
    identically as strftime(), (though not treating the  null  character
    as a terminator), calling do_put() repeatedly as needed.
    The  second form calls do_put() once, simply passing along its argu­
    ments.
  Returns:
    An iterator pointing immediately after the last character  produced.

  +-------                BEGIN BOX 26                -------+
  In the previous Draft, the first form was documented without its const
  locale& argument, which meant it had no such parameter to  pass  along
  to the second form.
  +-------                 END BOX 26                 -------+

  22.2.5.3.2  time_put virtual            [lib.locale.time.put.virtuals]
       functions

  iter_type do_put(iter_type s, ios&, const locale&, const tm* t,
                   char format, char modifier) const;

  Effects:
    Formats the contents of the parameter t into  characters  placed  on
    the  output  sequence s.  Formatting is controlled by the parameters
    format and modifier, interpreted identically as  the  format  speci­
    fiers  in  the  string  argument  to  the  standard library function
    strftime().9)
  Returns:
    An  iterator pointing immediately after the last character produced.

  22.2.5.4  Template class                  [lib.locale.time.put.byname]
       time_put_byname

  _________________________
  9) Interpretation of the modifier argument is  implementation-defined,
  but should follow POSIX conventions.

  namespace std {
    template <class charT, class OutputIterator = ostreambuf_iterator<charT> >
    class time_put_byname : public time_put<charT, OutputIterator>
    {
    public:
      explicit time_put_byname(const char*, size_t refs = 0);
    protected:
     ~time_put_byname();  // virtual
      virtual iter_type do_put(iter_type s, ios&, const locale&, const tm* t,
                               char format, char modifier) const;
    };
  }

  22.2.6  The monetary category                  [lib.category.monetary]

1 These  templates  handle monetary formats.  A template parameter indi­
  cates whether local or international monetary formats are to be  used.
  money_get<>  and money_put<> use moneypunct<> members to determine all
  formatting details.  moneypunct<> provides  basic  format  information
  for  money processing.  The ios& argument is used both for format con­
  trol,   and   to   report   errors,   as   described   in   subclauses
  _lib.ios::fmtflags_ and _lib.ios::iostate_.

  22.2.6.1  Template class money_get              [lib.locale.money.get]
  namespace std {
    template <class charT, bool Intl = false,
              class InputIterator = istreambuf_iterator<charT> >
    class money_get : public locale::facet {
    public:
      typedef charT               char_type;
      typedef InputIterator       iter_type;
      typedef basic_string<charT> string;
      typedef basic_ios<charT>    ios;
      explicit money_get(size_t refs = 0);
      iter_type get(iter_type s, iter_type end, ios& f,
                    const locale& loc, double& units) const;
      iter_type get(iter_type s, iter_type end, ios& f,
                    const locale& loc, string& digits) const;
      static locale::id id;
    protected:
     ~money_get();  // virtual
      virtual iter_type do_get(iter_type, iter_type, ios&, const locale&,
                               double& units) const;
      virtual iter_type do_get(iter_type, iter_type, ios&, const locale&,
                               string& digits) const;
    };
  }

  +-------                BEGIN BOX 27                -------+
  Editorial proposal: Add the following member:
      static const bool           intl = Intl;
  +-------                 END BOX 27                 -------+

  22.2.6.1.1  money_get members           [lib.locale.money.get.members]

  iter_type get(iter_type s, iter_type end, ios& f,
                const locale& loc, double& quant) const;
  iter_type get(s, iter_type end, ios&f,
                const locale& loc, string& quant) const;

  Returns:
    do_get(s, end, f, loc, quant)

  22.2.6.1.2  money_get virtual          [lib.locale.money.get.virtuals]
       functions

  iter_type do_get(iter_type s, iter_type end, ios& str,
                   const locale& loc, double& units) const;
  iter_type do_get(iter_type s, iter_type end, ios& strfP,
                   const locale& loc, string& digits) const;

  Effects:
    Reads characters from s until it has constructed a  monetary  value,
    as  specified in str.flags() and the moneypunct<charT> facet of loc,
    or until it encounters an error or  runs  out  of  characters.   The
    result  is  a  pure  sequence of digits, representing a count of the
    smallest  unit  of currency representable.10) Digit group separators
    are optional; if present, digit grouping is checked after  all  syn­
    tactic  elements  have been read.  Where space or none appear in the
    format pattern, except at the end, optional whitespace is  consumed.

  +-------                BEGIN BOX 28                -------+
  Editorial proposal: If (str.flags() & ios::showbase) is true, the cur­
  rency symbol is required; otherwise it is optional.
  +-------                 END BOX 28                 -------+

  Sets the argument units or digits from the sequence of  digits  found.
  units  is negated, or digits is preceded by '-', for a negative value.
  Indicates failure by calling str.setstate(failbit)  (which  may  throw
  ios_base::failure (_lib.iostate.flags_)).
  On error, the units or digits argument is unchanged.
  Returns:
    An  iterator  pointing  immediately beyond the last character recog­
    nized as part of a valid monetary quantity.

  +-------                BEGIN BOX 29                -------+
  The description above needs further review.
  +-------                 END BOX 29                 -------+

  _________________________
  10) For  example, the sequence $1,056.23 in a common U.S. locale would
  yield, for units, 105623, or for digits, 105623".

  22.2.6.2  Template class money_put              [lib.locale.money.put]
  namespace std {
    template <class charT, bool Intl = false,
              class OutputIterator = ostreambuf_iterator<charT> >
    class money_put : public locale::facet {
    public:
      typedef charT               char_type;
      typedef OutputIterator      iter_type;
      typedef basic_string<charT> string;
      typedef basic_ios<charT>    ios;
      explicit money_put(size_t refs = 0);
      iter_type put(iter_type s, ios& f, const locale& loc,
                    double units) const;
      iter_type put(iter_type s, ios& f, const locale& loc,
                    const string& digits) const;
      static locale::id id;
      static const bool intl = Intl;
    protected:
     ~money_put();  // virtual
      virtual iter_type
        do_put(iter_type, ios&, const locale&, double units) const;
      virtual iter_type
        do_put(iter_type, ios&, const locale&, const string& digits) const;
    };
  }

  22.2.6.2.1  money_put members           [lib.locale.money.put.members]

  iter_type put(iter_type s, ios& f, const locale& loc,
                double quant) const;
  iter_type put(iter_type s, ios& f, const locale& loc,
                const string& quant) const;

  Returns:
    do_put(s, f, loc, quant)

  22.2.6.2.2  money_put virtual          [lib.locale.money.put.virtuals]
       functions

  iter_type do_put(iter_type s, ios& str, const locale& loc,
                   double units) const;
  iter_type do_put(iter_type s, ios& str, const locale& loc,
                   const string& digits) const;

  Effects:
    Writes  characters  to  s,  according to the format specified by the
    moneypunct<charT> facet of loc, and str.flags().  Ignores any  frac­
    tional  part  of  units,  or  any  characters  in  digits beyond the
    (optional) leading '-' and immediately subsequent digits.
  Notes:
    The  currency  symbol  is   generated   only   if   (str.flags()   &

    ios::showbase)  is  true.   If  ((str.flags() & ios::adjustfield) ==
    ios::internal) the fill characters are placed where  none  or  space
    appears in the formatting pattern (_lib.money.get.virtuals_).
  Returns:
    An  iterator pointing immediately after the last character produced.

  22.2.6.3  Template class moneypunct            [lib.locale.moneypunct]
  namespace std {
    class money_base {
    public:
      enum part { none, space, symbol, sign, value };
      struct pattern { char field[4]; };
    };

    template <class charT, bool International = false>
    class moneypunct : public locale::facet, public money_base {
    public:
      typedef charT char_type;
      typedef basic_string<charT> string;
      explicit moneypunct(size_t refs = 0);
      charT        decimal_point() const;
      charT        thousands_sep() const;
      vector<char> grouping()      const;
      string       curr_symbol()   const;
      string       positive_sign() const;
      string       negative_sign() const;
      int          frac_digits()   const;
      pattern      pos_format()    const;
      pattern      neg_format()    const;
      static locale::id id;
      static const bool intl = International;
    protected:
     ~moneypunct();  // virtual
      virtual charT        do_decimal_point() const;
      virtual charT        do_thousands_sep() const;
      virtual vector<char> do_grouping()      const;
      virtual string       do_curr_symbol()   const;
      virtual string       do_positive_sign() const;
      virtual string       do_negative_sign() const;
      virtual int          do_frac_digits()   const;
      virtual pattern      do_pos_format()    const;
      virtual pattern      do_neg_format()    const;
    };
  }

1 This  provides  money  punctuation,  similar   to   numpunct<>   above
  (_lib.locale.numpunct_).  In particular, the value portion of the for­
  mat is:
    value ::= units [decimal-point [digits]] |
              decimal-point digits
  if frac_digits returns a positive value, or just
    value ::= units
  otherwise.  In these forms, the decimal-point and  thousands-separator

  are  as  determined  below  and the number of digits after the decimal
  point is exactly the value returned by frac_digits.

  22.2.6.3.1  moneypunct members         [lib.locale.moneypunct.members]

      charT        decimal_point() const;
      charT        thousands_sep() const;
      vector<char> grouping()      const;
      string       curr_symbol()   const;
      string       positive_sign() const;
      string       negative_sign() const;
      int          frac_digits()   const;
      pattern      pos_format()    const;
      pattern      neg_format()    const;

1 Each of these functions F returns the result  of  calling  the  corre­
  sponding virtual member function do_F().

  22.2.6.3.2  moneypunct virtual        [lib.locale.moneypunct.virtuals]
       functions

  charT do_decimal_point() const;

  Returns:
    The radix separator to use in case do_frac_digits() is greater  than
    zero.11)

  charT do_thousands_sep() const;

  Returns:
    The  digit  group separator to use in case do_grouping() specifies a
    digit grouping pattern.12)

  vector<char> do_grouping() const;

  Returns:
    A    pattern    defined    identically    as    the    result     of
    numpunct<charT>::do_grouping().13)

  string do_curr_symbol() const;

  _________________________
  11) In common U.S. locales this is '.'.
  12) In common U.S. locales this is ','.
  13) This is most commonly the vector "{ 3 }"

  Returns:
    A string to use as the currency identifier symbol.14)

  string do_positive_sign() const;

  Returns:
    The string to use to indicate a positive monetary value.15)

  string do_negative_sign() const;

  Returns:
    The string to use to indicate a negative monetary value.
  Notes:
    If  it is a one-character string containing '(', it is paired with a
    matching ')'.

  int do_frac_digits() const;

  Returns:
    The number of digits after the decimal radix separator, if any.16)

  pattern do_pos_format() const;
  pattern do_neg_format() const;

  Returns:
    A pattern, a four-element array specifying the order in  which  syn­
    tactic elements appear in the monetary format.
  Notes:
    In this array each enumeration value symbol, sign, value, and either
    space or none appears exactly once.  none, if present, is not first;
    space,  if  present, is neither first nor last.  Otherwise, the ele­
    ments may appear in any order.  In international instantiations, the
    result is always { symbol, sign, none, value }.17)

  22.2.6.4  Template class                [lib.locale.moneypunct.byname]
       moneypunct_byname

  _________________________
  14)  For international instantiations (second template parameter true)
  this is always four characters  long,  usually  three  letters  and  a
  space.
  15) This is usually the empty string.
  16) In common U.S. locales, this is 2.
  17)  Note  that the international symbol usually contains a space, it­
  self; for example, "USD ".

  namespace std {
    template <class charT, bool Intl = false>
    class moneypunct_byname : public moneypunct<charT, Intl> {
    public:
      explicit moneypunct_byname(const char*, size_t refs = 0);
    protected:
     ~moneypunct_byname();  // virtual
      virtual charT        do_decimal_point() const;
      virtual charT        do_thousands_sep() const;
      virtual vector<char> do_grouping()      const;
      virtual string       do_curr_symbol()   const;
      virtual string       do_positive_sign() const;
      virtual string       do_negative_sign() const;
      virtual int          do_frac_digits()   const;
      virtual pattern      do_pos_format()    const;
      virtual pattern      do_neg_format()    const;
    };
  }

  22.2.7  The message retrieval category         [lib.category.messages]

1 Class  messages<charT>  implements  retrieval  of strings from message
  catalogs.

  22.2.7.1  Template class messages                [lib.locale.messages]
  namespace std {
    class messages_base {
    public:
      typedef THE_POSIX_CATALOG_IDENTIFIER_TYPE catalog;
    };

    template <class charT>
    class messages : public locale::facet, public messages_base {
    public:
      typedef charT char_type;
      typedef int   catalog;
      typedef basic_string<charT> string;

  +-------                BEGIN BOX 30                -------+
  We should clarify  the  meaning  of  THE_POSIX_CATALOG_IDENTIFIER_TYPE
  above.
  +-------                 END BOX 30                 -------+

      explicit messages(size_t refs = 0);
      catalog open (const basic_string<char>& fn, const locale&) const;
      string  get  (catalog c, int set, int msgid, const string& dfault) const;
      void    close(catalog c) const;
      static locale::id id;

    protected:
     ~messages();  // virtual
      virtual catalog do_open(const basic_string<char>&, const locale&) const;
      virtual string  do_get(catalog, int set, int msgid,
                             const string& dfault) const;
      virtual void    do_close(catalog) const;
    };
  }

  22.2.7.1.1  messages members             [lib.locale.messages.members]

  catalog open(const basic_string<char>& name, const locale& loc) const;

  Returns:
    do_open(name, loc).

  string get(catalog cat, int set, int msgid, const string& dfault) const;

  Returns:
    do_get(cat, set, msgid, dfault).

  void  close(catalog cat) const;

  Effects:
    Calls do_close(cat).

  22.2.7.1.2  messages virtual            [lib.locale.messages.virtuals]
       functions

  catalog do_open(const basic_string<char>& name,
                  const locale& loc) const;

  Returns:
    A value that may be passed to get() to retrieve a message, from  the
    message catalog identified by the string name according to an imple­
    mentation-defined mapping.  The result  can  be  used  until  it  is
    passed to close().
    Returns a value less than 0 if no such catalog can be opened.
  Notes:
    The  locale  argument  loc is used for character set code conversion
    when retrieving messages, if needed.

  string do_get(catalog cat, int set, int msgid,
                const string& dfault) const;

  Requires:
    A catalog cat obtained from open() and not yet closed.

  Returns:
    A message identified by arguments set, msgid, and dfault,  according
    to  an  implementation-defined  mapping.   If no such message can be
    found, returns dfault.

  void do_close(catalog cat) const;

  Requires:
    A catalog cat obtained from open() and not yet closed.
  Effects:
    Releases unspecified resources associated with  cat.
  Notes:
    The limit on such resources, if any, is implementation-defined.

  22.2.7.2  Template class                  [lib.locale.messages.byname]
       messages_byname
  namespace std {
    template <class charT>
    class messages_byname : public messages<charT> {
    public:
      explicit messages_byname(const char*, size_t refs = 0);
    protected:
     ~messages_byname();  // virtual
      virtual catalog do_open(const basic_string<char>&, const locale&) const;
      virtual string  do_get(catalog, int set, int msgid,
                             const string& dfault) const;
      virtual void    do_close(catalog) const;
    };
  }

  22.2.8  Program-defined facets                   [lib.facets.examples]

1 A C++ program may define facets to be added to a locale and used iden­
  tically as the built-in facets.  To create a new facet interface,  C++
  programs  simply derive from locale::facet a class containing a static
  member: static locale::id id.

2 [Note: The locale member function templates verify its type and  stor­
  age class.   --end note]

3 This initialization/identification system depends only on the initial­
  ization to 0 of static objects, before static constructors are called.
  When  an  instance  of  a  facet  is installed in a locale, the locale
  checks whether an id has been  assigned,  and  if  not,  assigns  one.
  Before  this  occurs,  any  attempted  use of its interface causes the
  bad_cast exception to be thrown.

4 [Example: Here is a program that just calls C functions:

    #include <locale>
    extern "C" void c_function();
    int main()
    {
      using namespace std;
      locale::global(locale(""));  // same as setlocale(LC_ALL, "");
      c_function();
      return 0;
    }
  In other words, C library localization is unaffected.   --end example]

5 [Example: Traditional global localization is still easy:
    #include <iostream>
    #include <locale>
    int main(int argc, char** argv)
    {
      using namespace std;
      locale::global(locale(""));  // set the global locale
       cin.imbue(locale());        // imbue it on the std streams
      cout.imbue(locale());
      cerr.imbue(locale());
      return MyObject(argc, argv).doit();
    }
   --end example]

6 [Example: Greater flexibility is possible:
    #include <iostream>
    #include <locale>
    int main()
    {
      using namespace std;
      cin.imbue(locale(""));  // the user's preferred locale
      cout.imbue(locale::classic());
      double f;
      while (cin >> f) cout << f << endl;
      return (cin.fail() != 0);
    }
  In  a European locale, with input 3.456,78, output is 3456.78.   --end
  example]

7 This can be important even for simple  programs,  which  may  need  to
  write  a  data  file in a fixed format, regardless of a user's prefer­
  ence.

8 [Example: Here is an example of the use of locales in a library inter­
  face.

    // file: Date.h
    #include <locale>
       ...
    class Date {
      ...
     public:
      Date(unsigned day, unsigned month, unsigned year);
      std::string asString(const std::locale& = std::locale());
    };
    istream& operator>>(istream& s, Date& d);
    ostream& operator<<(ostream& s, Date d);
    ...
  This example illustrates two architectural uses of class locale.

9 The  first  is  as  a  default argument in Date::asString(), where the
  default is the global (presumably user-preferred) locale.

10The second is in the operators << and >>, where a locale  "hitchhikes"
  on  another  object,  in  this case a stream, to the point where it is
  needed.
    // file: Date.C
    #include <Date>
    #include <stringstream>
    std::string Date::asString(const std::locale& l)
    {
      using namespace std;
      stringstream s; s.imbue(l);
      s << *this; return s.data();
    }
    std::istream& operator>>(std::istream& s, Date& d)
    {
      using namespace std;
      if (!s.ipfx(0)) return s;
      locale loc = s.getloc();
      struct tm t;
      loc.template use<time_get<char> >().get_date(s, s, 0, loc, &t);
      if (s) d = Date(t.tm_day, t.tm_mon + 1, t.tm_year + 1900);
      s.isfx();
      return s;
    }
   --end example]

11A locale object may be extended with a new facet simply by  construct­
  ing  it  with  an instance of a class derived from locale::facet.  The
  only member a C++ program must define is the static member  id,  which
  identifies your class interface as a new facet.

12[Example: Classifying Japanese characters:

    // file: <jctype>
    #include <locale>
    namespace My {
      using namespace std;
      class JCtype : public locale::facet {
      public:
        static locale::id id;  // required for use as a new locale facet
        bool is_kanji(wchar_t c);
        JCtype() {}
      protected:
       ~JCtype() {}
      };
    }
    // file: filt.C
    #include <iostream>
    #include <locale>
    #include <jctype> // above
    std::locale::id JCtype::id;  // the static JCtype member declared above.
    int main()
    {
      using namespace std;
      typedef ctype<wchar_t> ctype;
      locale loc(locale(""),       // the user's preferred locale ...
                 new My::JCType);  // and a new feature ...
      wchar_t c = loc.template use<ctype>().widen('!');
      if (loc.template use<My::JCType>().is_kanji(c))
        cout << "no it isn't!" << endl;
      return 0;
    }

13The  new facet is used exactly like the built-in facets.   --end exam­
  ple]

14[Example: Replacing an existing facet is even easier.  Here we do  not
  define  a  member  id because we are reusing the numpunct<charT> facet
  interface:
    // my_bool.C
    #include <iostream>
    #include <locale>
    #include <string>
    namespace My {
      using namespace std;
      typedef numpunct_byname<char> numpunct;
      class BoolNames : public numpunct {
        typedef basic_string<char> string;
      protected:
        string do_truename()  { return "Oui Oui!"; }
        string do_falsename() { return "Mais Non!"; }
       ~BoolNames() {}
      public:
        BoolNames(const char* name) : numpunct(name) {}
      };
    }

    int main(int argc, char** argv)
    {
      using namespace std;
      // make the user's preferred locale, except for...
      locale loc(locale(""), new My::BoolNames(""));
      cout.imbue(loc);
      cout << "Any arguments today? " << (argc > 1) << endl;
      return 0;
    }
   --end example]

  22.3  C Library Locales                                [lib.c.locales]

1 Header <clocale> (Table 4):

                    Table 4--Header <clocale> synopsis

            +-------------------------------------------------+
            |   Type                    Name(s)               |
            +-------------------------------------------------+
            |Macros:                                          |
            |             LC_ALL        LC_COLLATE   LC_CTYPE |
            |             LC_MONETARY   LC_NUMERIC   LC_TIME  |
            +-------------------------------------------------+
            |Struct:      lconv                               |
            +-------------------------------------------------+
            |Functions:   localeconv    setlocale             |
            +-------------------------------------------------+

2 The contents are the same as the Standard C library.

  SEE ALSO: ISO C subclause 7.10.4.