Compaq C++ User Documentation

| United States

cxxlstd$help.HLP

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

    locale
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      locale - Localization	class containing a polymorphic set of facets.

    SYNOPSIS

      #include<locale>
      class	locale;

    DESCRIPTION

      locale provides a localization interface and a set of	indexed
      facets,	each of which covers one particular localization
      issue.  The default locale object is constructed	on the "C"
      locale.  Locales can	also be	constructed on named locales.

      A calling program can	determine whether a particular facet is
      contained in a locale by using the	has_facet function, and	the
      program can	obtain a reference to that facet with the use_facet
      function.	These are not member functions, but instead take a
      locale object as an argument.

      locale has several important characteristics.

      First, successive calls to member functions will always return the
      same result.  This	allows a calling program to safely cache the
      results of	a call.

      Any standard facet not implemented by	a locale will be obtained from
      the global locale	the first time that use_facet is called	(for
      that facet).

      Only a locale	constructed from a name	(i.e., "POSIX"), from parts of
      two named	locales, or from a stream, has a name.	All other
      locales are unnamed.  Only named locales may be compared for
      equality.  An unnamed locale is equal only to itself.

    INTERFACE

      class	locale {
      public:
        // types:
       class facet;
       class id;
       typedef int category;
       static const	category   none, collate, ctype, monetary,
    			   numeric, time, messages,
    			   all = collate | ctype | monetary |
    				 numeric | time	 | messages;
        // construct/copy/destroy:
       locale() throw()
       locale(const	locale&) throw()
       explicit locale(const char*);
       locale(const	locale&, const char*, category);
       template <class Facet> locale(const locale&,	Facet*);
       template <class Facet> locale(const locale&,
    				 const locale&);
       locale(const	locale&, const locale&,	category);
        ~locale() throw();	// non-virtual
       const locale& operator=(const locale&) throw();
        // locale operations:
       basic_string<char>		       name() const;
       bool	operator==(const locale&) const;
       bool	operator!=(const locale&) const;
       template <class charT,Traits>
         bool operator()(const basic_string<charT,Traits>&,
    		     const basic_string<charT,Traits>&)	const;
        // global locale objects:
       static	locale	global(const locale&);
       static const	locale&	classic();
      };

      class	locale::facet {
      protected:
       explicit facet(size_t refs =	0);
       virtual ~facet();
      private:
       facet(const facet&);		 // not	defined
       void	operator=(const	facet&); // not	defined
      };

      class	locale::id {
      public:
       id();
      private:
       void	operator=(const	id&); // not defined
       id(const id&);	      // not defined
      };

    TYPES

      category
         Standard facets fall into eight broad categories.	These are:
         none, collate, ctype, monetary,	numeric, time, messages, and
         all.  all is a combination of all	the other categories except
         none.  Bitwise operations may be applied to combine or screen
         these categries.  For instance	all is	defined	as:

          (collate | ctype | monetary | numeric | time | messages)

         locale member functions that take a category argument must	be
         provided with one of the above values, or one of the constants
         from	the old	C locale (e.g., LC_CTYPE).

      facet
         Base class	for facets. This class exists primarily	to provide
         reference counting services to derived classes.  All	facets
         must derive from	it, either directly or	indirectly indirectly
         (e.g., facet -> ctype<char> -> my_ctype).

         If	the refs argument to the constructor is	0 then destruction of
         the object is delegated to the	locale,	or locales, containing
         it. This allows the	user to	ignore lifetime	management
         issues.  On the other had, if	refs  is 1, then the object
         must be explicitly deleted;	the locale will not do so.  In
         this case, the	object can be maintained across	the lifetime
         of multiple locales.

         Copy construction and assignment of this class are	disallowed.

      id
         Type used to index	facets in the locale container.	 Every facet
         must contain a member of this type.

         Copy construction and assignment of this type are disallowed.

    CONSTRUCTORS AND DESTRUCTORS

      locale()
       throw()
         Constructs	a default locale object.  This locale will be the same
         as the last argument passed to locale::global(), or, if that
         function has	not been called, the locale will be the same
         as the classic "C" locale.

      locale(const locale& other)
       throw()
         Constructs	a copy of the locale argument other.

      explicit locale(const	char* std_name);
         Constructs	a locale object	on the named locale indicated by
         std_name. Throws a runtime_error exception of if std_name is
         not a valid locale name.

      locale(const locale& other, const char* std_name,
    	category cat);
         Construct a locale	object that is a copy of other,	except for the
         facets that are in the category specified	by cat.	 These facets
         will be obtained from the named locale identified by std_name.
         Throws a runtime_error exception of	if std_name is not a
         valid locale name.

         Note that the resulting locale will have the same name (possibly
         none) as	other.

      template <class Facet>
      locale(const locale& other, Facet* f);
         Constructs	a locale object	that is	a copy of other, except	for
         the	facet of	type Facet.  Unless f is null, it f is
         used to supply the missing facet, otherwise the facet	will
         come from other as	well.

         Note that the resulting locale will not have a name.

      template <class Facet>
      locale(const locale& other, const locale& one);
         Constructs	a locale object	that is	a copy of other, except	for
         the	facet of	type Facet.  This missing facet	is
         obtained from the second locale argument, one.  Throws a
         runtime_error exception if one does not contain a facet of	type
         Facet.

         Note that the resulting locale will not have a name.

      locale(const locale& other, const locale& one, category cat);
         Constructs	a locale object	that is	a copy of other, except	for
         facets that are in the category specified	by category argument
         cat.  These missing facets are	obtained from the other	locale
         argument, one.

         Note that the resulting locale will only have a name only if both
         other and one have names.  The name will	be the same as other's
         name.

      ~locale();
         Destroy the locale.

    PUBLIC MEMBER OPERATORS

      const	locale&
      operator=(const locale& other) throw();
         Replaces *this with a copy	of other.  Returns *this.

      bool
      operator==(const locale& other) const;
         Retuns true if both other and *this are the same object, if one
         is	a copy of another, or if both have the same name.  Otherwise
         returns false.

      bool
      operator!=(const locale& other) const;
         Returns !(*this ==	other)

      template <class charT,Traits>
      bool
      operator()(const basic_string<charT,Traits>& s1,
    	    const basic_string<charT,Traits>& s2) const;
         This operator is provided to allow	a locale object	to be used as
         a	comparison object for	comparing two strings.	Returns	the
         result of comparing the two strings using the compare member
         function of the collate<charT> facet contained in this.
         Specifically, this function returns the following:

       use_facet< collate<charT> >(*this).compare(s1.data(),
         s1.data()+s1.size(), s2.data(),
         s2.data()+s2.size()) < 0;

      This allows a	locale to be used with standard	algorithms, such as
      sort, to provide localized comparison of strings.

    PUBLIC MEMBER FUNCTIONS

      basic_string<char> name() const; Returns the name of this, if this
      has one;	otherwise returns the string "*".

    STATIC PUBLIC MEMBER FUNCTIONS

      static locale
      global(const locale& loc);
         Sets the global locale to loc.  This causes future	uses of	the
         default constructor for locale to return a	copy of	loc.  If loc
         has a name, this function has the further effect of
         calling std::setlocale(LC_ALL,loc.name().c_str());.  Returns the
         previous value of	 locale().

      static const locale&
      classic();

         Returns a locale with the same semantics as the classic "C" locale.

    EXAMPLE

      //
      // locale.cpp
      //

       #include <string>
       #include <vector>
       #include <iostream>
       #include "codecvte.h"

      int main ()
       {
       using namespace std;

       locale loc;	// Default locale

        // Construct new locale using default locale plus
        // user defined codecvt facet
        // This facet converts from	ISO Latin
        // Alphabet	No. 1 (ISO 8859-1) to
        // U.S. ASCII code page 437
        // This facet replaces the default for
        // codecvt<char,char,mbstate_t>
       locale my_loc(loc,new ex_codecvt);

        // imbue modified locale onto cout
       locale old =	cout.imbue(my_loc);
       cout	<< "A jolly time was had by all" << endl;

       cout.imbue(old);
       cout	<< "A jolly time was had by all" << endl;

        // Create a	vector of strings
       vector<string,allocator<void> > v;
       v.insert(v.begin(),"antelope");
       v.insert(v.begin(),"bison");
       v.insert(v.begin(),"elk");

       copy(v.begin(),v.end(),
    	ostream_iterator<string,char,
    		 char_traits<char> >(cout," "));
       cout	<< endl;

        // Sort the	strings	using the locale as a comparitor
       sort(v.begin(),v.end(),loc);

       copy(v.begin(),v.end(),
    	ostream_iterator<string,char,
    		char_traits<char> >(cout," "));

       cout	<< endl;
       return 0;
      }

    SEE ALSO

      facets, has_facet, use_facet,	specific facet reference sections

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    codecvt_byname
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      codecvt_byname - A facet that	provides code set converion
      classification facilities based on the named	locales.

    SYNOPSIS

      #include <locale>
      template <class charT> class codecvt_byname;

    DESCRIPTION

      The codecvt_byname  template provides	the same functionality as the
      codecvt template, but	specific to a particular named locale.	For a
      description of the member functions of codecvt_byname, see the
      reference for	codecvt. Only the constructor is described here.

    INTERFACE

      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_out(stateT&,
    			 const internT*,
    			 const internT*,
    			 const internT*&,
    			 externT*, externT*,
    			 externT*&) const;
       virtual result do_in(stateT&,
    			const externT*,
    			const externT*,
    			const externT*&,
    			internT*, internT*,
    			internT*&) const;

       virtual bool	do_always_noconv() const throw();
       virtual int do_length(const stateT&,	const internT*,
    			 const internT*,
       virtual int do_max_length() const throw();
       virtual int do_encoding() const throw();
      };

    CONSTRUCTOR

      explicit codecvt_byname(const	char* name, size_t refs	= 0);
         Construct a codecvt_byname	facet.	The facet will provide codeset
         conversion	relative to the	named locale specified by the name
         argument. If	the refs argument is 0,	destruction of the
         object is delegated to the locale, or	locales, containing
         it.	This allows the	user to	ignore life-time management
         issues.  On the other had,	if refs	 is 1, the object must be
         explicitly	deleted:  the locale will not do so.  In this case,
         the object	can be maintained across the lifetime of multiple
         locales.

    SEE ALSO

      locale, facets, codecvt

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    code_cvt
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      code_cvt - Code conversion facet.

    SYNOPSIS

      #include <locale>
      class	codecvt_base;

      template <class internT, class externT, class	stateT>
      class	codecvt;

    DESCRIPTION

      The codecvt<internT,externT,stateT> template provides	code
      conversion facilities.  Default implementations of
      codecvt<char,wchar_t,mbstate_t> and codecvt<wchar_t,char,mbstate_t>
      use ctype<wchar_t>::widen and ctype<wchar_t>::narrow respectively.
      The default implementation of codecvt<wchar_t,wchar_t,mbstate_t>
      simply uses memcpy	(no particular conversion applied).

    INTERFACE

      class	codecvt_base {
      public:
       enum	result { ok, partial, error, noconv };
      };

      template <class internT, class externT, class	stateT>
      class	codecvt	: public locale::facet,	public codecvt_base {
      public:
       typedef internT  intern_type;
       typedef externT  extern_type;
       typedef stateT   state_type;

       explicit codecvt(size_t = 0)
       result out(stateT&, const internT*,
    	     const internT*, const internT*&,
    	     externT*, externT*, externT*&) const;
       result in(stateT&, const externT*,
    	     const externT*, const externT*&,
    	     internT*, internT*, internT*&) const;

       bool	always_noconv()	const throw();
       int length(const stateT&, const internT*, const internT*,
    	      size_t) const;

       int max_length() const throw();
       int encoding() const	throw();
       static locale::id id;

      protected:
        ~codecvt();	 // virtual
       virtual result do_out(stateT&,
    			 const internT*,
    			 const internT*,
    			 const internT*&,
    			 externT*, externT*,
    			 externT*&) const;
       virtual result do_in(stateT&,
    			const externT*,
    			const externT*,
    			const externT*&,
    			internT*, internT*,
    			internT*&) const;

       virtual bool	do_always_noconv() const throw();
       virtual int do_length(const stateT&,	const internT*,
    			 const internT*,
    			 size_t) const;

       virtual int do_max_length() const throw();
       virtual int do_encoding() const throw();
      };

    TYPES

      intern_type
         Type of character to convert from.

      extern_type
         Type of character to convert to.

      state_type
         Type to keep track	of state and determine the direction of	the
         conversion.

    CONSTRUCTORS AND DESTRUCTORS

      explicit codecvt(size_t refs = 0)
         Construct a codecvt facet.	 If the	refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      ~codecvt();  // virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the codecvt facet provide an interface to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public length function simply calls	its protected cousin
      do_length.

      bool
      always_noconv() const
       throw();

      int
      encoding() const
       throw();

      result
      in(stateT& state, const externT* from,
        const externT* from_end, const externT*& from_next,
        internT* to, internT* to_limit, internT*& to_next) const;

      int
      length(const stateT&,	const internT* from,
    	const internT* end,
    	size_t max) const;

      int
      max_length() const
       throw();

      result
      out(stateT& state, const internT* from,
         const internT* from_end, const internT*& from_next,
         externT* to, externT* to_limit, externT*& to_next)	const;
         Each of these public member functions xxx simply calls the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual bool
      do_always_noconv() const
       throw();
         Returns true if no	conversion is required.	 This is the case if
         do_in and do_out	return noconv for all valid arguments.	The
         instantiation codecvt<char,char,mbstate_t> returns true,	while
         all other	default instantiations return false.

      virtual int
      do_encoding()	const
       throw();
         Returns one of the	following

         +	     -1	if the encoding	on the external	character sequence is
              dependent on state.

         +	     A constant	number representing the	number of external
              characters in a fixed width encoding.

         +	     0 if the encoding is uses a variable width.

      virtual result
      do_in(stateT&	state,
           const externT* from,
           const externT* from_end,
           const externT*& from_next,
           internT*	to, internT* to_limit,
           internT*& to_next) const;

      virtual result
      do_out(stateT& state,
    	const internT* from,
    	const internT* from_end,
    	const internT*&	from_next,
    	externT* to, externT* to_limit,
    	externT*& to_next) const;
         Both functions take characters in the range of [from,from_end),
         apply an appropriate conversion, and place the resulting
         characters	in the buffer starting at to.  Each function converts
         at	most from_end-from internT characters, and stores no more than
         to_limit-to externT characters. Both do_out and do_in will	stop
         if	they find a character they cannot convert.  In any case,
         from_next and to_next are always left pointing to the next
         character	beyond the last	one successfully converted.

         do_out and	do_in must be called under the following pre-conditions:

         +	     from <= from_end

         +	     to	<= to_end

         +	     state either initialized for the beginning	of a sequence or
    	  equal	to the result of the previous conversion on the	sequence.

      In	the case where no conversion is	required, from_next will be
      set	to from and to_next set to to.

         do_out and	do_in return one the following:

           Return Value   Meaning

           ok	      completed	the conversion
           partial	      not all source characters	converted
           error	      encountered a from_type character	it
    			    could not convert
           noconv	      no conversion was	needed

      If either function returns partial and (from == from_end) then one
      of	two conditions prevail:

      +	  The destination sequence has not accepted all	the converted
           characters, or

      +	  Additional internT characters	are needed before another
           externT character can be	assembled.

      virtual int
      do_length(const stateT&, const internT* from,
    	   const internT* end,
    	   size_t max) const;
         Returns the largest number	< max of internT characters available
         in the range [from,end).

         do_length must be called under the	following pre-conditions:

         +	     from <= from_end

         +	     state either initialized for the beginning	of a sequence or
    	  equal	to the result of the previous conversion on the	sequence.

      virtual int
      do_max_length() const	throw();
         Returns the maximum value that do_length can  return for any
         valid	set of	arguments.

      virtual result
      do_out(stateT& state,
    	const internT* from,
    	const internT* from_end,
    	const internT*&	from_next,
    	externT* to, externT* to_limit,
    	externT*& to_next) const;
         See do_in above.

    EXAMPLE

      //
      // codecvt.cpp
      //
      #include <sstream>
      #include "codecvte.h"

      int main ()
      {
       using namespace std;

       mbstate_t state;

        // A string	of ISO characters and buffers to hold
        // conversions
       string ins("	  );

       string ins2(ins.size(),'.');
       string outs(ins.size(),'.');

        // Print initial contents of buffers
       cout	<< "Before:0 <<	ins << endl;
       cout	<< ins2	<< endl;
       cout	<< outs	<< endl	<< endl;

        // Initialize buffers
       string::iterator in_it = ins.begin();
       string::iterator out_it = outs.begin();

        // Create a	user defined codecvt fact
        // This facet converst from	ISO Latin
        // Alphabet	No. 1 (ISO 8859-1) to
        // U.S. ASCII code page 437
        // This facet replaces the default for
        // codecvt<char,char,mbstate_t>
       locale loc(locale(),new ex_codecvt);

        // Now get the facet from the locale
       const codecvt<char,char,mbstate_t>& cdcvt =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
         use_facet<codecvt<char,char,mbstate_t> >(loc);
      #else
         use_facet(loc,(codecvt<char,char,mbstate_t>*)0);
      #endif

        // convert the buffer
       cdcvt.in(state,ins.begin(),ins.end(),in_it,
    	    outs.begin(),outs.end(),out_it);

       cout	<< "After in:0 << ins << endl;
       cout	<< ins2	<< endl;
       cout	<< outs	<< endl	<< endl;

        // Lastly, convert back to the original codeset
       in_it = ins.begin();
       out_it = outs.begin();
       cdcvt.out(state, outs.begin(),outs.end(),out_it,
    	     ins2.begin(),ins2.end(),in_it);

       cout	<< "After out:0	<< ins << endl;
       cout	<< ins2	<< endl;
       cout	<< outs	<< endl;

       return 0;
      }

    SEE ALSO

      locale, facets, codecvt_byname

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    collate
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      collate, collate_byname - String collation, comparison, and hashing
      facet.

    SYNOPSIS

      #include <locale>
      template <class charT> class collate;
      template <class charT> class collate_byname;

    DESCRIPTION

      The collate and collate_byname facets	provides string	collation,
      comparison, and hashing facilities.   collate provides these
      facilities for the "C" locale, while	collate_byname provides	the
      same thing for named locales.

    INTERFACE

      template <class charT>
      class	collate	: public locale::facet {
      public:
       typedef charT	       char_type;
       typedef basic_string<charT> string_type;
       explicit collate(size_t refs	= 0);
       int compare(const charT*, const charT*,
    	       const charT*, const charT*) const;
       string_type transform(const charT*, const charT*) const;
       long	hash(const charT*, const charT*) const;
       static locale::id id;
      protected:
        ~collate();	 // virtual
       virtual int do_compare(const	charT*,	const charT*,
    			  const	charT*,	const charT*) const;
       virtual string_type do_transform(const charT*, const	charT*)	const;
       virtual long	do_hash	(const charT*, const charT*) const;
      };

      template <class charT>
      class	collate_byname : public	collate<charT> {
      public:
       explicit collate_byname(const char*,	size_t = 0);
      protected:
        ~collate_byname();	// virtual
       virtual int do_compare(const	charT*,	const charT*,
    			  const	charT*,	const charT*) const;
       virtual string_type do_transform(const charT*, const	charT*)	const;
       virtual long	do_hash(const charT*, const charT*) const;
      };

    TYPES

      char_type
         Type of character the facet is instantiated on.

      string_type
         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit collate(size_t refs = 0)
         Construct a collate facet.	 If the	refs argument is 0,
         destruction	of the object	is delegated to	the locale, or
         locales,	containing it. This allows the	user to	ignore
         lifetime	management issues.  On the other had, if	refs
         is 1, the	object must be explicitly deleted:  the	locale will
         not do so.	 In this case, the object can be maintained across the
         life-time of multiple locales.

      explicit collate_byname(const	char* name, size_t refs	= 0);
         Construct a collate_byname	facet.	Use the	named locale specified
         by the name argument.  The refs argument serves the same purpose
         as it does for the collate constructor.

      ~collate();  // virtual and protected
      ~collate_byname();  // virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

         The public members of	the collate facet provide an interface
         to protected members.  Each public	member xxx has a corresponding
         virtual protected member do_xxx.  All work is delagated	to
         these protected members.   For instance, the	long version
         of	the public grouping function simply calls its protected cousin
         do_grouping.

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

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

      string_type
      transform(const charT* low, const charT* high) const;
         Each of these public member functions xxx simply call the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual int
      do_compare(const charT* low1,	const charT* high1,
    	    const charT* low2, const charT* high2) const;
         Returns 1 if the character	string represented by the range
         [low1,high1) is	greater	than the character string represented
         by the range [low2,high2), -1 if first string is less than the
         second, or 0 if the two are equal.  collate uses a
         lexicographical comparison.

      virtual long
      do_hash( const charT*	low, const charT* high)
         Generate a	has value from a string	defined	by the range of
         characters [low,high).  Given	two strings that compare equal
         (i.e. do_compare returns 0), do_hash returns an integer value
         that is the same for both strings.  For differing strings the
         probability that the return value will be equal is approximately
         1.0/numeric_limits<unsigned long>::max().

      virtual string_type
      do_transform(const charT* low, const charT* high) const;
         Returns a string that will	yield the same result in a
         lexicographical comparison	with another string returned from
         transform as does the do_compare	function applied to the
         original strings.  In other words, the result	of  applying a
         lexicographical comparison to two strings returned from transform
         will be the same as applying do_compare to	the original strings
         passed to	transform.

    EXAMPLE

      //
      // collate.cpp
      //
      #include <iostream>

      int main ()
      {
       using namespace std;
       locale loc;
       string s1("blue");
       string s2("blues");
        // Get a reference to the collate<char> facet
       const collate<char>&	co =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
           use_facet<collate<char> >(loc);
      #else
           use_facet(loc,(collate<char>*)0);
      #endif
        // Compare two strings
       cout	<< co.compare(s1.begin(),s1.end(),
    		      s2.begin(),s2.end()-1) <<	endl;
       cout	<< co.compare(s1.begin(),s1.end(),
    		      s2.begin(),s2.end()) << endl;
        // Retrieve	hash values for	two strings
       cout	<< co.hash(s1.begin(),s1.end())	<< endl;
       cout	<< co.hash(s2.begin(),s2.end())	<< endl;
       return 0;
      }

    SEE ALSO

      locale, facets, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    collate_byname
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      collate, collate_byname - String collation, comparison, and hashing
      facet.

    SYNOPSIS

      #include <locale>
      template <class charT> class collate;
      template <class charT> class collate_byname;

    DESCRIPTION

      The collate and collate_byname facets	provides string	collation,
      comparison, and hashing facilities.   collate provides these
      facilities for the "C" locale, while	collate_byname provides	the
      same thing for named locales.

    INTERFACE

      template <class charT>
      class	collate	: public locale::facet {
      public:
       typedef charT	       char_type;
       typedef basic_string<charT> string_type;
       explicit collate(size_t refs	= 0);
       int compare(const charT*, const charT*,
    	       const charT*, const charT*) const;
       string_type transform(const charT*, const charT*) const;
       long	hash(const charT*, const charT*) const;
       static locale::id id;
      protected:
        ~collate();	 // virtual
       virtual int do_compare(const	charT*,	const charT*,
    			  const	charT*,	const charT*) const;
       virtual string_type do_transform(const charT*, const	charT*)	const;
       virtual long	do_hash	(const charT*, const charT*) const;
      };

      template <class charT>
      class	collate_byname : public	collate<charT> {
      public:
       explicit collate_byname(const char*,	size_t = 0);
      protected:
        ~collate_byname();	// virtual
       virtual int do_compare(const	charT*,	const charT*,
    			  const	charT*,	const charT*) const;
       virtual string_type do_transform(const charT*, const	charT*)	const;
       virtual long	do_hash(const charT*, const charT*) const;
      };

    TYPES

      char_type
         Type of character the facet is instantiated on.

      string_type
         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit collate(size_t refs = 0)

         Construct a collate facet.	 If the	refs argument is 0,
         destruction	of the object	is delegated to	the locale, or
         locales,	containing it. This allows the	user to	ignore
         lifetime	management issues.  On the other had, if	refs
         is 1, the	object must be explicitly deleted:  the	locale will
         not do so.	 In this case, the object can be maintained across the
         lifetime of multiple locales.

      explicit collate_byname(const	char* name, size_t refs	= 0);
         Construct a collate_byname	facet.	Use the	named locale specified
         by the name argument.  The refs argument serves the same purpose
         as it does for the collate constructor.

      ~collate();  // virtual and protected
      ~collate_byname();  // virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the collate facet provide an interface to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public grouping function simply calls its protected cousin
      do_grouping.

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

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

      string_type
      transform(const charT* low, const charT* high) const;
         Each of these public member functions xxx simply call the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual int
      do_compare(const charT* low1,	const charT* high1,
    	    const charT* low2, const charT* high2) const;
         Returns 1 if the character	string represented by the range
         [low1,high1) is	greater	than the character string represented
         by the range [low2,high2), -1 if first string is less than the
         second, or 0 if the two are equal.  collate uses a
         lexicographical comparison.

      virtual long
      do_hash( const charT*	low, const charT* high)
         Generate a	has value from a string	defined	by the range of
         characters [low,high).  Given	two strings that compare equal
         (i.e. do_compare returns 0), do_hash returns an integer value
         that is the same for both strings.  For differing strings the
         probability that the return value will be equal is approximately
         1.0/numeric_limits<unsigned long>::max().

      virtual string_type
      do_transform(const charT* low, const charT* high) const;
         Returns a string that will	yield the same result in a
         lexicographical comparison	with another string returned from
         transform as does the do_compare	function applied to the
         original strings.  In other words, the result	of  applying a
         lexicographical comparison to two strings returned from transform
         will be the same as applying do_compare to	the original strings
         passed to	transform.

    EXAMPLE

      //
      // collate.cpp
      //
      #include <iostream>

      int main ()
      {
       using namespace std;
       locale loc;
       string s1("blue");
       string s2("blues");
        // Get a reference to the collate<char> facet
       const collate<char>&	co =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
           use_facet<collate<char> >(loc);
      #else
           use_facet(loc,(collate<char>*)0);
      #endif
        // Compare two strings
       cout	<< co.compare(s1.begin(),s1.end(),
    		      s2.begin(),s2.end()-1) <<	endl;
       cout	<< co.compare(s1.begin(),s1.end(),
    		      s2.begin(),s2.end()) << endl;
        // Retrieve	hash values for	two strings
       cout	<< co.hash(s1.begin(),s1.end())	<< endl;
       cout	<< co.hash(s2.begin(),s2.end())	<< endl;
       return 0;
      }

    SEE ALSO

      locale, facets, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    facets
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      facets - Family of classes used to encapsulate categories of locale
      functionality.

    DESCRIPTION

      The Standard C++ Localization	library	provides a locale interface
      that contains	a collection of	diverse	facets.	 Each facet
      provides localization facilities for some specific area, such as
      character classification or numeric formatting.  Each facet also
      falls into one or more broad categories.  These categories	are
      defined in the locale class, and the standard facets fit into these
      categories as follows.

      Category     Facets

      collate      collate,	collate_byname
      ctype	       ctype, codecvt, ctype_byname, codecvt_byname
      monetary     moneypunct, moneypunct_byname, money_put,
    		  money_get
      numeric      numpunct, numpunct_byname, num_put, num_get
      time	       time_put, time_put_byname, time_get,
    		  time_get_byname
      messages     messages, messages_byname

      A facet must satisfy two properties.	First, it must be derived from
      the base class locale::facet, either directly or indirectly (for
      example,	facet -> ctype<char> -> my_ctype).	Second,	it
      must	contain	a member of type locale::id.  This ensures that the
      locale class can manage its collection of facets properly.

    SEE ALSO

      locale, specific facet reference sections

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    has_facet
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      has_facet - A	function template used to determine if a locale	has a
      given facet.

    SYNOPSIS

      #include <locale>
      template <class Facet> bool has_facet(const locale&) throw();

    DESCRIPTION

      has_facet returns true if the	requested facet	is available in	the
      locale, otherwise it returns false.	You specify the	facet type by
      explicitly providing the template parameter. (See the example
      below.)

         Note that if your compiler cannot overload function templates
         on return type then you'll need	to use an alternative
         has_facet	template.  The alternative template takes	an
         additional argument that's a	pointer	to the type of facet
         you want to check on.  The declaration looks	like this:

      template <class Facet>
      const	bool has_facet(const locale&, Facet*) throw();

      The example below shows the use of both variations of	has_facet.

    EXAMPLE

      //
      // hasfacet.cpp
      //

      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       cout	<< has_facet<ctype<char> >(loc)	<< endl;
      #else
       cout	<< has_facet(loc,(ctype<char>*)0) << endl;
      #endif

       return 0;
      }

    SEE ALSO

      locale, facets, use_facet

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isalnum
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isalnum - Determines if a character is alphabetic or numeric.

    SYNOPSIS

      #include <locale>
      template <class charT>

      bool isalnum (charT c, const locale& loc) const;

    DESCRIPTION

      The isalnum function returns true if the character passed as a
      parameter is either part of the alphabet specified	by the locale
      parameter	or a decimal digit, otherwise the function
      returns	false.	 The check is made using the ctype	facet
      from the locale parameter.

    EXAMPLE

      //
      // isalnum.cpp
      //

      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

       cout	<< isalnum('a',loc) << endl;
       cout	<< isalnum(',',loc) << endl;

       return 0;
      }

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isalpha
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isalpha - Determines if a character is alphabetic.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The isslpha function returns true if the character passed as a
      parameter is part of the alphabet specified by the	locale
      parameter, otherwise the	function returns false.	The
      check is made using	the ctype facet	from the locale parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    iscntrl
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      iscntrl - Determines if a character is a control character.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The iscntrl function returns true if the character passed as a
      parameter is a control character, otherwise the function returns
      false.	The check is made using the ctype facet from the
      locale parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isdigit
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isdigit - Determines if a character is a decimal digit.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The isdigit function returns true if the character passed as a
      parameter is a decimal digit, otherwise the function returns false.
      The check is	made using	the ctype facet	from the locale
      parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isgraph
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isgraph - Determines if a character is a graphic character.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The isgraph function returns true if the character passed as a
      parameter is a graphic character, otherwise the function returns
      false.   The check is made using the ctype facet from the locale
      parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    islower
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      islower - Determines whether a character is lower case.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The islower function returns true if the character passed as a
      parameter is lower	case, otherwise	the function returns false.
      The check is made using the ctype facet from the locale parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isprint
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isprint - Determines if a character is printable.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The isprint function returns true if the character passed as a
      parameter is printable, otherwise the function returns false.  The
      check is made using the ctype facet from the locale parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    ispunct
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      ispunct - Determines if a character is punctuation.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The ispunct function returns true if the character passed as a
      parameter is punctuation, otherwise the function returns false.  The
      check	is made	using the ctype facet from the locale parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isspace
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isspace - Determines if a character is a space.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The isspace  function	returns	true if	the character passed as	a
      parameter is a space character,	otherwise the function returns
      false.  The check is made using the ctype facet from the locale
      parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isupper
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isupper - Determines whether a character is upper case.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The isupper function returns true if the character passed as a
      parameter is upper	case, otherwise	the function returns false.
      The check	is made	using the ctype facet from the locale
      parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    isxdigit
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      isxdigit - Determines	whether	a character is a hexidecimal digit.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The isxdigit function	returns	true if	the character passed as	a
      parameter is a hexidecimal digit, otherwise the	function
      returns false.	  The check is made using	the ctype
      facet	from the locale	parameter.

    SEE ALSO

      other	is_ functions, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    messages
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      messages, messages_byname - Messaging	facets.

    SYNOPSIS

      #include<locale>
      class	messages_base;

      template <class charT> class messages;

    DESCRIPTION

      messages  provides access to a localized messaging facility. The
      messages facet	provides facilities based on the "C" locale,
      while the messages_byname facet	provides the same facilities
      for named locales.

      The messages_base class provides a catalog type for use by the
      derived messages	and messages_byname classes.

      Note that the	default	messages facet uses catopen, catclose, etc.,
      to implement the	message	database.  If your platform does not
      support these then you'll need to imbue your own messages facet by
      implementing whatever database is available.

    INTERFACE

      class	messages_base {
      public:
       typedef int catalog;
      };

      template <class charT>
      class	messages : public locale::facet, public	messages_base {
      public:
       typedef charT char_type;
       typedef basic_string<charT> string_type;
       explicit messages(size_t = 0);
       catalog open(const basic_string<char>&, const locale&) const;
       string_type	get(catalog, int, int,
    		    const string_type&)	const;
       void	   close(catalog) const;
       static locale::id id;
      protected:
        ~messages();  // virtual
       virtual catalog do_open(const basic_string<char>&,
    			   const locale&) const;
       virtual string_type	do_get(catalog,	int, int,
    			       const string_type&) const;
       virtual void	   do_close(catalog) const;
      };

      class	messages_byname	: public messages<charT> {
      public:
       explicit messages_byname(const char*, size_t	= 0);
      protected:
        ~messages_byname();	 // virtual
       virtual catalog do_open(const basic_string<char>&,
    			   const locale&) const;
      virtual string_type  do_get(catalog, int, int,
    			     const string_type&) const;
       virtual void	   do_close(catalog) const;
      };

    TYPES

      char_type
         Type of character the facet is instantiated on.

      string_type
         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit messages(size_t refs	= 0)
         Construct a messages facet.  If the refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other hand, if refs is 1	then
         the object	must be	explicitly deleted:  the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      explicit messages_byname(const char* name, size_t refs = 0);
         Construct a messages_byname facet.	 Use the named locale
         specified	by the name argument.	 The refs argument serves the
         same purpose as it does for the messages constructor.

      ~messages();	// virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;

         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the messages facet provide an interface	to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public open	function simply	calls its protected cousin do_open.

      void
      close(catalog	c) const;

      string_type
      get(catalog c, int set, int msgid,
         const string_type&	dfault)	const;

      catalog
      open(const basic_string<char>& fn, const locale&) const;
         Each of these public member functions xxx simply call the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual void
      do_close(catalog cat)	const;
         Closes the	catalog.  The cat argument must	have been obtained by
         a	call to	open().

      virtual string_type
      do_get(catalog cat, int set, int msgid,
    	const string_type& dfault) const;
         Retrieves a specific message.  Returns the	message	identified by
         cat, set, msgid, and dfault.  cat must have been obtained by a
         previous	call to	open() and this	function must not be called
         with a cat that has	had close() called on yet after the
         last call to open().  In other words, the catalog must have been
         opened and not yet closed.

      virtual catalog
      do_open(const	basic_string<char>& name, const	locale&) const;
         Opens a message catalog.  Returns a catalog identifier that can
         be passed to the get() function in order to access specific
         messages. Returns -1	if the catalog name specificed in the
         name argument is invalid.  The loc argument	will be	used
         for codeset conversion if necessary.

    EXAMPLE

      //
      // messages.cpp
      //
      #include <string>
      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

        // Get a reference to the messages<char> facet
       const messages<char>& mess =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
         use_facet<messages<char> >(loc);
      #else
         use_facet(loc,(messages<char>*)0);
      #endif

        // Open a catalog and try to grab
        // both some valid messages, and an	invalid	message
       string def("Message Not Found");
       messages<char>::catalog cat =
    	   mess.open("./rwstdmessages.cat",loc);
       if (cat != -1)
        {
         string msg0 = mess.get(cat,1,1,def);
         string msg1 = mess.get(cat,1,2,def);
         string msg2 = mess.get(cat,1,6,def); // invalid msg #
         string msg3 = mess.get(cat,2,1,def);

         mess.close(cat);
         cout << msg0 << endl << msg1 << endl
    	   << msg2 << endl << msg3 << endl;
        }
       else
         cout << "Unable to	open message catalog" << endl;

       return 0;
      }

    SEE ALSO

      locale, facets

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    messages_byname
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      messages, messages_byname - Messaging	facets.

    SYNOPSIS

      #include<locale>
      class	messages_base;

      template <class charT> class messages;

    DESCRIPTION

      messages  provides access to a localized messaging facility. The
      messages facet	provides facilities based on the "C" locale,
      while the messages_byname facet	provides the same facilities
      for named locales.

      The messages_base class provides a catalog type for use by the
      derived messages	and messages_byname classes.

      Note that the	default	messages facet uses catopen, catclose, etc.,
      to implement the	message	database.  If your platform does not
      support these then you'll need to imbue your own messages facet by
      implementing whatever database is available.

    INTERFACE

      class	messages_base {
      public:
       typedef int catalog;
      };

      template <class charT>
      class	messages : public locale::facet, public	messages_base {
      public:
       typedef charT char_type;
       typedef basic_string<charT> string_type;
       explicit messages(size_t = 0);
       catalog open(const basic_string<char>&, const locale&) const;
       string_type	get(catalog, int, int,
    		    const string_type&)	const;
       void	   close(catalog) const;
       static locale::id id;
      protected:
        ~messages();  // virtual
       virtual catalog do_open(const basic_string<char>&,
    			   const locale&) const;
       virtual string_type	do_get(catalog,	int, int,
    			       const string_type&) const;
       virtual void	   do_close(catalog) const;
      };

      class	messages_byname	: public messages<charT> {
      public:
       explicit messages_byname(const char*, size_t	= 0);
      protected:
        ~messages_byname();	 // virtual
       virtual catalog do_open(const basic_string<char>&,
    			   const locale&) const;
      virtual string_type  do_get(catalog, int, int,
    			     const string_type&) const;
       virtual void	   do_close(catalog) const;
      };

    TYPES

      char_type
         Type of character the facet is instantiated on.

      string_type
         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit messages(size_t refs	= 0)
         Construct a messages facet.  If the refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other hand, if refs is 1	then
         the object	must be	explicitly deleted:  the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      explicit messages_byname(const char* name, size_t refs = 0);
         Construct a messages_byname facet.	 Use the named locale
         specified	by the name argument.	 The refs argument serves the
         same purpose as it does for the messages constructor.

      ~messages();	// virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the messages facet provide an interface	to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public open	function simply	calls its protected cousin do_open.

      void
      close(catalog	c) const;

      string_type
      get(catalog c, int set, int msgid,
         const string_type&	dfault)	const;

      catalog
      open(const basic_string<char>& fn, const locale&) const;
         Each of these public member functions xxx simply call the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual void
      do_close(catalog cat)	const;
         Closes the	catalog.  The cat argument must	have been obtained by
         a	call to	open().

      virtual string_type
      do_get(catalog cat, int set, int msgid,
    	const string_type& dfault) const;
         Retrieves a specific message.  Returns the	message	identified by
         cat, set, msgid, and dfault.  cat must have been obtained by a
         previous	call to	open() and this	function must not be called
         with a cat that has	had close() called on yet after the
         last call to open().  In other words, the catalog must have been
         opened and not yet closed.

      virtual catalog
      do_open(const	basic_string<char>& name, const	locale&) const;
         Opens a message catalog.  Returns a catalog identifier that can
         be passed to the get() function in order to access specific
         messages. Returns -1	if the catalog name specificed in the
         name argument is invalid.  The loc argument	will be	used
         for codeset conversion if necessary.

    EXAMPLE

      //
      // messages.cpp
      //
      #include <string>
      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

        // Get a reference to the messages<char> facet
       const messages<char>& mess =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
         use_facet<messages<char> >(loc);
      #else
         use_facet(loc,(messages<char>*)0);
      #endif

        // Open a catalog and try to grab
        // both some valid messages, and an	invalid	message
       string def("Message Not Found");
       messages<char>::catalog cat =
    	   mess.open("./rwstdmessages.cat",loc);
       if (cat != -1)
        {
         string msg0 = mess.get(cat,1,1,def);
         string msg1 = mess.get(cat,1,2,def);
         string msg2 = mess.get(cat,1,6,def); // invalid msg #
         string msg3 = mess.get(cat,2,1,def);

         mess.close(cat);
         cout << msg0 << endl << msg1 << endl
    	   << msg2 << endl << msg3 << endl;
        }
       else
         cout << "Unable to	open message catalog" << endl;

       return 0;
      }

    SEE ALSO

      locale, facets

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    moneypunct
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      moneypunct, moneypunct_byname	- Monetary punctuation facets.

    SYNOPSIS

      #include <locale>
      class	money_base;

      template <class charT, bool International = false>
      class	moneypunct;

    DESCRIPTION

      The moneypunct facets	provide	formatting specifications and
      punctuation character for	monetary values. The moneypunct	facet
      provides punctuation based	on the "C" locale, while the
      moneypunct_byname facet provides the same facilities for named
      locales.

      The facet is used by money_put for outputting	formatted
      representations of monetary values and by money_get for reading
      these strings back in.

      money_base provides a	structure, pattern, that specifies the order
      of	syntactic elements in a monetary	value and enumeration
      values representing those	elements.  The pattern struct provides
      a simple	array of characters, field.  Each index in	field
      is taken up by an	enumeration value indicating the location of a
      syntactic element.	The enumeration	values are described below:

      Format Flag	 Meaning

      none		 No grouping seperator
      space		 Use space for grouping	seperator
      symbol	 Currency symbol
      sign		 Sign of monetary value
      value		 The monetary value itself

      The do_pos_format an do_neg_format member functions of moneypunct
      both return the pattern type.  See	the description	of these
      functions for further elaboration.

    INTERFACE

      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_type;
       explicit moneypunct(size_t =	0);
       charT	decimal_point()	const;
       charT	thousands_sep()	const;
       string	grouping()	const;
       string_type	curr_symbol()	const;
       string_type	positive_sign()	const;
       string_type	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 string	do_grouping()	   const;
       virtual string_type	do_curr_symbol()   const;
       virtual string_type	do_positive_sign() const;
       virtual string_type	do_negative_sign() const;
       virtual int		do_frac_digits()   const;
       virtual pattern	do_pos_format()	   const;
       virtual pattern	do_neg_format()	   const;
      };

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

    TYPES

      char_type
         Type of character the facet is instantiated on.

      string_type
         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit moneypunct(size_t refs = 0)
         Constructs	a moneypunct facet.  If	the refs argument is 0 then
         destruction of the object	is delegated to	the locale, or
         locales,	containing it. This allows the user to ignore
         lifetime management issues.  On	the other had,	if refs	 is 1
         then the object must be explicitly deleted; the locale will not
         do	so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      explicit moneypunct_byname(const char* name, size_t refs = 0);
         Constructs	a moneypunct_byname facet.  Uses the named locale
         specified by	the name argument.  The	refs argument serves
         the same purpose as it does for the moneypunct constructor.

      ~moneypunct();  // virtual and protected
         Destroy the facet

    STATIC MEMBERS

      static locale::id id;

         Unique identifier for this	type of	facet.

      static const bool intl = Intl;

         true if international representation, false otherwise.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the moneypunct	and moneypunct_byname facets
      provide an interface to protected members.  Each public member xxx
      has a corresponding	virtual	protected member do_xxx.  All work is
      delagated	to these	protected members.   For instance, the
      long version of the public decimal_point	function simply	calls
      its protected cousin do_decimal_point.

      string_type  curr_symbol()   const;
      charT	       decimal_point() const;
      int	       frac_digits()   const;
      string       grouping()      const;
      pattern      neg_format()    const;
      string_type  negative_sign() const;
      pattern      pos_format()    const;
      string_type  positive_sign() const;
      charT	       thousands_sep() const;
         Each of these public member functions xxx simply calls the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual string_type
      do_curr_symbol()   const;
         Returns a string to use as	the currency symbol.

      virtual charT
      do_decimal_point() const;
         Returns the radix separator to use	if fractional digits are
         allowed (see do_frac_digits).

      virtual int
      do_frac_digits()   const;
         Returns the number	of digits in the fractional part of the
         monetary representation.

      virtual string
      do_grouping()	     const;
         Returns a string in which each character is used as an integer
         value to represent the number of digits in a particular grouping,
         starting with the rightmost group.  A group is simply the digits
         between	adjacent thousands'	separators.  Each group	at a
         position larger than the size of the string	gets the same
         value as the last	element	in the string.	If a value is less
         than	or equal to zero, or equal to CHAR_MAX,	then the size
         of	that group is unlimited.   moneypunct  returns an empty
         string,	indicating no grouping.

      virtual string_type
      do_negative_sign() const;
         A string to use as	the negative sign.  The	first character	of
         this string will be placed in the position indicated by	the
         format pattern (see do_neg_format); the rest of the characters,
         if any, will be placed after all other parts of the monetary
         value.

      virtual pattern
      do_neg_format()    const;
      virtual pattern
      do_pos_format()    const;
         Returns a pattern object specifying the location of the various
         syntactic elements in a monetary	representation.	 The
         enumeration values	symbol, sign,	and value will appear exactly
         once in this pattern, with the remaining location	taken by
         either	none or	space.	none will never occupy the	first
         position in the pattern and space	will never occupy the first or
         the last position.  Beyond these restrictions, elements may
         appear in any order.  moneypunct returns {symbol, sign, none,
         value}.

      virtual string_type
      do_positive_sign() const;
         A string to use as	the positive sign.  The	first character	of
         this string will be placed in the position indicated by	the
         format pattern (see do_pos_format); the rest of the characters,
         if any, will be placed after all other parts of the monetary
         value.

      virtual charT
      do_thousands_sep() const;
         Reurns the	grouping seperator if grouping is allowed (see
         do_grouping).

    EXAMPLE

      //
      // moneypun.cpp
      //

      #include <string>

      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

        // Get a moneypunct	facet
       const moneypunct<char,false>& mp =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<moneypunct<char,false> >(loc);
      #else
       use_facet(loc,(moneypunct<char,false>*)0);
      #endif

       cout	<< "Decimal point	 = "
    	 << mp.decimal_point() << endl;
       cout	<< "Thousands seperator	 = "
    	 << mp.thousands_sep() << endl;
       cout	<< "Currency symbol	 = "
    	 << mp.curr_symbol() <<	endl;
       cout	<< "Negative Sign	 = "
    	 << mp.negative_sign() << endl;
       cout	<< "Digits after decimal = "
    	 << mp.frac_digits() <<	endl;

       return 0;
      }

    SEE ALSO

      locale, facets, money_put, money_get

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    moneypunct_byname
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      moneypunct, moneypunct_byname	- Monetary punctuation facets.

    SYNOPSIS

      #include <locale>
      class	money_base;

      template <class charT, bool International = false>
      class	moneypunct;

    DESCRIPTION

      The moneypunct facets	provide	formatting specifications and
      punctuation character for	monetary values. The moneypunct	facet
      provides punctuation based	on the "C" locale, while the
      moneypunct_byname facet provides the same facilities for named
      locales.

      The facet is used by money_put for outputting	formatted
      representations of monetary values and by money_get for reading
      these strings back in.

      money_base provides a	structure, pattern, that specifies the order
      of	syntactic elements in a monetary	value and enumeration
      values representing those	elements.  The pattern struct provides
      a simple	array of characters, field.  Each index in	field
      is taken up by an	enumeration value indicating the location of a
      syntactic element.	The enumeration	values are described below:

      Format Flag	 Meaning

      none		 No grouping seperator
      space		 Use space for grouping	seperator
      symbol	 Currency symbol
      sign		 Sign of monetary value
      value		 The monetary value itself

      The do_pos_format an do_neg_format member functions of moneypunct
      both return the pattern type.  See	the description	of these
      functions for further elaboration.

    INTERFACE

      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_type;
       explicit moneypunct(size_t =	0);
       charT	decimal_point()	const;
       charT	thousands_sep()	const;
       string	grouping()	const;
       string_type	curr_symbol()	const;
       string_type	positive_sign()	const;
       string_type	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 string	do_grouping()	   const;
       virtual string_type	do_curr_symbol()   const;
       virtual string_type	do_positive_sign() const;
       virtual string_type	do_negative_sign() const;
       virtual int		do_frac_digits()   const;
       virtual pattern	do_pos_format()	   const;
       virtual pattern	do_neg_format()	   const;
      };

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

    TYPES

      char_type
         Type of character the facet is instantiated on.

      string_type
         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit moneypunct(size_t refs = 0)
         Constructs	a moneypunct facet.  If	the refs argument is 0 then
         destruction of the object	is delegated to	the locale, or
         locales,	containing it. This allows the user to ignore
         lifetime management issues.  On	the other hand,	if refs	 is 1
         then the object must be explicitly deleted; the locale will not
         do	so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      explicit moneypunct_byname(const char* name, size_t refs = 0);
         Constructs	a moneypunct_byname facet.  Uses the named locale
         specified by	the name argument.  The	refs argument serves
         the same purpose as it does for the moneypunct constructor.

      ~moneypunct();  // virtual and protected

         Destroy the facet

    STATIC MEMBERS

      static locale::id id;

         Unique identifier for this	type of	facet.

      static const bool intl = Intl;

         true if international representation, false otherwise.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the moneypunct	and moneypunct_byname facets
      provide an interface to protected members.  Each public member xxx
      has a corresponding	virtual	protected member do_xxx.  All work is
      delagated	to these	protected members.   For instance, the
      long version of the public decimal_point	function simply	calls
      its protected cousin do_decimal_point.

      string_type  curr_symbol()   const;
      charT	       decimal_point() const;
      int	       frac_digits()   const;
      string       grouping()      const;
      pattern      neg_format()    const;
      string_type  negative_sign() const;
      pattern      pos_format()    const;
      string_type  positive_sign() const;
      charT	       thousands_sep() const;
         Each of these public member functions xxx simply calls the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual string_type
      do_curr_symbol()   const;
         Returns a string to use as	the currency symbol.

      virtual charT
      do_decimal_point() const;
         Returns the radix separator to use	if fractional digits are
         allowed (see do_frac_digits).

      virtual int
      do_frac_digits()   const;
         Returns the number	of digits in the fractional part of the
         monetary representation.

      virtual string
      do_grouping()	     const;
         Returns a string in which each character is used as an integer
         value to represent the number of digits in a particular grouping,
         starting with the rightmost group.  A group is simply the digits
         between	adjacent thousands'	separators.  Each group	at a
         position larger than the size of the string	gets the same
         value as the last	element	in the string.	If a value is less
         than	or equal to zero, or equal to CHAR_MAX,	then the size
         of	that group is unlimited.   moneypunct  returns an empty
         string,	indicating no grouping.

      virtual string_type
      do_negative_sign() const;
         A string to use as	the negative sign.  The	first character	of
         this string will be placed in the position indicated by	the
         format pattern (see do_neg_format); the rest of the characters,
         if any, will be placed after all other parts of the monetary
         value.

      virtual pattern
      do_neg_format()    const;
      virtual pattern
      do_pos_format()    const;
         Returns a pattern object specifying the location of the various
         syntactic elements in a monetary	representation.	 The
         enumeration values	symbol, sign,	and value will appear exactly
         once in this pattern, with the remaining location	taken by
         either	none or	space.	none will never occupy the	first
         position in the pattern and space	will never occupy the first or
         the last position.  Beyond these restrictions, elements may
         appear in any order.  moneypunct returns {symbol, sign, none,
         value}.

      virtual string_type
      do_positive_sign() const;
         A string to use as	the positive sign.  The	first character	of
         this string will be placed in the position indicated by	the
         format pattern (see do_pos_format); the rest of the characters,
         if any, will be placed after all other parts of the monetary
         value.

      virtual charT
      do_thousands_sep() const;
         Reurns the	grouping seperator if grouping is allowed (see
         do_grouping).

    EXAMPLE

      //
      // moneypun.cpp
      //

      #include <string>

      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

        // Get a moneypunct	facet
       const moneypunct<char,false>& mp =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<moneypunct<char,false> >(loc);
      #else
       use_facet(loc,(moneypunct<char,false>*)0);
      #endif

       cout	<< "Decimal point	 = "
    	 << mp.decimal_point() << endl;
       cout	<< "Thousands seperator	 = "
    	 << mp.thousands_sep() << endl;
       cout	<< "Currency symbol	 = "
    	 << mp.curr_symbol() <<	endl;
       cout	<< "Negative Sign	 = "
    	 << mp.negative_sign() << endl;
       cout	<< "Digits after decimal = "
    	 << mp.frac_digits() <<	endl;

       return 0;
      }

    SEE ALSO

      locale, facets, money_put, money_get

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    money_get
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      money_get - Monetary formatting facet	for input.

    SYNOPSIS

      #include <locale>
      template <class charT, bool Intl = false,
    	   class InputIterator = istreambuf_iterator<charT> >
      class	money_get;

    DESCRIPTION

      The money_get	facet interprets formatted monetary string values.
      The	Intl template pa,rameter is used to specify locale	or
      international formatting. If Intl is true then international
      formatting	is used, otherwise locale formatting is	used.

    INTERFACE

      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_type;
       explicit money_get(size_t = 0);
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, long double&) const;
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, string_type&) const;
       static const	bool intl = Intl;
       static locale::id id;
      protected:
        ~money_get();  // virtual
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,
    			    long double&) const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,
    			    string_type&) const;
      };

    TYPES

      char_type
         Type of character upon which the facet is instantiated.

      iter_type
         Type of iterator used to scan the character buffer.

      string_type
         Type of character string passed to	member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit money_get(size_t refs = 0)
         Construct a money_get facet.  If the refs argument	is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      ~money_get();	 // virtual and	protected
         Destroy the facet

      <REFSECT1> <ANCHOR>

    STATIC MEMBERS

      static locale::id id;
         Unique identifier for this	type of	facet.

      static const bool intl = Intl;
         true if international formatting is used, false otherwise.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the money_get facet provide an interface to
      protected members.  Each public	member get has a corresponding
      virtual protected member do_get.

      iter_type
      get(iter_type	s, iter_type end, ios_base& f,
         ios_base::iostate&	err, long double& units) const;
      iter_type
      get(iter_type	s, iter_type end, ios_base& f,
         ios_base::iostate&	err, string_type& digits) const;
         Each of these two overloads of the	public member function get calls the
         corresponding protected do_get function.

    PROTECTED MEMBER FUNCTIONS

      virtual iter_type
      do_get(iter_type s, iter_type	end,
    	ios_base& f,
    	ios_base::iostate& err,
    	long double& units) const;
      virtual iter_type
      do_get(iter_type s, iter_type	end,
    	ios_base& f,
    	ios_base::iostate& err,
    	string_type& digits) const;
         Reads in a	localized character representation of a	monetary value
         and generates a generic representation, either	as a seqeuence
         of digits or as	a long double value.   In either case do_get
         uses the smallest possible unit of currency.

         Both overloads of do_get read characters from the range [s,end)
         until one of three things occurs:

         +	     A monetary	value is assembled

         +	     An	error occurs

         +	     No	more characters	are available.

         The functions use f.flags() and the moneypunct<charT> facet from
         f.getloc()	for formatting information to use in intrepreting the
         sequence of characters. do_get then places	a pure sequence	of
         digits representing the monetary value in	the smallest possible
         unit of currency into the string argument digits, or it
         calculates	a long double value based on those digits and returns
         that value	in units.

         The following specifics apply to formatting:

         +	     Digit group seperators are	optional.  If no grouping is
              specified then in thousands seperator characters are treated
              as delimiters.

         +	     If	space or none are part of the format pattern in
              moneypunct then optional whitespace is consumed, except at
              the end. See the moneypunct reference section for a description
              of money specific formatting flags.

         +	     If	iosbase::showbase is set in f.flags() then the currency
              symbol is optional, and if it appears after all other elements
              then it will not be consumed.	 Otherwise the currency	symbol
              is required, and will be consumed where ever it occurs.

         +	     digits will be preceded by	a '-' ,	or units will be negated,
              if the monetary value is	negative.

         +	     See the moneypunct	reference section for a	description of
              money specific formatting flags.

         The err argument will be set to iosbase::failbit if an error
         occurs during parsing.

         Returns an	iterator pointing one past the last character that is
         part of a valid monetary sequence.

    EXAMPLE

      //
      // moneyget.cpp
      //

      #include <string>
      #include <sstream>

      int main ()
      {
       using namespace std;
       typedef istreambuf_iterator<char,char_traits<char> >	iter_type;

       locale loc;
       string buffer("$100.02");
       string dest;
       long	double ldest;
       ios_base::iostate state;
       iter_type end;

        // Get a money_get facet
       const money_get<char,false,iter_type>& mgf =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
         use_facet<money_get<char,false,iter_type> >(loc);
      #else
         use_facet(loc,(money_get<char,false,iter_type>*)0);
      #endif

        {
          // Build an istringstream	from the buffer	and construct
          // a beginning iterator on it.
         istringstream ins(buffer);
         iter_type begin(ins);

          // Get a a string	representation of the monetary value
         mgf.get(begin,end,ins,state,dest);
        }
        {
          // Build another istringstream from the buffer, etc.
          // so we have an iterator	pointing to the	beginning
         istringstream ins(buffer);
         iter_type begin(ins);

          // Get a a long double representation
          // of the	monetary value
         mgf.get(begin,end,ins,state,ldest);
        }
       cout	<< buffer << " --> " <<	dest
    	 << " --> " << ldest <<	endl;

       return 0;
      }

    SEE ALSO

      locale, facets,money_put, moneypunct

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    money_put
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      money_put - Monetary formatting facet	for output.

    SYNOPSIS

      #include <locale>
      template <class charT, bool Intl = false,
    	   class OutputIterator	= ostreambuf_iterator<charT> >
      class	money_put;

    DESCRIPTION

      The money_put	facet takes a long double value, or generic sequence
      of digits and writes out	a formatted representation of the
      monetary value.

    INTERFACE

      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_type;
       explicit money_put(size_t = 0);
       iter_type put(iter_type, ios_base&, char_type,
    		 long double) const;
       iter_type put(iter_type, ios_base&, char_type,
    		 const string_type&) const;
       static const	bool intl = Intl;
       static locale::id id;
      protected:
        ~money_put();  // virtual
       virtual iter_type  do_put(iter_type,	ios_base&, char_type,
    			     long double) const;
       virtual iter_type do_put(iter_type, ios_base&, char_type,
    			    const string_type&)	const;
      };

    TYPES

      char_type
         Type of the character upon	which the facet	is instantiated.

      iter_type
         Type of iterator used to scan the character buffer.

      string_type
         Type of character string passed to	member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit money_put(size_t refs = 0)
         Construct a  money_put facet.  If the refs argument	is 0
         then destruction of	the object is delegated	to the locale,
         or locales, containing it. This allows the user to ignore
         lifetime management	issues.	 On the	other had, if refs  is
         1	then the object	must be	explicitly deleted; the locale will
         not do	so.  In	this case, the object can be maintained across
         the	lifetime of multiple locales.

      ~money_put();	 // virtual and	protected
         Destroy the facet

    STATIC MEMBERS

      static locale::id id;
         Unique identifier for this	type of	facet.

      static const bool intl = Intl;
         true if international representation, false otherwise.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the money_put facet provide an interface to
      protected members.  Each public	member put has a corresponding
      virtual protected member do_put.

      iter_type
      put(iter_type	s, ios_base& f,	char_type fill,
         long double units)	const;
      iter_type
      put(iter_type	s, ios_base& f,	char_type fill,
         const string_type&	digits)	const;

         Each of these two overloads of the	public member function put
         simply calls the corresponding protected do_put function.

    PROTECTED MEMBER FUNCTIONS

      virtual iter_type
      do_put(iter_type s, ios_base&	f, char_type fill,
    	long double units) const;

         Writes out	a character string representation of the monetary
         value	contained in units.  Since units represents the
         monetary value in the	smallest possible unit	of
         currency any	fractional portions of the value are ignored.
         f.flags() and the moneypunct<charT> facet from f.getloc() provide
         the formatting information.

         The fill argument is used for any padding.

         Returns an	iterator pointing one past the last character written.

      virtual iter_type
      do_put(iter_type s, ios_base&	f, char_type fill,
    	const string_type& digits) const;
         Writes out	a character string representation of the monetary
         contained in	digits.	 digits	represents the monetary	value
         as a sequence of digits in	the smallest possible unit of
         currency.	 do_put	only looks at an optional -	character and
         any immediatly contigous digits.	f.flags() and the
         moneypunct<charT> facet from f.getloc() provide the formatting
         information.

         The fill argument is used for any padding.

         Returns an	iterator pointing one past the last character written.

    EXAMPLE

      //
      // moneyput.cpp
      //

      #include <string>
      #include <iostream>

      int main ()
      {
       using namespace std;

       typedef ostreambuf_iterator<char,char_traits<char> >	iter_type;

       locale loc;
       string buffer("10002");
       long	double ldval = 10002;

        // Construct a ostreambuf_iterator on cout
       iter_type begin(cout);

        // Get a money put facet
       const money_put<char,false,iter_type>& mp =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<money_put<char,false,iter_type> >(loc);
      #else
       use_facet(loc,(money_put<char,false,iter_type>*)0);
      #endif

        // Put out the string representation of the	monetary value
       cout	<< buffer << " --> ";
       mp.put(begin,cout,' ',buffer);

        // Put out the long	double representation
        // of the monetary value
       cout	<< endl	<< ldval << " --> ";
       mp.put(begin,cout,' ',ldval);

       cout	<<  endl;

       return 0;
      }

    SEE ALSO

      locale, facets, money_get, moneypunct

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    numpunct
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      numpunct, numpunct_byname - Numeric punctuation facet.

    SYNOPSIS

      #include <locale>
      template <class charT>  class	numpunct;
      template <class charT>  class	numpunct_byname;

    DESCRIPTION

      The numpunct<charT> facet specifies numeric punctuation.  This
      template provides punctuation based on	the "C"	locale,	while
      the numpunct_byname facet	provides the same facilities for named
      locales.

      Both num_put and num_get make	use of this facet.

    INTERFACE

      template <class charT>
      class	numpunct : public locale::facet	{
      public:
       typedef charT	       char_type;
       typedef basic_string<charT> string_type;
       explicit numpunct(size_t refs = 0);
       char_type	decimal_point()	  const;
       char_type	thousands_sep()	  const;
       string	grouping()	  const;
       string_type	truename()	  const;
       string_type	falsename()	  const;
       static locale::id id;
      protected:
        ~numpunct();  // virtual
       virtual char_type	do_decimal_point() const;
       virtual char_type	do_thousands_sep() const;
       virtual string	do_grouping()	   const;
       virtual string_type	do_truename()	   const;  // for bool
       virtual string_type	do_falsename()	   const;  // for bool
      };

      template <class charT>
      class	numpunct_byname	: public numpunct<charT> {
      public:
       explicit numpunct_byname(const char*, size_t	refs = 0);
      protected:
        ~numpunct_byname();	 // virtual
       virtual char_type	do_decimal_point() const;
       virtual char_type	do_thousands_sep() const;
       virtual string	do_grouping()	   const;
       virtual string_type	do_truename()	   const;  // for bool
       virtual string_type	do_falsename()	   const;  // for bool
      };

    TYPES

      char_type
         Type of character upon which the facet is instantiated.

      string_type

         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit numpunct(size_t refs	= 0)
         Construct a numpunct facet.  If the refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      explicit numpunct_byname(const char* name, size_t refs = 0);
         Construct a numpunct_byname facet.	 Use the named locale
         specified	by the name argument.	 The refs argument serves the
         same purpose as it does for the numpunct constructor.

      ~numpunct();	// virtual and protected
      ~numpunct_byname();  // virtual and protected

         Destroy the facet

    FACET ID

      static locale::id id;

         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the numpunct facet provide an interface	to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public grouping function simply calls its protected cousin
      do_grouping.

      char_type    decimal_point()	 const;
      string_type  falsename()	 const;
      string       grouping()	 const;
      char_type    thousands_sep()	 const;
      string_type  truename()	 const;

         Each of these public member functions xxx simply call the
         corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual char_type
      do_decimal_point() const;

         Returns the decimal radix separator .  numpunct returns '.'.

      virtual string_type
      do_falsename()     const;  //	for bool
      virtual string_type
      do_truename()	     const;  //	for bool

         Returns a string representing the name of the boolean values true
         and false respectively.  numpunct returns  "true" and
         "false".

      virtual string
      do_grouping()	     const;

         Returns a string in which each character is used as an integer
         value to represent the number of digits in a particular grouping,
         starting with the rightmost group.  A group is simply the digits
         between	adjacent thousands separators.  Each group at a
         position larger than the size of the string	gets the same
         value as the last	element	in the string.	If a value is less
         than	or equal to zero, or equal to CHAR_MAX then the	size
         of	that group is unlimited.  numpunct returns an empty string,
         indicating no grouping.

      virtual char_type
      do_thousands_sep() const;

         Returns the decimal digit group seperator.	 numpunct returns ','.

    EXAMPLE

      //
      // numpunct.cpp
      //

      #include <iostream>

      int main ()
      {
       using namespace std;
       locale loc;

        // Get a numpunct facet
       const numpunct<char>& np =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<numpunct<char> >(loc);
      #else
       use_facet(loc,(numpunct<char>*)0);
      #endif

       cout	<< "Decimal point	= "
    	 << np.decimal_point() << endl;
       cout	<< "Thousands seperator	= "
    	 << np.thousands_sep() << endl;
       cout	<< "True name		= "
    	 << np.truename() << endl;
       cout	<< "False name		= "
    	 << np.falsename() << endl;

       return 0;
      }

    SEE ALSO

      locale, facets, num_put, num_get, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    numpunct_byname
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      numpunct, numpunct_byname - Numeric punctuation facet.

    SYNOPSIS

      #include <locale>
      template <class charT>  class	numpunct;
      template <class charT>  class	numpunct_byname;

    DESCRIPTION

      The numpunct<charT> facet specifies numeric punctuation.  This template
      provides punctuation based on	the "C"	locale,	while the numpunct_byname
      facet	provides the same facilities for named locales.

      Both num_put and num_get make	use of this facet.

    INTERFACE

      template <class charT>
      class	numpunct : public locale::facet	{
      public:
       typedef charT	       char_type;
       typedef basic_string<charT> string_type;
       explicit numpunct(size_t refs = 0);
       char_type	decimal_point()	  const;
       char_type	thousands_sep()	  const;
       string	grouping()	  const;
       string_type	truename()	  const;
       string_type	falsename()	  const;
       static locale::id id;
      protected:
        ~numpunct();  // virtual
       virtual char_type	do_decimal_point() const;
       virtual char_type	do_thousands_sep() const;
       virtual string	do_grouping()	   const;
       virtual string_type	do_truename()	   const;  // for bool
       virtual string_type	do_falsename()	   const;  // for bool
      };

      template <class charT>
      class	numpunct_byname	: public numpunct<charT> {
      public:
       explicit numpunct_byname(const char*, size_t	refs = 0);
      protected:
        ~numpunct_byname();	 // virtual
       virtual char_type	do_decimal_point() const;
       virtual char_type	do_thousands_sep() const;
       virtual string	do_grouping()	   const;
       virtual string_type	do_truename()	   const;  // for bool
       virtual string_type	do_falsename()	   const;  // for bool
      };

    TYPES

      char_type
         Type of character upon which the facet is instantiated.

      string_type

         Type of character string returned by member functions.

    CONSTRUCTORS AND DESTRUCTORS

      explicit numpunct(size_t refs	= 0)
         Construct a numpunct facet.  If the refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      explicit numpunct_byname(const char* name, size_t refs = 0);
         Construct a numpunct_byname facet.	 Use the named locale
         specified	by the name argument.	 The refs argument serves the
         same purpose as it does for the numpunct constructor.

      ~numpunct();	// virtual and protected
      ~numpunct_byname();  // virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;

         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the numpunct facet provide an interface	to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public grouping function simply calls its protected cousin
      do_grouping.

      char_type    decimal_point()	 const;
      string_type  falsename()	 const;
      string       grouping()	 const;
      char_type    thousands_sep()	 const;
      string_type  truename()	 const;

      Each of these public member functions xxx simply call the
      corresponding protected do_xxx function.

    PROTECTED MEMBER FUNCTIONS

      virtual char_type
      do_decimal_point() const;

         Returns the decimal radix separator .  numpunct returns '.'.

      virtual string_type
      do_falsename()     const;  //	for bool
      virtual string_type
      do_truename()	     const;  //	for bool

         Returns a string representing the name of the boolean values true
         and false respectively.  numpunct returns  "true" and
         "false".

      virtual string
      do_grouping()	     const;

         Returns a string in which each character is used as an integer
         value to represent the number of digits in a particular grouping,
         starting with the rightmost group.  A group is simply the digits
         between	adjacent thousands separators.  Each group at a
         position larger than the size of the string	gets the same
         value as the last	element	in the string.	If a value is less
         than	or equal to zero, or equal to CHAR_MAX then the	size
         of	that group is unlimited.  numpunct returns an empty string,
         indicating no grouping.

      virtual char_type
      do_thousands_sep() const;

         Returns the decimal digit group seperator.	 numpunct returns ','.

    EXAMPLE

      //
      // numpunct.cpp
      //

      #include <iostream>

      int main ()
      {
       using namespace std;
       locale loc;

        // Get a numpunct facet
       const numpunct<char>& np =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<numpunct<char> >(loc);
      #else
       use_facet(loc,(numpunct<char>*)0);
      #endif

       cout	<< "Decimal point	= "
    	 << np.decimal_point() << endl;
       cout	<< "Thousands seperator	= "
    	 << np.thousands_sep() << endl;
       cout	<< "True name		= "
    	 << np.truename() << endl;
       cout	<< "False name		= "
    	 << np.falsename() << endl;

       return 0;
      }

    SEE ALSO

      locale, facets, num_put, num_get, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    num_get
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      num_get - Numeric formatting facet for input.

    SYNOPSIS

      #include <locale>
      template <class charT, class InputIterator > class num_get;

    DESCRIPTION

      The num_get provides facilities for formatted	input of numbers.
      basic_istream	and all	other input-oriented streams use this facet to imple-
      ment formatted numeric input.

    INTERFACE

      template <class charT, class InputIterator = istreambuf_iterator<charT> >
      class	num_get	: public locale::facet {
      public:
       typedef charT	    char_type;
       typedef InputIterator    iter_type;
       explicit num_get(size_t refs	= 0);
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, bool&)	     const;
       iter_type get(iter_type, iter_type, ios_base& ,
    		 ios_base::iostate&, long&)	     const;
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, unsigned short&) const;
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, unsigned int&)  const;
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, unsigned long&) const;
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, float&)	     const;
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, double&)	     const;
       iter_type get(iter_type, iter_type, ios_base&,
    		 ios_base::iostate&, long double&)   const;
       static locale::id id;

      protected:
        ~num_get();	 // virtual
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,	bool&) const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,	long&) const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,
    			    unsigned short&) const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,
    			    unsigned int&) const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,
    			    unsigned long&) const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,	float&)	const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,	double&) const;
       virtual iter_type do_get(iter_type, iter_type, ios_base&,
    			    ios_base::iostate&,
    			    long double&) const;
      };

    TYPES

      char_type
         Type of character the facet is instantiated on.

      iter_type
         Type of iterator used to scan the character buffer.

    CONSTRUCTOR AND	DESTRUCTOR

      explicit num_get(size_t refs = 0)
         Construct a num_get facet.	 If the	refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      ~num_get();  // virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the num_get facet provide an interface to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.  For instance, the	long version of	the
      public get function	simply calls its protected cousin
      do_get.

      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, bool& v)	       const;
      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, long& v)	       const;
      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, unsigned short& v)	const;
      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, unsigned int& v)  const;
      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, unsigned long& v) const;
      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, float& v)	       const;
      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, double& v)	       const;
      iter_type
      get(iter_type	in, iter_type end, ios_base& io,
         ios_base::iostate&	err, long double& v)   const;
         Each of the eight overloads of the	get function simply call the
         corresponding do_get function.

    PROTECTED MEMBER FUNCTIONS

      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& err,	bool& v) const;
      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& err,	long& v) const;
      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& err,
    	unsigned short&	v) const;
      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& err,
    	unsigned int& v) const;
      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& err,
    	unsigned long& v) const;
      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& err,	float& v) const;
      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& err,	double&	v) const;
      virtual iter_type
      do_get(iter_type in, iter_type end, ios_base&	io,
    	ios_base::iostate& long	double&	v) const;

         The eight overloads of the	do_get member function all take	a
         sequence of characters	[int,end), and extract a numeric
         value.	 The numeric value is returned in v.   The io argument
         is used to obtain	formatting information and the err argument
         is used to set error conditions in a calling stream.

    EXAMPLE

      //
      // numget.cpp
      //

      #include <sstream>

      int main ()
      {
       using namespace std;

      typedef istreambuf_iterator<char,char_traits<char> > iter_type;

       locale loc;
       ios_base::iostate state;
       bool	bval = false;
       long	lval = 0L;
       long	double ldval = 0.0;
       iter_type end;

        // Get a num_get facet
       const num_get<char,iter_type>& tg =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<num_get<char,iter_type> >(loc);
      #else
       use_facet(loc,(num_get<char,iter_type>*)0);
      #endif

        {
          // Build an istringstream	from the buffer	and construct
          // beginning and ending iterators	on it.
         istringstream ins("true");
         iter_type begin(ins);

          // Get a bool value
         tg.get(begin,end,ins,state,bval);
        }
       cout	<< bval	<< endl;
        {
          // Get a long value
         istringstream ins("2422235");
         iter_type begin(ins);
         tg.get(begin,end,ins,state,lval);
        }
       cout	<< lval	<< endl;
        {
          // Get a long double value
         istringstream ins("32324342.98908");
         iter_type begin(ins);
         tg.get(begin,end,ins,state,ldval);
        }
       cout	<< ldval << endl;
       return 0;
      }

    SEE ALSO

      locale, facets, num_put, numpunct, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    num_put
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      num_put - Numeric formatting	facet for output.

    SYNOPSIS

      #include <locale>
      template <class charT, class OutputIterator> class num_put;

    DESCRIPTION

      The num_put<charT,OutputIterator> template provides facilities for
      formatted output of	numbers.  basic_ostream	and all	other input
      oriented streams use this facet to implement formatted
      numeric	output.

    INTERFACE

      template <class charT, class OutputIterator =
                ostreambuf_iterator<charT> >
      class	num_put	: public locale::facet {
      public:
       typedef charT	    char_type;
       typedef OutputIterator   iter_type;
       explicit num_put(size_t = 0);

       iter_type put(iter_type, ios_base&, char_type, bool)	const;
       iter_type put(iter_type, ios_base&, char_type, long)	const;
       iter_type put(iter_type, ios_base&, char_type,
    		 unsigned long)	const;
       iter_type put(iter_type, ios_base&, char_type,
    		 double) const;
       iter_type put(iter_type, ios_base&, char_type,
    		 long double) const;
       static locale::id id;

      protected:
        ~num_put();	 // virtual
       virtual iter_type do_put(iter_type, ios_base&, char_type,
    			    bool) const;
       virtual iter_type do_put(iter_type, ios_base&, char_type,
    			    long) const;
       virtual iter_type do_put(iter_type, ios_base&, char_type,
    			    unsigned long) const;
       virtual iter_type do_put(iter_type, ios_base&, char_type,
    			    double) const;
       virtual iter_type do_put(iter_type, ios_base&, char_type,
    			    long double) const;
      };

    TYPES

      char_type
         Type of character upon which the facet is instantiated.

      iter_type
         Type of iterator used to scan the character buffer.

    CONSTRUCTORS AND DESTRUCTORS

      explicit num_put(size_t refs = 0)
         Construct a num_put facet.	 If the	refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      ~num_put();  // virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the num_put facet provide an interface to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public put function	simply calls its protected cousin
      do_put.

      iter_type
      put(iter_type	s, ios_base& io, char_type fill, bool v) const;
      iter_type
      put(iter_type	s, ios_base& io, char_type fill, long v) const;
      iter_type
      put(iter_type	s, ios_base& io, char_type fill,
         unsigned long v) const;
      iter_type
      put(iter_type	s, ios_base& io, char_type fill, double	v) const;
      iter_type
      put(iter_type	s, ios_base& io, char_type fill, long double v)	const;

         Each of the five overloads	of the put function simply call	the
         corresponding do_put function.

    PROTECTED MEMBER FUNCTIONS

      virtual iter_type
      do_put(iter_type s, ios_base&	io,
    	char_type fill,	bool v)	const;
      virtual iter_type
      do_put(iter_type s, ios_base&	io,
    	char_type fill,	long v)	const;
      virtual iter_type
      do_put(iter_type s, ios_base&	io,
    	char_type fill,unsigned	long) const;
      virtual iter_type
      do_put(iter_type s, ios_base&	io,
    	char_type fill,	double v) const;
      virtual iter_type
      do_put(iter_type s, ios_base&	io,
    	char_type fill,long double v) const;

         The five overloads	of the do_put member function all take a
         numeric value and output a	formatted character string
         representing	that value. The character string is output
         through the	s argument to the function. The io argument is
         used to	obtain formatting specifications, and the fill
         argument determines the character to use in padding.

    EXAMPLE

      //
      // numput.cpp
      //

      #include <iostream>

      int main ()
      {
       using namespace std;

       typedef ostreambuf_iterator<char,char_traits<char> >	iter_type;

       locale loc;
       bool	bval = true;
       long	lval = 422432L;
       unsigned long ulval = 12328889UL;
       double dval = 10933.8934;
       long	double ldval = 100028933.8934;

        // Construct a ostreambuf_iterator on cout
       iter_type begin(cout);

        // Get a num_put facet reference
       const num_put<char,iter_type>& np =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<num_put<char,iter_type> >(loc);
      #else
       use_facet(loc,(num_put<char,iter_type>*)0);
      #endif

        // Put out a bool
       cout	<< bval	<< " --> ";
       np.put(begin,cout,' ',bval);

        // Put out a long
       cout	<< endl	<< lval	<< " --> ";
       np.put(begin,cout,' ',lval);

        // Put out an unsigned long
       cout	<< endl	<< ulval << " --> ";
       np.put(begin,cout,' ',ulval);

        // Put out a double
       cout	<< endl	<< dval	<< " --> ";
       np.put(begin,cout,' ',dval);

        // Put out a long double
       cout	<< endl	<< ldval << " --> ";
       np.put(begin,cout,' ',ldval);

       cout	<<  endl;

       return 0;
      }

    SEE ALSO

      locale, facets, numget, numpunct, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    time_get
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      time_get - Time formatting facet for input.

    SYNOPSIS

      #include <locale>
      class	time_base;
      template <class charT, class InputIterator =
    	   istreambuf_iterator<charT> >
      class	time_get;

    DESCRIPTION

      The time_get facet extracts time and date components from a
      character string and stores the	resulting values in a struct
      tm	argument.  The facet parses the string using a specific format
      as a guide.	   If the string does not fit the format, then the
      facet will indicate an error by setting the err argument in the
      public member functions to iosbase::failbit.  See member function
      descriptions for details.

      The time_base	class provides a set of	values for specifying the
      order	in which	the three parts	of a date appear.  The
      dateorder function returns one of these five	possible values:

      Order	       Meaning
      noorder      Date format has no set ordering
      dmy	       Date order is day, month, year
      mdy	       Date order is  month, day, year
      ymd	       Date order is  year, month, day
      ydm	       Date order is year, day,	month

    INTERFACE

      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;
       explicit time_get(size_t = 0);
       dateorder date_order()  const;
       iter_type get_time(iter_type, iter_type, ios_base&,
    		      ios_base::iostate&, tm*)	const;
       iter_type get_date(iter_type, iter_type, ios_base&,
    		      ios_base::iostate&, tm*)	const;
       iter_type get_weekday(iter_type, iter_type, ios_base&,
    			 ios_base::iostate&, tm*) const;
       iter_type get_monthname(iter_type, iter_type, ios_base&,
    			   ios_base::iostate&, tm*) const;
       iter_type get_year(iter_type, iter_type, ios_base&,
    		      ios_base::iostate&, tm*) const;
       static locale::id id;
      protected:
        ~time_get();  // virtual
       virtual dateorder do_date_order()  const;
       virtual iter_type do_get_time(iter_type, iter_type, os_base&,
    				 ios_base::iostate&, tm*) const;
       virtual iter_type do_get_date(iter_type, iter_type, ios_base&,
    				 ios_base::iostate&, tm*) const;
       virtual iter_type do_get_weekday(iter_type, iter_type, os_base&,
    				    ios_base::iostate&,	tm*) const;
       virtual iter_type do_get_monthname(iter_type, ios_base&,
    				      ios_base::iostate&, tm*) const;
       virtual iter_type do_get_year(iter_type, iter_type, ios_base&,
    				 ios_base::iostate&, tm*) const;
      };

    TYPES

      char_type
         Type of character the facet is instantiated on.

      iter_type

         Type of iterator used to scan the character buffer.

    CONSTRUCTORS AND DESTRUCTORS

      explicit time_get(size_t refs	= 0)
         Construct a time_get facet.  If the refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      ~time_get();	// virtual and protected
         Destroy the facet

    FACET ID

      static locale::id id;
         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      The public members of	the time_get facet provide an interface	to
      protected members.  Each public	member xxx has a corresponding
      virtual protected member do_xxx.  All work is delagated	to
      these protected members.   For instance, the	long version of	the
      public get_time function simply calls its protected cousin
      do_get_time.

      dateorder
      date_order()	const;
      iter_type
      get_date(iter_type s,	iter_type end, ios_base& f,
    	  ios_base::iostate& err, tm* t)  const;
      iter_type
      get_monthname(iter_type s, iter_type end, ios_base& f,
    	       ios_base::iostate& err, tm* t) const;
      iter_type
      get_time(iter_type s,	iter_type end, ios_base& f,
    	  ios_base::iostate& err, tm* t)  const;
      iter_type
      get_weekday(iter_type	s, iter_type end, ios_base& f,
    	     ios_base::iostate&	err, tm* t) const;
      iter_type
      get_year(iter_type s,	iter_type end, ios_base& f,
    	  ios_base::iostate& err, tm* t) const;
         Each of these public functions simply calls a corresponding protected
         virtual do_ function.

    PROTECTED MEMBER FUNCTIONS

      virtual dateorder
      do_date_order()  const;

         Return the	a value	indicating the relative	ordering of the	three
         basic parts of a	date.  Possible	return values are:

         +	     noorder, indicating that the date format has no ordering,
              an ordering cannot be determined, or the	date format
              contains variable components other than	Month, Day and
              Year.  noorder is never returned by the default time_put, but
              may be used by derived classes.

         +	     one of dmy, mdy, ymd, ydm,	indicating the relative	ordering
              of Day, Month and Year.

      virtual iter_type
      do_get_date(iter_type	s, iter_type end, ios_base&,
    	     ios_base::iostate&	err, tm* t) const;

         Fills out the t argument with date	values parsed from the
         character buffer specified by the range (s,end].  If	the
         buffer does	not contain a valid date	representation
         then the	err argument will be set to iosbase::failbit.

         Returns an	iterator pointing just beyond the last character that
         can be determined	to be part of a	valid date.

      virtual iter_type
      do_get_monthname(iter_type s,	ios_base&,
    		  ios_base::iostate& err, tm* t) const;

         Fills out the tm_mon member of the	t argument with	a month	name
         parsed from the character	buffer specified by the	range (s,end].
         As with do_get_weekday, this name may be an abbreviation, but the
         function	will attempt to	read a full name if valid characters
         are found after an abbreviation.  For	example, if a full
         name	is "December", and an abbreviation is	"Dec", then
         the	string "Dece" will cause an error. If an error occurs
         then the  err	argument will be set to	iosbase::failbit.

         Returns an	iterator pointing just beyond the last character that
         can be determined	to be part of a	valid name.

      virtual iter_type
      do_get_time(iter_type	s, iter_type end, os_base&,
    	     ios_base::iostate&	err, tm* t) const;

         Fills out the t argument with time	values parsed from the
         character buffer specified by the range (s,end].  The buffer
         must contain a valid time representation. Returns an iterator
         pointing just beyond the last character that can	be determined
         to be part of a valid time.

      virtual iter_type

      do_get_weekday(iter_type s, iter_type	end, os_base&,
    		ios_base::iostate& err,	tm* t) const;

         Fills out the tm_wday member of the t argument with a weekday
         name parsed from the character buffer specified	by the range
         (s,end].  This name may be an abbreviation, but the function will
         attempt	to read	a full name if valid	characters are found
         after an abbreviation.  For instance, if a full name is "Monday",
         and an abbreviation is "Mon", then the string	"Mond" will
         cause an error. If an error	occurs then the	 err argument
         will be set to iosbase::failbit.

         Returns an	iterator pointing just beyond the last character that
         can be determined	to be part of a	valid name.

      virtual iter_type

      do_get_year(iter_type	s, iter_type end, ios_base&,
    	     ios_base::iostate&	err, tm* t) const;

         Fills in the tm_year member of the	t argument with	a year parsed
         from the character buffer specified by the range (s,end].  If an
         error occurs then the  err argument will be set	to
         iosbase::failbit.

         Returns an	iterator pointing just beyond the last character that
         can be determined	to be part of a	valid year.

    EXAMPLE

      //
      // timeget.cpp
      //
      #include <locale>
      #include <sstream>
      #include <time.h>

       using namespace std;

      // Print out a tm struct
      ostream& operator<< (ostream&	os, const struct tm& t)
      {
       os << "Daylight Savings = " << t.tm_isdst <<	endl;
       os << "Day of year	   = " << t.tm_yday << endl;
       os << "Day of week	   = " << t.tm_wday << endl;
       os << "Year		   = " << t.tm_year << endl;
       os << "Month		   = " << t.tm_mon << endl;
       os << "Day of month	   = " << t.tm_mday << endl;
       os << "Hour		   = " << t.tm_hour << endl;
       os << "Minute	   = " << t.tm_min << endl;
       os << "Second	   = " << t.tm_sec << endl;
       return os;
      }

      int main ()
      {
       typedef istreambuf_iterator<char,char_traits<char> >	iter_type;

       locale loc;
       time_t tm = time(NULL);
       struct tm* tmb = localtime(&tm);
       struct tm timeb;
       memcpy(&timeb,tmb,sizeof(struct tm));
       ios_base::iostate state;
       iter_type end;

        // Get a time_get facet
       const time_get<char,iter_type>& tg =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<time_get<char,iter_type> >(loc);
      #else
       use_facet(loc,(time_get<char,iter_type>*)0);
      #endif

       cout	<< timeb << endl;
        {
          // Build an istringstream	from the buffer	and construct
          // beginning and ending iterators	on it.
         istringstream ins("12:46:32");
         iter_type begin(ins);

          // Get the time
         tg.get_time(begin,end,ins,state,&timeb);
        }
       cout	<< timeb << endl;
        {
          // Get the date
         istringstream ins("Dec 6 1996");
         iter_type begin(ins);
         tg.get_date(begin,end,ins,state,&timeb);
        }
       cout	<< timeb << endl;
        {
          // Get the weekday
         istringstream ins("Tuesday");
         iter_type begin(ins);
         tg.get_weekday(begin,end,ins,state,&timeb);
        }
       cout	<< timeb << endl;
       return 0;
      }

    SEE ALSO

      locale, facets, time_put

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    time_get_byname
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      time_get_byname - A facet that provides formatted time input
      facilities based	on the named locales.

    SYNOPSIS

      #include <locale>
      template <class charT, class InputIterator =
    	   istreambuf_iterator<charT> >
      class	time_get_byname;

    DESCRIPTION

      The time_get_byname  template	provides the same functionality	as the
      time_get  template, but specific to a	particular named locale.  For
      a description of the member functions of time_get_byname, see the
      reference for time_get.	 Only the constructor is described
      here.

    INTERFACE

      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	= 0);
      protected:
        ~time_get_byname();	 // virtual
       virtual dateorder do_date_order()  const;
       virtual iter_type do_get_time(iter_type, iter_type, ios_base&,
    				 ios_base::iostate&, tm*) const;
       virtual iter_type do_get_date(iter_type, iter_type, ios_base&,
    				 ios_base::iostate&, tm*) const;
       virtual iter_type do_get_weekday(iter_type, iter_type, ios_base&,
    				  ios_base::iostate& err, tm*) const;
       virtual iter_type do_get_monthname(iter_type, iter_type, ios_base&,
    				      ios_base::iostate&, tm*) const;
       virtual iter_type do_get_year(iter_type, iter_type, ios_base&,
    				 ios_base::iostate&, tm*) const;
      };

    CONSTRUCTOR

      explicit time_get_byname(const char* name, size_t refs = 0);
         Construct a time_get_byname facet.	 The facet will	provide	time
         formatting facilities relative to the named locale specified by
         the name	argument. If the refs argument	is 0 then
         destruction of the object is delegated to the locale, or locales,
         containing it. This allows the user to	ignore lifetime
         management issues.  On the other had, if refs  is 1 then the
         object must be explicitly	deleted; the locale will not do	so. In
         this case, the object can be maintained	across the lifetime of
         multiple locales.

    SEE ALSO

      locale, facets, time_get, time_put_byname

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    time_put
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      time_put - Time formatting facet for ouput.

    SYNOPSIS

      #include <locale>
      template <class charT, class OutputIterator =
    	   ostreambuf_iterator<charT> >
      class	time_put;

    DESCRIPTION

      The time_put facet provides facilities for formated output of
      date/time values.  The member function of time_put take	a
      date/time in the form	of a struct tm and	translate this into
      character string representation.

    INTERFACE

      template <class charT, class OutputIterator =
    	   ostreambuf_iterator<charT> >
      class	time_put : public locale::facet	{
      public:
       typedef charT	    char_type;
       typedef OutputIterator   iter_type;
       explicit time_put(size_t = 0);
       iter_type put(iter_type, ios_base&,
    		 char_type, const tm*,
    		 const charT*, const charT*) const;
       iter_type put(iter_type, ios_base&, char_type,
    		 const tm*, char, char = 0) const;
       static locale::id id;
      protected:
        ~time_put();  // virtual
       virtual iter_type do_put(iter_type, ios_base&,
    			    char_type, const tm*,
    			    char, char)	const;
      };

    TYPES

      char_type
         Type of character the facet is instantiated on.

      iter_type

         Type of iterator used to scan the character buffer.

    CONSTRUCTORS AND DESTRUCTORS

      explicit time_put(size_t refs	= 0)

         Construct a time_put facet.  If the refs argument is 0 then
         destruction of	the object is delegated	to the locale, or
         locales, containing it. This allows the user to ignore lifetime
         management	issues.	 On the	other had, if refs  is 1	then
         the object	must be	explicitly deleted; the locale will not do
         so.  In	this case, the object can be maintained across the
         lifetime of multiple locales.

      ~time_put();	// virtual and protected

         Destroy the facet

    FACET ID

      static locale::id id;

         Unique identifier for this	type of	facet.

    PUBLIC MEMBER FUNCTIONS

      iter_type
      put(iter_type	s, ios_base& f,
         char_type fill, const tm* tmb,
         const charT* pattern, const charT*	pat_end) const;

         Creates a character string	representing the Date/Time contained
         in	tmb. The format	of the string is determined by a sequence of
         format modifiers contained in the range [pattern,pat_end).	These
         modifiers	are from the same set as those use by the strftime
         function and	apply in exactly the same way.	The resulting
         string is	written	out to the buffer pointed to by	the iterator
         s.	 See the Table 1 below for a description of strftime
         formatting	characters.

         The fill argument is used for any padding.

         Returns an	iterator pointing one past the last character written.

      iter_type
      put(iter_type	s, ios_base& f,	char_type fill,
         const tm* tmb, char format, char modifier = 0) const;

         Calls the protected virtual do_put	function.

    PROTECTED MEMBER FUNCTIONS

      virtual iter_type
      do_put(iter_type s, ios_base&,
    	char_type fill,	const tm* t,
    	char format, char modifier) const;

         Writes out	a character string representation of the Date/Time
         contained in	t.  The	string is formatted according the the
         specifier	format and modifier modifier.	 These values are
         interpreted in exactly the same way that the strftime function
         intrprets its format and modifier flags.  See the Table 1 below
         for a description of strftime formatting	characters.

         The fill argument is used for any padding.

         Returns an	iterator pointing one past the last character written.

         Table 1. Formatting characters used by strftime().

         For those formats that do not use all members of the struct tm,
         only those members that	are actually used are noted [in
         brackets].

         Format
         character	Meaning			       Example

         a		Abbreviated weekday name
    		[from tm::tm_wday]	       Sun
         A		Full weekday name
    		[from tm::tm_wday]	       Sunday
         b		Abbreviated month name	       Feb
         B		Full month name		       February
         c		Date and time
    		[may use all members]	       Feb 29 14:34:56 1984
         d		Day of the month	       29
         H		Hour of	the 24-hour day	       14
         I		Hour of	the 12-hour day	       02
         j		Day of the year,
    		from 001 [from tm::tm_yday]    60
         m		Month of the year, from	01     02
         M		Minutes	after the hour	       34
         p		AM/PM indicator, if any	       AM
         S		Seconds	after the minute       56
         U		Sunday week of the year,
    		from 00	[from tm::tm_yday
    		and tm::tm_wday]
         w		Day of the week,
    		with 0 for Sunday	       0
         W		Monday week of the year,
    		from 00	[from tm::tm_yday
    		and tm::tm_wday]
         x		Date [uses tm::tm_yday
    		in some	locales]	       Feb 29 1984
         X		Time			       14:34:56
         y		Year of	the century,
    		from 00	(deprecated)	       84
         Y		Year			       1984
         Z		Time zone name
    		[from tm::tm_isdst]	       PST or PDT

    EXAMPLE

      //
      // timeput.cpp
      //
      #include <iostream>

      int main ()
      {
       using namespace std;

       typedef ostreambuf_iterator<char,char_traits<char> >	iter_type;

       locale loc;
       time_t tm = time(NULL);
       struct tm* tmb = localtime(&tm);
       struct tm timeb;
       memcpy(&timeb,tmb,sizeof(struct tm));
       char	pat[] =	"%c";

        // Get a time_put facet
       const time_put<char,iter_type>& tp =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
       use_facet<time_put<char,iter_type> >(loc);
      #else
       use_facet(loc,(time_put<char,iter_type>*)0);
      #endif

        // Construct a ostreambuf_iterator on cout
       iter_type begin(cout);

       cout	<< " --> ";
       tp.put(begin,cout,' ',&timeb,pat,pat+2);

       cout	<< endl	<< " --> ";
       tp.put(begin,cout,' ',&timeb,'c',' ');

       cout	<<  endl;

       return 0;
      }

    SEE ALSO

      locale, facets, time_get

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    time_put_byname
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      time_put_byname - A facet that provides formatted time output
      facilities based	on the named locales.

    SYNOPSIS

      #include <locale>
      template <class charT, class OuputIterator =
    	   ostreambuf_iterator<charT> >
      class	time_put_byname;

    DESCRIPTION

      The time_put_byname  template	provides the same functionality	as the
      time_put  template, but specific to a	particular named locale.  For
      a description of the member functions of time_put_byname, see the
      reference for time_put.	 Only the constructor is described
      here.

    INTERFACE

      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_base&,
    			    char_type, const tm* t,
    			    char format, char modifier)	const;
      };

    CONSTRUCTOR

      explicit time_put_byname(const char* name, size_t refs = 0);

      Construct a time_put_byname facet.	 The facet will	provide	time
      formatting facilities relative to the named locale specified by
      the name argument. If the refs argument is 0 then destruction of the
      object	is delegated to the locale, or locales, containing it.
      This allows the user to	ignore lifetime	management issues.  On
      the other had, if refs  is 1 then the object must be explicitly
      deleted; the locale will not do	so. In	this case, the object
      can be maintained	across the lifetime of multiple locales.

    SEE ALSO

      locale, facets, time_put, time_get_byname

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    tolower
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      tolower - Converts a character to lower case.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The tolower returns the the parameter	c converted to lower case.
      The conversion is	made using the ctype facet from	the locale
      parameter.

    EXAMPLE

      //
      // toupper.cpp
      //
      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

       cout	<< 'a' << toupper('c') << tolower('F') << endl;

       return 0;
      }

    SEE ALSO

      toupper, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    toupper
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      toupper - Converts a character to upper case.

    SYNOPSIS

      #include <locale>

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

    DESCRIPTION

      The toupper returns the the parameter	c converted to upper case.
      The conversion is	made using the ctype facet from	the locale
      parameter.

    EXAMPLE

      //
      // toupper.cpp
      //
      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

       cout	<< 'a' << toupper('c') << tolower('F') << endl;

       return 0;
      }

    SEE ALSO

      tolower, locale, ctype

    STANDARDS CONFORMANCE
      ANSI X3J16/ISO WG21 Joint C++	Committee

    use_facet
    			   Standard C++	Library
    		 Copyright 1996, Rogue Wave Software, Inc.

    NAME

      use_facet - Template function	used to	obtain a facet.

    SYNOPSIS

      #include <locale>
      template <class Facet> const Facet& use_facet(const locale&);

    DESCRIPTION

      use_facet returns a reference	to the corresponding facet contained
      in	the locale argument.  You	specify	the facet type be
      explicitly providing the template parameter (See the example below).
      If that facet is	not present then use_facet throws
      bad_cast.  Otherwise, the reference will remain	valid for as
      long as any copy of   the locale exists.

      Note that if your compiler cannot overload function templates	on
      return type then you'll need	to use an alternate use_facet
      template.	 The alternate template	takes an additional
      argument that's a pointer to the type of facet	you want to
      extract from the locale.  The declaration looks like this:

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

      The example below shows the use of both variations of	use_facet.

    EXAMPLE

      //
      // usefacet.cpp
      //
      #include <iostream>

      int main ()
      {
       using namespace std;

       locale loc;

        // Get a ctype facet
       const ctype<char>& ct =
      #ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
          use_facet<ctype<char> >(loc);
      #else
          use_facet(loc,(ctype<char>*)0);
      #endif

       cout	<< 'a' << ct.toupper('c') << endl;

       return 0;
      }

    SEE ALSO

      locale, facets, has_facet

|  | privacy statement and legal notices