DIGITAL logo   C++ Graphic
    Updated: 21 November 1998
  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 parameter 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

   
Burgundy bar
DIGITAL Home Feedback Search Sitemap Subscribe Help
Legal