locale
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
locale - Localization class containing a polymorphic set of facets.
SYNOPSIS
#include<locale>
class locale;
DESCRIPTION
locale provides a localization interface and a set of indexed
facets, each of which covers one particular localization
issue. The default locale object is constructed on the "C"
locale. Locales can also be constructed on named locales.
A calling program can determine whether a particular facet is
contained in a locale by using the has_facet function, and the
program can obtain a reference to that facet with the use_facet
function. These are not member functions, but instead take a
locale object as an argument.
locale has several important characteristics.
First, successive calls to member functions will always return the
same result. This allows a calling program to safely cache the
results of a call.
Any standard facet not implemented by a locale will be obtained from
the global locale the first time that use_facet is called (for
that facet).
Only a locale constructed from a name (i.e., "POSIX"), from parts of
two named locales, or from a stream, has a name. All other
locales are unnamed. Only named locales may be compared for
equality. An unnamed locale is equal only to itself.
INTERFACE
class locale {
public:
// types:
class facet;
class id;
typedef int category;
static const category none, collate, ctype, monetary,
numeric, time, messages,
all = collate | ctype | monetary |
numeric | time | messages;
// construct/copy/destroy:
locale() throw()
locale(const locale&) throw()
explicit locale(const char*);
locale(const locale&, const char*, category);
template <class Facet> locale(const locale&, Facet*);
template <class Facet> locale(const locale&,
const locale&);
locale(const locale&, const locale&, category);
~locale() throw(); // non-virtual
const locale& operator=(const locale&) throw();
// locale operations:
basic_string<char> name() const;
bool operator==(const locale&) const;
bool operator!=(const locale&) const;
template <class charT,Traits>
bool operator()(const basic_string<charT,Traits>&,
const basic_string<charT,Traits>&) const;
// global locale objects:
static locale global(const locale&);
static const locale& classic();
};
class locale::facet {
protected:
explicit facet(size_t refs = 0);
virtual ~facet();
private:
facet(const facet&); // not defined
void operator=(const facet&); // not defined
};
class locale::id {
public:
id();
private:
void operator=(const id&); // not defined
id(const id&); // not defined
};
TYPES
category
Standard facets fall into eight broad categories. These are:
none, collate, ctype, monetary, numeric, time, messages, and
all. all is a combination of all the other categories except
none. Bitwise operations may be applied to combine or screen
these categries. For instance all is defined as:
(collate | ctype | monetary | numeric | time | messages)
locale member functions that take a category argument must be
provided with one of the above values, or one of the constants
from the old C locale (e.g., LC_CTYPE).
facet
Base class for facets. This class exists primarily to provide
reference counting services to derived classes. All facets
must derive from it, either directly or indirectly indirectly
(e.g., facet -> ctype<char> -> my_ctype).
If the refs argument to the constructor is 0 then destruction of
the object is delegated to the locale, or locales, containing
it. This allows the user to ignore lifetime management
issues. On the other had, if refs is 1, then the object
must be explicitly deleted; the locale will not do so. In
this case, the object can be maintained across the lifetime
of multiple locales.
Copy construction and assignment of this class are disallowed.
id
Type used to index facets in the locale container. Every facet
must contain a member of this type.
Copy construction and assignment of this type are disallowed.
CONSTRUCTORS AND DESTRUCTORS
locale()
throw()
Constructs a default locale object. This locale will be the same
as the last argument passed to locale::global(), or, if that
function has not been called, the locale will be the same
as the classic "C" locale.
locale(const locale& other)
throw()
Constructs a copy of the locale argument other.
explicit locale(const char* std_name);
Constructs a locale object on the named locale indicated by
std_name. Throws a runtime_error exception of if std_name is
not a valid locale name.
locale(const locale& other, const char* std_name,
category cat);
Construct a locale object that is a copy of other, except for the
facets that are in the category specified by cat. These facets
will be obtained from the named locale identified by std_name.
Throws a runtime_error exception of if std_name is not a
valid locale name.
Note that the resulting locale will have the same name (possibly
none) as other.
template <class Facet>
locale(const locale& other, Facet* f);
Constructs a locale object that is a copy of other, except for
the facet of type Facet. Unless f is null, it f is
used to supply the missing facet, otherwise the facet will
come from other as well.
Note that the resulting locale will not have a name.
template <class Facet>
locale(const locale& other, const locale& one);
Constructs a locale object that is a copy of other, except for
the facet of type Facet. This missing facet is
obtained from the second locale argument, one. Throws a
runtime_error exception if one does not contain a facet of type
Facet.
Note that the resulting locale will not have a name.
locale(const locale& other, const locale& one, category cat);
Constructs a locale object that is a copy of other, except for
facets that are in the category specified by category argument
cat. These missing facets are obtained from the other locale
argument, one.
Note that the resulting locale will only have a name only if both
other and one have names. The name will be the same as other's
name.
~locale();
Destroy the locale.
PUBLIC MEMBER OPERATORS
const locale&
operator=(const locale& other) throw();
Replaces *this with a copy of other. Returns *this.
bool
operator==(const locale& other) const;
Retuns true if both other and *this are the same object, if one
is a copy of another, or if both have the same name. Otherwise
returns false.
bool
operator!=(const locale& other) const;
Returns !(*this == other)
template <class charT,Traits>
bool
operator()(const basic_string<charT,Traits>& s1,
const basic_string<charT,Traits>& s2) const;
This operator is provided to allow a locale object to be used as
a comparison object for comparing two strings. Returns the
result of comparing the two strings using the compare member
function of the collate<charT> facet contained in this.
Specifically, this function returns the following:
use_facet< collate<charT> >(*this).compare(s1.data(),
s1.data()+s1.size(), s2.data(),
s2.data()+s2.size()) < 0;
This allows a locale to be used with standard algorithms, such as
sort, to provide localized comparison of strings.
PUBLIC MEMBER FUNCTIONS
basic_string<char> name() const; Returns the name of this, if this
has one; otherwise returns the string "*".
STATIC PUBLIC MEMBER FUNCTIONS
static locale
global(const locale& loc);
Sets the global locale to loc. This causes future uses of the
default constructor for locale to return a copy of loc. If loc
has a name, this function has the further effect of
calling std::setlocale(LC_ALL,loc.name().c_str());. Returns the
previous value of locale().
static const locale&
classic();
Returns a locale with the same semantics as the classic "C" locale.
EXAMPLE
//
// locale.cpp
//
#include <string>
#include <vector>
#include <iostream>
#include "codecvte.h"
int main ()
{
using namespace std;
locale loc; // Default locale
// Construct new locale using default locale plus
// user defined codecvt facet
// This facet converts from ISO Latin
// Alphabet No. 1 (ISO 8859-1) to
// U.S. ASCII code page 437
// This facet replaces the default for
// codecvt<char,char,mbstate_t>
locale my_loc(loc,new ex_codecvt);
// imbue modified locale onto cout
locale old = cout.imbue(my_loc);
cout << "A jolly time was had by all" << endl;
cout.imbue(old);
cout << "A jolly time was had by all" << endl;
// Create a vector of strings
vector<string,allocator<void> > v;
v.insert(v.begin(),"antelope");
v.insert(v.begin(),"bison");
v.insert(v.begin(),"elk");
copy(v.begin(),v.end(),
ostream_iterator<string,char,
char_traits<char> >(cout," "));
cout << endl;
// Sort the strings using the locale as a comparitor
sort(v.begin(),v.end(),loc);
copy(v.begin(),v.end(),
ostream_iterator<string,char,
char_traits<char> >(cout," "));
cout << endl;
return 0;
}
SEE ALSO
facets, has_facet, use_facet, specific facet reference sections
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
codecvt_byname
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
codecvt_byname - A facet that provides code set converion
classification facilities based on the named locales.
SYNOPSIS
#include <locale>
template <class charT> class codecvt_byname;
DESCRIPTION
The codecvt_byname template provides the same functionality as the
codecvt template, but specific to a particular named locale. For a
description of the member functions of codecvt_byname, see the
reference for codecvt. Only the constructor is described here.
INTERFACE
template <class fromT, class toT, class stateT>
class codecvt_byname : public codecvt<fromT, toT, stateT> {
public:
explicit codecvt_byname(const char*, size_t refs = 0);
protected:
~codecvt_byname(); // virtual
virtual result do_out(stateT&,
const internT*,
const internT*,
const internT*&,
externT*, externT*,
externT*&) const;
virtual result do_in(stateT&,
const externT*,
const externT*,
const externT*&,
internT*, internT*,
internT*&) const;
virtual bool do_always_noconv() const throw();
virtual int do_length(const stateT&, const internT*,
const internT*,
virtual int do_max_length() const throw();
virtual int do_encoding() const throw();
};
CONSTRUCTOR
explicit codecvt_byname(const char* name, size_t refs = 0);
Construct a codecvt_byname facet. The facet will provide codeset
conversion relative to the named locale specified by the name
argument. If the refs argument is 0, destruction of the
object is delegated to the locale, or locales, containing
it. This allows the user to ignore life-time management
issues. On the other had, if refs is 1, the object must be
explicitly deleted: the locale will not do so. In this case,
the object can be maintained across the lifetime of multiple
locales.
SEE ALSO
locale, facets, codecvt
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
code_cvt
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
code_cvt - Code conversion facet.
SYNOPSIS
#include <locale>
class codecvt_base;
template <class internT, class externT, class stateT>
class codecvt;
DESCRIPTION
The codecvt<internT,externT,stateT> template provides code
conversion facilities. Default implementations of
codecvt<char,wchar_t,mbstate_t> and codecvt<wchar_t,char,mbstate_t>
use ctype<wchar_t>::widen and ctype<wchar_t>::narrow respectively.
The default implementation of codecvt<wchar_t,wchar_t,mbstate_t>
simply uses memcpy (no particular conversion applied).
INTERFACE
class codecvt_base {
public:
enum result { ok, partial, error, noconv };
};
template <class internT, class externT, class stateT>
class codecvt : public locale::facet, public codecvt_base {
public:
typedef internT intern_type;
typedef externT extern_type;
typedef stateT state_type;
explicit codecvt(size_t = 0)
result out(stateT&, const internT*,
const internT*, const internT*&,
externT*, externT*, externT*&) const;
result in(stateT&, const externT*,
const externT*, const externT*&,
internT*, internT*, internT*&) const;
bool always_noconv() const throw();
int length(const stateT&, const internT*, const internT*,
size_t) const;
int max_length() const throw();
int encoding() const throw();
static locale::id id;
protected:
~codecvt(); // virtual
virtual result do_out(stateT&,
const internT*,
const internT*,
const internT*&,
externT*, externT*,
externT*&) const;
virtual result do_in(stateT&,
const externT*,
const externT*,
const externT*&,
internT*, internT*,
internT*&) const;
virtual bool do_always_noconv() const throw();
virtual int do_length(const stateT&, const internT*,
const internT*,
size_t) const;
virtual int do_max_length() const throw();
virtual int do_encoding() const throw();
};
TYPES
intern_type
Type of character to convert from.
extern_type
Type of character to convert to.
state_type
Type to keep track of state and determine the direction of the
conversion.
CONSTRUCTORS AND DESTRUCTORS
explicit codecvt(size_t refs = 0)
Construct a codecvt facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
~codecvt(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the codecvt facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public length function simply calls its protected cousin
do_length.
bool
always_noconv() const
throw();
int
encoding() const
throw();
result
in(stateT& state, const externT* from,
const externT* from_end, const externT*& from_next,
internT* to, internT* to_limit, internT*& to_next) const;
int
length(const stateT&, const internT* from,
const internT* end,
size_t max) const;
int
max_length() const
throw();
result
out(stateT& state, const internT* from,
const internT* from_end, const internT*& from_next,
externT* to, externT* to_limit, externT*& to_next) const;
Each of these public member functions xxx simply calls the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual bool
do_always_noconv() const
throw();
Returns true if no conversion is required. This is the case if
do_in and do_out return noconv for all valid arguments. The
instantiation codecvt<char,char,mbstate_t> returns true, while
all other default instantiations return false.
virtual int
do_encoding() const
throw();
Returns one of the following
+ -1 if the encoding on the external character sequence is
dependent on state.
+ A constant number representing the number of external
characters in a fixed width encoding.
+ 0 if the encoding is uses a variable width.
virtual result
do_in(stateT& state,
const externT* from,
const externT* from_end,
const externT*& from_next,
internT* to, internT* to_limit,
internT*& to_next) const;
virtual result
do_out(stateT& state,
const internT* from,
const internT* from_end,
const internT*& from_next,
externT* to, externT* to_limit,
externT*& to_next) const;
Both functions take characters in the range of [from,from_end),
apply an appropriate conversion, and place the resulting
characters in the buffer starting at to. Each function converts
at most from_end-from internT characters, and stores no more than
to_limit-to externT characters. Both do_out and do_in will stop
if they find a character they cannot convert. In any case,
from_next and to_next are always left pointing to the next
character beyond the last one successfully converted.
do_out and do_in must be called under the following pre-conditions:
+ from <= from_end
+ to <= to_end
+ state either initialized for the beginning of a sequence or
equal to the result of the previous conversion on the sequence.
In the case where no conversion is required, from_next will be
set to from and to_next set to to.
do_out and do_in return one the following:
Return Value Meaning
ok completed the conversion
partial not all source characters converted
error encountered a from_type character it
could not convert
noconv no conversion was needed
If either function returns partial and (from == from_end) then one
of two conditions prevail:
+ The destination sequence has not accepted all the converted
characters, or
+ Additional internT characters are needed before another
externT character can be assembled.
virtual int
do_length(const stateT&, const internT* from,
const internT* end,
size_t max) const;
Returns the largest number < max of internT characters available
in the range [from,end).
do_length must be called under the following pre-conditions:
+ from <= from_end
+ state either initialized for the beginning of a sequence or
equal to the result of the previous conversion on the sequence.
virtual int
do_max_length() const throw();
Returns the maximum value that do_length can return for any
valid set of arguments.
virtual result
do_out(stateT& state,
const internT* from,
const internT* from_end,
const internT*& from_next,
externT* to, externT* to_limit,
externT*& to_next) const;
See do_in above.
EXAMPLE
//
// codecvt.cpp
//
#include <sstream>
#include "codecvte.h"
int main ()
{
using namespace std;
mbstate_t state;
// A string of ISO characters and buffers to hold
// conversions
string ins(" );
string ins2(ins.size(),'.');
string outs(ins.size(),'.');
// Print initial contents of buffers
cout << "Before:0 << ins << endl;
cout << ins2 << endl;
cout << outs << endl << endl;
// Initialize buffers
string::iterator in_it = ins.begin();
string::iterator out_it = outs.begin();
// Create a user defined codecvt fact
// This facet converst from ISO Latin
// Alphabet No. 1 (ISO 8859-1) to
// U.S. ASCII code page 437
// This facet replaces the default for
// codecvt<char,char,mbstate_t>
locale loc(locale(),new ex_codecvt);
// Now get the facet from the locale
const codecvt<char,char,mbstate_t>& cdcvt =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<codecvt<char,char,mbstate_t> >(loc);
#else
use_facet(loc,(codecvt<char,char,mbstate_t>*)0);
#endif
// convert the buffer
cdcvt.in(state,ins.begin(),ins.end(),in_it,
outs.begin(),outs.end(),out_it);
cout << "After in:0 << ins << endl;
cout << ins2 << endl;
cout << outs << endl << endl;
// Lastly, convert back to the original codeset
in_it = ins.begin();
out_it = outs.begin();
cdcvt.out(state, outs.begin(),outs.end(),out_it,
ins2.begin(),ins2.end(),in_it);
cout << "After out:0 << ins << endl;
cout << ins2 << endl;
cout << outs << endl;
return 0;
}
SEE ALSO
locale, facets, codecvt_byname
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
collate
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
collate, collate_byname - String collation, comparison, and hashing
facet.
SYNOPSIS
#include <locale>
template <class charT> class collate;
template <class charT> class collate_byname;
DESCRIPTION
The collate and collate_byname facets provides string collation,
comparison, and hashing facilities. collate provides these
facilities for the "C" locale, while collate_byname provides the
same thing for named locales.
INTERFACE
template <class charT>
class collate : public locale::facet {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit collate(size_t refs = 0);
int compare(const charT*, const charT*,
const charT*, const charT*) const;
string_type transform(const charT*, const charT*) const;
long hash(const charT*, const charT*) const;
static locale::id id;
protected:
~collate(); // virtual
virtual int do_compare(const charT*, const charT*,
const charT*, const charT*) const;
virtual string_type do_transform(const charT*, const charT*) const;
virtual long do_hash (const charT*, const charT*) const;
};
template <class charT>
class collate_byname : public collate<charT> {
public:
explicit collate_byname(const char*, size_t = 0);
protected:
~collate_byname(); // virtual
virtual int do_compare(const charT*, const charT*,
const charT*, const charT*) const;
virtual string_type do_transform(const charT*, const charT*) const;
virtual long do_hash(const charT*, const charT*) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit collate(size_t refs = 0)
Construct a collate facet. If the refs argument is 0,
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore
lifetime management issues. On the other had, if refs
is 1, the object must be explicitly deleted: the locale will
not do so. In this case, the object can be maintained across the
life-time of multiple locales.
explicit collate_byname(const char* name, size_t refs = 0);
Construct a collate_byname facet. Use the named locale specified
by the name argument. The refs argument serves the same purpose
as it does for the collate constructor.
~collate(); // virtual and protected
~collate_byname(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the collate facet provide an interface
to protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version
of the public grouping function simply calls its protected cousin
do_grouping.
int
compare(const charT* low1, const charT* high1,
const charT* low2, const charT* high2) const;
long
hash(const charT* low, const charT* high) const;
string_type
transform(const charT* low, const charT* high) const;
Each of these public member functions xxx simply call the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual int
do_compare(const charT* low1, const charT* high1,
const charT* low2, const charT* high2) const;
Returns 1 if the character string represented by the range
[low1,high1) is greater than the character string represented
by the range [low2,high2), -1 if first string is less than the
second, or 0 if the two are equal. collate uses a
lexicographical comparison.
virtual long
do_hash( const charT* low, const charT* high)
Generate a has value from a string defined by the range of
characters [low,high). Given two strings that compare equal
(i.e. do_compare returns 0), do_hash returns an integer value
that is the same for both strings. For differing strings the
probability that the return value will be equal is approximately
1.0/numeric_limits<unsigned long>::max().
virtual string_type
do_transform(const charT* low, const charT* high) const;
Returns a string that will yield the same result in a
lexicographical comparison with another string returned from
transform as does the do_compare function applied to the
original strings. In other words, the result of applying a
lexicographical comparison to two strings returned from transform
will be the same as applying do_compare to the original strings
passed to transform.
EXAMPLE
//
// collate.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
string s1("blue");
string s2("blues");
// Get a reference to the collate<char> facet
const collate<char>& co =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<collate<char> >(loc);
#else
use_facet(loc,(collate<char>*)0);
#endif
// Compare two strings
cout << co.compare(s1.begin(),s1.end(),
s2.begin(),s2.end()-1) << endl;
cout << co.compare(s1.begin(),s1.end(),
s2.begin(),s2.end()) << endl;
// Retrieve hash values for two strings
cout << co.hash(s1.begin(),s1.end()) << endl;
cout << co.hash(s2.begin(),s2.end()) << endl;
return 0;
}
SEE ALSO
locale, facets, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
collate_byname
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
collate, collate_byname - String collation, comparison, and hashing
facet.
SYNOPSIS
#include <locale>
template <class charT> class collate;
template <class charT> class collate_byname;
DESCRIPTION
The collate and collate_byname facets provides string collation,
comparison, and hashing facilities. collate provides these
facilities for the "C" locale, while collate_byname provides the
same thing for named locales.
INTERFACE
template <class charT>
class collate : public locale::facet {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit collate(size_t refs = 0);
int compare(const charT*, const charT*,
const charT*, const charT*) const;
string_type transform(const charT*, const charT*) const;
long hash(const charT*, const charT*) const;
static locale::id id;
protected:
~collate(); // virtual
virtual int do_compare(const charT*, const charT*,
const charT*, const charT*) const;
virtual string_type do_transform(const charT*, const charT*) const;
virtual long do_hash (const charT*, const charT*) const;
};
template <class charT>
class collate_byname : public collate<charT> {
public:
explicit collate_byname(const char*, size_t = 0);
protected:
~collate_byname(); // virtual
virtual int do_compare(const charT*, const charT*,
const charT*, const charT*) const;
virtual string_type do_transform(const charT*, const charT*) const;
virtual long do_hash(const charT*, const charT*) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit collate(size_t refs = 0)
Construct a collate facet. If the refs argument is 0,
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore
lifetime management issues. On the other had, if refs
is 1, the object must be explicitly deleted: the locale will
not do so. In this case, the object can be maintained across the
lifetime of multiple locales.
explicit collate_byname(const char* name, size_t refs = 0);
Construct a collate_byname facet. Use the named locale specified
by the name argument. The refs argument serves the same purpose
as it does for the collate constructor.
~collate(); // virtual and protected
~collate_byname(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the collate facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public grouping function simply calls its protected cousin
do_grouping.
int
compare(const charT* low1, const charT* high1,
const charT* low2, const charT* high2) const;
long
hash(const charT* low, const charT* high) const;
string_type
transform(const charT* low, const charT* high) const;
Each of these public member functions xxx simply call the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual int
do_compare(const charT* low1, const charT* high1,
const charT* low2, const charT* high2) const;
Returns 1 if the character string represented by the range
[low1,high1) is greater than the character string represented
by the range [low2,high2), -1 if first string is less than the
second, or 0 if the two are equal. collate uses a
lexicographical comparison.
virtual long
do_hash( const charT* low, const charT* high)
Generate a has value from a string defined by the range of
characters [low,high). Given two strings that compare equal
(i.e. do_compare returns 0), do_hash returns an integer value
that is the same for both strings. For differing strings the
probability that the return value will be equal is approximately
1.0/numeric_limits<unsigned long>::max().
virtual string_type
do_transform(const charT* low, const charT* high) const;
Returns a string that will yield the same result in a
lexicographical comparison with another string returned from
transform as does the do_compare function applied to the
original strings. In other words, the result of applying a
lexicographical comparison to two strings returned from transform
will be the same as applying do_compare to the original strings
passed to transform.
EXAMPLE
//
// collate.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
string s1("blue");
string s2("blues");
// Get a reference to the collate<char> facet
const collate<char>& co =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<collate<char> >(loc);
#else
use_facet(loc,(collate<char>*)0);
#endif
// Compare two strings
cout << co.compare(s1.begin(),s1.end(),
s2.begin(),s2.end()-1) << endl;
cout << co.compare(s1.begin(),s1.end(),
s2.begin(),s2.end()) << endl;
// Retrieve hash values for two strings
cout << co.hash(s1.begin(),s1.end()) << endl;
cout << co.hash(s2.begin(),s2.end()) << endl;
return 0;
}
SEE ALSO
locale, facets, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
facets
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
facets - Family of classes used to encapsulate categories of locale
functionality.
DESCRIPTION
The Standard C++ Localization library provides a locale interface
that contains a collection of diverse facets. Each facet
provides localization facilities for some specific area, such as
character classification or numeric formatting. Each facet also
falls into one or more broad categories. These categories are
defined in the locale class, and the standard facets fit into these
categories as follows.
Category Facets
collate collate, collate_byname
ctype ctype, codecvt, ctype_byname, codecvt_byname
monetary moneypunct, moneypunct_byname, money_put,
money_get
numeric numpunct, numpunct_byname, num_put, num_get
time time_put, time_put_byname, time_get,
time_get_byname
messages messages, messages_byname
A facet must satisfy two properties. First, it must be derived from
the base class locale::facet, either directly or indirectly (for
example, facet -> ctype<char> -> my_ctype). Second, it
must contain a member of type locale::id. This ensures that the
locale class can manage its collection of facets properly.
SEE ALSO
locale, specific facet reference sections
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
has_facet
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
has_facet - A function template used to determine if a locale has a
given facet.
SYNOPSIS
#include <locale>
template <class Facet> bool has_facet(const locale&) throw();
DESCRIPTION
has_facet returns true if the requested facet is available in the
locale, otherwise it returns false. You specify the facet type by
explicitly providing the template parameter. (See the example
below.)
Note that if your compiler cannot overload function templates
on return type then you'll need to use an alternative
has_facet template. The alternative template takes an
additional argument that's a pointer to the type of facet
you want to check on. The declaration looks like this:
template <class Facet>
const bool has_facet(const locale&, Facet*) throw();
The example below shows the use of both variations of has_facet.
EXAMPLE
//
// hasfacet.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
cout << has_facet<ctype<char> >(loc) << endl;
#else
cout << has_facet(loc,(ctype<char>*)0) << endl;
#endif
return 0;
}
SEE ALSO
locale, facets, use_facet
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isalnum
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isalnum - Determines if a character is alphabetic or numeric.
SYNOPSIS
#include <locale>
template <class charT>
bool isalnum (charT c, const locale& loc) const;
DESCRIPTION
The isalnum function returns true if the character passed as a
parameter is either part of the alphabet specified by the locale
parameter or a decimal digit, otherwise the function
returns false. The check is made using the ctype facet
from the locale parameter.
EXAMPLE
//
// isalnum.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
cout << isalnum('a',loc) << endl;
cout << isalnum(',',loc) << endl;
return 0;
}
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isalpha
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isalpha - Determines if a character is alphabetic.
SYNOPSIS
#include <locale>
template <class charT>
bool isslpha (charT c, const locale& loc) const;
DESCRIPTION
The isslpha function returns true if the character passed as a
parameter is part of the alphabet specified by the locale
parameter, otherwise the function returns false. The
check is made using the ctype facet from the locale parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
iscntrl
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
iscntrl - Determines if a character is a control character.
SYNOPSIS
#include <locale>
template <class charT>
bool iscntrl (charT c, const locale& loc) const;
DESCRIPTION
The iscntrl function returns true if the character passed as a
parameter is a control character, otherwise the function returns
false. The check is made using the ctype facet from the
locale parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isdigit
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isdigit - Determines if a character is a decimal digit.
SYNOPSIS
#include <locale>
template <class charT>
bool isdigit (charT c, const locale& loc) const;
DESCRIPTION
The isdigit function returns true if the character passed as a
parameter is a decimal digit, otherwise the function returns false.
The check is made using the ctype facet from the locale
parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isgraph
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isgraph - Determines if a character is a graphic character.
SYNOPSIS
#include <locale>
template <class charT>
bool isgraph (charT c, const locale& loc) const;
DESCRIPTION
The isgraph function returns true if the character passed as a
parameter is a graphic character, otherwise the function returns
false. The check is made using the ctype facet from the locale
parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
islower
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
islower - Determines whether a character is lower case.
SYNOPSIS
#include <locale>
template <class charT>
bool islower (charT c, const locale& loc) const;
DESCRIPTION
The islower function returns true if the character passed as a
parameter is lower case, otherwise the function returns false.
The check is made using the ctype facet from the locale parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isprint
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isprint - Determines if a character is printable.
SYNOPSIS
#include <locale>
template <class charT>
bool isprint (charT c, const locale& loc) const;
DESCRIPTION
The isprint function returns true if the character passed as a
parameter is printable, otherwise the function returns false. The
check is made using the ctype facet from the locale parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ispunct
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
ispunct - Determines if a character is punctuation.
SYNOPSIS
#include <locale>
template <class charT>
bool ispunct (charT c, const locale& loc) const;
DESCRIPTION
The ispunct function returns true if the character passed as a
parameter is punctuation, otherwise the function returns false. The
check is made using the ctype facet from the locale parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isspace
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isspace - Determines if a character is a space.
SYNOPSIS
#include <locale>
template <class charT>
bool isspace (charT c, const locale& loc) const;
DESCRIPTION
The isspace function returns true if the character passed as a
parameter is a space character, otherwise the function returns
false. The check is made using the ctype facet from the locale
parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isupper
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isupper - Determines whether a character is upper case.
SYNOPSIS
#include <locale>
template <class charT>
bool isupper (charT c, const locale& loc) const;
DESCRIPTION
The isupper function returns true if the character passed as a
parameter is upper case, otherwise the function returns false.
The check is made using the ctype facet from the locale
parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
isxdigit
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
isxdigit - Determines whether a character is a hexidecimal digit.
SYNOPSIS
#include <locale>
template <class charT>
bool isxdigit (charT c, const locale& loc) const;
DESCRIPTION
The isxdigit function returns true if the character passed as a
parameter is a hexidecimal digit, otherwise the function
returns false. The check is made using the ctype
facet from the locale parameter.
SEE ALSO
other is_ functions, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
messages
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
messages, messages_byname - Messaging facets.
SYNOPSIS
#include<locale>
class messages_base;
template <class charT> class messages;
DESCRIPTION
messages provides access to a localized messaging facility. The
messages facet provides facilities based on the "C" locale,
while the messages_byname facet provides the same facilities
for named locales.
The messages_base class provides a catalog type for use by the
derived messages and messages_byname classes.
Note that the default messages facet uses catopen, catclose, etc.,
to implement the message database. If your platform does not
support these then you'll need to imbue your own messages facet by
implementing whatever database is available.
INTERFACE
class messages_base {
public:
typedef int catalog;
};
template <class charT>
class messages : public locale::facet, public messages_base {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit messages(size_t = 0);
catalog open(const basic_string<char>&, const locale&) const;
string_type get(catalog, int, int,
const string_type&) const;
void close(catalog) const;
static locale::id id;
protected:
~messages(); // virtual
virtual catalog do_open(const basic_string<char>&,
const locale&) const;
virtual string_type do_get(catalog, int, int,
const string_type&) const;
virtual void do_close(catalog) const;
};
class messages_byname : public messages<charT> {
public:
explicit messages_byname(const char*, size_t = 0);
protected:
~messages_byname(); // virtual
virtual catalog do_open(const basic_string<char>&,
const locale&) const;
virtual string_type do_get(catalog, int, int,
const string_type&) const;
virtual void do_close(catalog) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit messages(size_t refs = 0)
Construct a messages facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other hand, if refs is 1 then
the object must be explicitly deleted: the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
explicit messages_byname(const char* name, size_t refs = 0);
Construct a messages_byname facet. Use the named locale
specified by the name argument. The refs argument serves the
same purpose as it does for the messages constructor.
~messages(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the messages facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public open function simply calls its protected cousin do_open.
void
close(catalog c) const;
string_type
get(catalog c, int set, int msgid,
const string_type& dfault) const;
catalog
open(const basic_string<char>& fn, const locale&) const;
Each of these public member functions xxx simply call the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual void
do_close(catalog cat) const;
Closes the catalog. The cat argument must have been obtained by
a call to open().
virtual string_type
do_get(catalog cat, int set, int msgid,
const string_type& dfault) const;
Retrieves a specific message. Returns the message identified by
cat, set, msgid, and dfault. cat must have been obtained by a
previous call to open() and this function must not be called
with a cat that has had close() called on yet after the
last call to open(). In other words, the catalog must have been
opened and not yet closed.
virtual catalog
do_open(const basic_string<char>& name, const locale&) const;
Opens a message catalog. Returns a catalog identifier that can
be passed to the get() function in order to access specific
messages. Returns -1 if the catalog name specificed in the
name argument is invalid. The loc argument will be used
for codeset conversion if necessary.
EXAMPLE
//
// messages.cpp
//
#include <string>
#include <iostream>
int main ()
{
using namespace std;
locale loc;
// Get a reference to the messages<char> facet
const messages<char>& mess =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<messages<char> >(loc);
#else
use_facet(loc,(messages<char>*)0);
#endif
// Open a catalog and try to grab
// both some valid messages, and an invalid message
string def("Message Not Found");
messages<char>::catalog cat =
mess.open("./rwstdmessages.cat",loc);
if (cat != -1)
{
string msg0 = mess.get(cat,1,1,def);
string msg1 = mess.get(cat,1,2,def);
string msg2 = mess.get(cat,1,6,def); // invalid msg #
string msg3 = mess.get(cat,2,1,def);
mess.close(cat);
cout << msg0 << endl << msg1 << endl
<< msg2 << endl << msg3 << endl;
}
else
cout << "Unable to open message catalog" << endl;
return 0;
}
SEE ALSO
locale, facets
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
messages_byname
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
messages, messages_byname - Messaging facets.
SYNOPSIS
#include<locale>
class messages_base;
template <class charT> class messages;
DESCRIPTION
messages provides access to a localized messaging facility. The
messages facet provides facilities based on the "C" locale,
while the messages_byname facet provides the same facilities
for named locales.
The messages_base class provides a catalog type for use by the
derived messages and messages_byname classes.
Note that the default messages facet uses catopen, catclose, etc.,
to implement the message database. If your platform does not
support these then you'll need to imbue your own messages facet by
implementing whatever database is available.
INTERFACE
class messages_base {
public:
typedef int catalog;
};
template <class charT>
class messages : public locale::facet, public messages_base {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit messages(size_t = 0);
catalog open(const basic_string<char>&, const locale&) const;
string_type get(catalog, int, int,
const string_type&) const;
void close(catalog) const;
static locale::id id;
protected:
~messages(); // virtual
virtual catalog do_open(const basic_string<char>&,
const locale&) const;
virtual string_type do_get(catalog, int, int,
const string_type&) const;
virtual void do_close(catalog) const;
};
class messages_byname : public messages<charT> {
public:
explicit messages_byname(const char*, size_t = 0);
protected:
~messages_byname(); // virtual
virtual catalog do_open(const basic_string<char>&,
const locale&) const;
virtual string_type do_get(catalog, int, int,
const string_type&) const;
virtual void do_close(catalog) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit messages(size_t refs = 0)
Construct a messages facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other hand, if refs is 1 then
the object must be explicitly deleted: the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
explicit messages_byname(const char* name, size_t refs = 0);
Construct a messages_byname facet. Use the named locale
specified by the name argument. The refs argument serves the
same purpose as it does for the messages constructor.
~messages(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the messages facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public open function simply calls its protected cousin do_open.
void
close(catalog c) const;
string_type
get(catalog c, int set, int msgid,
const string_type& dfault) const;
catalog
open(const basic_string<char>& fn, const locale&) const;
Each of these public member functions xxx simply call the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual void
do_close(catalog cat) const;
Closes the catalog. The cat argument must have been obtained by
a call to open().
virtual string_type
do_get(catalog cat, int set, int msgid,
const string_type& dfault) const;
Retrieves a specific message. Returns the message identified by
cat, set, msgid, and dfault. cat must have been obtained by a
previous call to open() and this function must not be called
with a cat that has had close() called on yet after the
last call to open(). In other words, the catalog must have been
opened and not yet closed.
virtual catalog
do_open(const basic_string<char>& name, const locale&) const;
Opens a message catalog. Returns a catalog identifier that can
be passed to the get() function in order to access specific
messages. Returns -1 if the catalog name specificed in the
name argument is invalid. The loc argument will be used
for codeset conversion if necessary.
EXAMPLE
//
// messages.cpp
//
#include <string>
#include <iostream>
int main ()
{
using namespace std;
locale loc;
// Get a reference to the messages<char> facet
const messages<char>& mess =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<messages<char> >(loc);
#else
use_facet(loc,(messages<char>*)0);
#endif
// Open a catalog and try to grab
// both some valid messages, and an invalid message
string def("Message Not Found");
messages<char>::catalog cat =
mess.open("./rwstdmessages.cat",loc);
if (cat != -1)
{
string msg0 = mess.get(cat,1,1,def);
string msg1 = mess.get(cat,1,2,def);
string msg2 = mess.get(cat,1,6,def); // invalid msg #
string msg3 = mess.get(cat,2,1,def);
mess.close(cat);
cout << msg0 << endl << msg1 << endl
<< msg2 << endl << msg3 << endl;
}
else
cout << "Unable to open message catalog" << endl;
return 0;
}
SEE ALSO
locale, facets
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
moneypunct
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
moneypunct, moneypunct_byname - Monetary punctuation facets.
SYNOPSIS
#include <locale>
class money_base;
template <class charT, bool International = false>
class moneypunct;
DESCRIPTION
The moneypunct facets provide formatting specifications and
punctuation character for monetary values. The moneypunct facet
provides punctuation based on the "C" locale, while the
moneypunct_byname facet provides the same facilities for named
locales.
The facet is used by money_put for outputting formatted
representations of monetary values and by money_get for reading
these strings back in.
money_base provides a structure, pattern, that specifies the order
of syntactic elements in a monetary value and enumeration
values representing those elements. The pattern struct provides
a simple array of characters, field. Each index in field
is taken up by an enumeration value indicating the location of a
syntactic element. The enumeration values are described below:
Format Flag Meaning
none No grouping seperator
space Use space for grouping seperator
symbol Currency symbol
sign Sign of monetary value
value The monetary value itself
The do_pos_format an do_neg_format member functions of moneypunct
both return the pattern type. See the description of these
functions for further elaboration.
INTERFACE
class money_base {
public:
enum part { none, space, symbol, sign, value };
struct pattern { char field[4]; };
};
template <class charT, bool International = false>
class moneypunct : public locale::facet, public money_base {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit moneypunct(size_t = 0);
charT decimal_point() const;
charT thousands_sep() const;
string grouping() const;
string_type curr_symbol() const;
string_type positive_sign() const;
string_type negative_sign() const;
int frac_digits() const;
pattern pos_format() const;
pattern neg_format() const;
static locale::id id;
static const bool intl = International;
protected:
~moneypunct(); // virtual
virtual charT do_decimal_point() const;
virtual charT do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_curr_symbol() const;
virtual string_type do_positive_sign() const;
virtual string_type do_negative_sign() const;
virtual int do_frac_digits() const;
virtual pattern do_pos_format() const;
virtual pattern do_neg_format() const;
};
template <class charT, bool Intl = false>
class moneypunct_byname : public moneypunct<charT, Intl> {
public:
explicit moneypunct_byname(const char*, size_t = 0);
protected:
~moneypunct_byname(); // virtual
virtual charT do_decimal_point() const;
virtual charT do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_curr_symbol() const;
virtual string_type do_positive_sign() const;
virtual string_type do_negative_sign() const;
virtual int do_frac_digits() const;
virtual pattern do_pos_format() const;
virtual pattern do_neg_format() const;
};
TYPES
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit moneypunct(size_t refs = 0)
Constructs a moneypunct facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore
lifetime management issues. On the other had, if refs is 1
then the object must be explicitly deleted; the locale will not
do so. In this case, the object can be maintained across the
lifetime of multiple locales.
explicit moneypunct_byname(const char* name, size_t refs = 0);
Constructs a moneypunct_byname facet. Uses the named locale
specified by the name argument. The refs argument serves
the same purpose as it does for the moneypunct constructor.
~moneypunct(); // virtual and protected
Destroy the facet
STATIC MEMBERS
static locale::id id;
Unique identifier for this type of facet.
static const bool intl = Intl;
true if international representation, false otherwise.
PUBLIC MEMBER FUNCTIONS
The public members of the moneypunct and moneypunct_byname facets
provide an interface to protected members. Each public member xxx
has a corresponding virtual protected member do_xxx. All work is
delagated to these protected members. For instance, the
long version of the public decimal_point function simply calls
its protected cousin do_decimal_point.
string_type curr_symbol() const;
charT decimal_point() const;
int frac_digits() const;
string grouping() const;
pattern neg_format() const;
string_type negative_sign() const;
pattern pos_format() const;
string_type positive_sign() const;
charT thousands_sep() const;
Each of these public member functions xxx simply calls the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual string_type
do_curr_symbol() const;
Returns a string to use as the currency symbol.
virtual charT
do_decimal_point() const;
Returns the radix separator to use if fractional digits are
allowed (see do_frac_digits).
virtual int
do_frac_digits() const;
Returns the number of digits in the fractional part of the
monetary representation.
virtual string
do_grouping() const;
Returns a string in which each character is used as an integer
value to represent the number of digits in a particular grouping,
starting with the rightmost group. A group is simply the digits
between adjacent thousands' separators. Each group at a
position larger than the size of the string gets the same
value as the last element in the string. If a value is less
than or equal to zero, or equal to CHAR_MAX, then the size
of that group is unlimited. moneypunct returns an empty
string, indicating no grouping.
virtual string_type
do_negative_sign() const;
A string to use as the negative sign. The first character of
this string will be placed in the position indicated by the
format pattern (see do_neg_format); the rest of the characters,
if any, will be placed after all other parts of the monetary
value.
virtual pattern
do_neg_format() const;
virtual pattern
do_pos_format() const;
Returns a pattern object specifying the location of the various
syntactic elements in a monetary representation. The
enumeration values symbol, sign, and value will appear exactly
once in this pattern, with the remaining location taken by
either none or space. none will never occupy the first
position in the pattern and space will never occupy the first or
the last position. Beyond these restrictions, elements may
appear in any order. moneypunct returns {symbol, sign, none,
value}.
virtual string_type
do_positive_sign() const;
A string to use as the positive sign. The first character of
this string will be placed in the position indicated by the
format pattern (see do_pos_format); the rest of the characters,
if any, will be placed after all other parts of the monetary
value.
virtual charT
do_thousands_sep() const;
Reurns the grouping seperator if grouping is allowed (see
do_grouping).
EXAMPLE
//
// moneypun.cpp
//
#include <string>
#include <iostream>
int main ()
{
using namespace std;
locale loc;
// Get a moneypunct facet
const moneypunct<char,false>& mp =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<moneypunct<char,false> >(loc);
#else
use_facet(loc,(moneypunct<char,false>*)0);
#endif
cout << "Decimal point = "
<< mp.decimal_point() << endl;
cout << "Thousands seperator = "
<< mp.thousands_sep() << endl;
cout << "Currency symbol = "
<< mp.curr_symbol() << endl;
cout << "Negative Sign = "
<< mp.negative_sign() << endl;
cout << "Digits after decimal = "
<< mp.frac_digits() << endl;
return 0;
}
SEE ALSO
locale, facets, money_put, money_get
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
moneypunct_byname
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
moneypunct, moneypunct_byname - Monetary punctuation facets.
SYNOPSIS
#include <locale>
class money_base;
template <class charT, bool International = false>
class moneypunct;
DESCRIPTION
The moneypunct facets provide formatting specifications and
punctuation character for monetary values. The moneypunct facet
provides punctuation based on the "C" locale, while the
moneypunct_byname facet provides the same facilities for named
locales.
The facet is used by money_put for outputting formatted
representations of monetary values and by money_get for reading
these strings back in.
money_base provides a structure, pattern, that specifies the order
of syntactic elements in a monetary value and enumeration
values representing those elements. The pattern struct provides
a simple array of characters, field. Each index in field
is taken up by an enumeration value indicating the location of a
syntactic element. The enumeration values are described below:
Format Flag Meaning
none No grouping seperator
space Use space for grouping seperator
symbol Currency symbol
sign Sign of monetary value
value The monetary value itself
The do_pos_format an do_neg_format member functions of moneypunct
both return the pattern type. See the description of these
functions for further elaboration.
INTERFACE
class money_base {
public:
enum part { none, space, symbol, sign, value };
struct pattern { char field[4]; };
};
template <class charT, bool International = false>
class moneypunct : public locale::facet, public money_base {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit moneypunct(size_t = 0);
charT decimal_point() const;
charT thousands_sep() const;
string grouping() const;
string_type curr_symbol() const;
string_type positive_sign() const;
string_type negative_sign() const;
int frac_digits() const;
pattern pos_format() const;
pattern neg_format() const;
static locale::id id;
static const bool intl = International;
protected:
~moneypunct(); // virtual
virtual charT do_decimal_point() const;
virtual charT do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_curr_symbol() const;
virtual string_type do_positive_sign() const;
virtual string_type do_negative_sign() const;
virtual int do_frac_digits() const;
virtual pattern do_pos_format() const;
virtual pattern do_neg_format() const;
};
template <class charT, bool Intl = false>
class moneypunct_byname : public moneypunct<charT, Intl> {
public:
explicit moneypunct_byname(const char*, size_t = 0);
protected:
~moneypunct_byname(); // virtual
virtual charT do_decimal_point() const;
virtual charT do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_curr_symbol() const;
virtual string_type do_positive_sign() const;
virtual string_type do_negative_sign() const;
virtual int do_frac_digits() const;
virtual pattern do_pos_format() const;
virtual pattern do_neg_format() const;
};
TYPES
char_type
Type of character the facet is instantiated on.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit moneypunct(size_t refs = 0)
Constructs a moneypunct facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore
lifetime management issues. On the other hand, if refs is 1
then the object must be explicitly deleted; the locale will not
do so. In this case, the object can be maintained across the
lifetime of multiple locales.
explicit moneypunct_byname(const char* name, size_t refs = 0);
Constructs a moneypunct_byname facet. Uses the named locale
specified by the name argument. The refs argument serves
the same purpose as it does for the moneypunct constructor.
~moneypunct(); // virtual and protected
Destroy the facet
STATIC MEMBERS
static locale::id id;
Unique identifier for this type of facet.
static const bool intl = Intl;
true if international representation, false otherwise.
PUBLIC MEMBER FUNCTIONS
The public members of the moneypunct and moneypunct_byname facets
provide an interface to protected members. Each public member xxx
has a corresponding virtual protected member do_xxx. All work is
delagated to these protected members. For instance, the
long version of the public decimal_point function simply calls
its protected cousin do_decimal_point.
string_type curr_symbol() const;
charT decimal_point() const;
int frac_digits() const;
string grouping() const;
pattern neg_format() const;
string_type negative_sign() const;
pattern pos_format() const;
string_type positive_sign() const;
charT thousands_sep() const;
Each of these public member functions xxx simply calls the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual string_type
do_curr_symbol() const;
Returns a string to use as the currency symbol.
virtual charT
do_decimal_point() const;
Returns the radix separator to use if fractional digits are
allowed (see do_frac_digits).
virtual int
do_frac_digits() const;
Returns the number of digits in the fractional part of the
monetary representation.
virtual string
do_grouping() const;
Returns a string in which each character is used as an integer
value to represent the number of digits in a particular grouping,
starting with the rightmost group. A group is simply the digits
between adjacent thousands' separators. Each group at a
position larger than the size of the string gets the same
value as the last element in the string. If a value is less
than or equal to zero, or equal to CHAR_MAX, then the size
of that group is unlimited. moneypunct returns an empty
string, indicating no grouping.
virtual string_type
do_negative_sign() const;
A string to use as the negative sign. The first character of
this string will be placed in the position indicated by the
format pattern (see do_neg_format); the rest of the characters,
if any, will be placed after all other parts of the monetary
value.
virtual pattern
do_neg_format() const;
virtual pattern
do_pos_format() const;
Returns a pattern object specifying the location of the various
syntactic elements in a monetary representation. The
enumeration values symbol, sign, and value will appear exactly
once in this pattern, with the remaining location taken by
either none or space. none will never occupy the first
position in the pattern and space will never occupy the first or
the last position. Beyond these restrictions, elements may
appear in any order. moneypunct returns {symbol, sign, none,
value}.
virtual string_type
do_positive_sign() const;
A string to use as the positive sign. The first character of
this string will be placed in the position indicated by the
format pattern (see do_pos_format); the rest of the characters,
if any, will be placed after all other parts of the monetary
value.
virtual charT
do_thousands_sep() const;
Reurns the grouping seperator if grouping is allowed (see
do_grouping).
EXAMPLE
//
// moneypun.cpp
//
#include <string>
#include <iostream>
int main ()
{
using namespace std;
locale loc;
// Get a moneypunct facet
const moneypunct<char,false>& mp =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<moneypunct<char,false> >(loc);
#else
use_facet(loc,(moneypunct<char,false>*)0);
#endif
cout << "Decimal point = "
<< mp.decimal_point() << endl;
cout << "Thousands seperator = "
<< mp.thousands_sep() << endl;
cout << "Currency symbol = "
<< mp.curr_symbol() << endl;
cout << "Negative Sign = "
<< mp.negative_sign() << endl;
cout << "Digits after decimal = "
<< mp.frac_digits() << endl;
return 0;
}
SEE ALSO
locale, facets, money_put, money_get
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
money_get
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
money_get - Monetary formatting facet for input.
SYNOPSIS
#include <locale>
template <class charT, bool Intl = false,
class InputIterator = istreambuf_iterator<charT> >
class money_get;
DESCRIPTION
The money_get facet interprets formatted monetary string values.
The Intl template pa,rameter is used to specify locale or
international formatting. If Intl is true then international
formatting is used, otherwise locale formatting is used.
INTERFACE
template <class charT, bool Intl = false,
class InputIterator = istreambuf_iterator<charT> >
class money_get : public locale::facet {
public:
typedef charT char_type;
typedef InputIterator iter_type;
typedef basic_string<charT> string_type;
explicit money_get(size_t = 0);
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, long double&) const;
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, string_type&) const;
static const bool intl = Intl;
static locale::id id;
protected:
~money_get(); // virtual
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&,
long double&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&,
string_type&) const;
};
TYPES
char_type
Type of character upon which the facet is instantiated.
iter_type
Type of iterator used to scan the character buffer.
string_type
Type of character string passed to member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit money_get(size_t refs = 0)
Construct a money_get facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
~money_get(); // virtual and protected
Destroy the facet
<REFSECT1> <ANCHOR>
STATIC MEMBERS
static locale::id id;
Unique identifier for this type of facet.
static const bool intl = Intl;
true if international formatting is used, false otherwise.
PUBLIC MEMBER FUNCTIONS
The public members of the money_get facet provide an interface to
protected members. Each public member get has a corresponding
virtual protected member do_get.
iter_type
get(iter_type s, iter_type end, ios_base& f,
ios_base::iostate& err, long double& units) const;
iter_type
get(iter_type s, iter_type end, ios_base& f,
ios_base::iostate& err, string_type& digits) const;
Each of these two overloads of the public member function get calls the
corresponding protected do_get function.
PROTECTED MEMBER FUNCTIONS
virtual iter_type
do_get(iter_type s, iter_type end,
ios_base& f,
ios_base::iostate& err,
long double& units) const;
virtual iter_type
do_get(iter_type s, iter_type end,
ios_base& f,
ios_base::iostate& err,
string_type& digits) const;
Reads in a localized character representation of a monetary value
and generates a generic representation, either as a seqeuence
of digits or as a long double value. In either case do_get
uses the smallest possible unit of currency.
Both overloads of do_get read characters from the range [s,end)
until one of three things occurs:
+ A monetary value is assembled
+ An error occurs
+ No more characters are available.
The functions use f.flags() and the moneypunct<charT> facet from
f.getloc() for formatting information to use in intrepreting the
sequence of characters. do_get then places a pure sequence of
digits representing the monetary value in the smallest possible
unit of currency into the string argument digits, or it
calculates a long double value based on those digits and returns
that value in units.
The following specifics apply to formatting:
+ Digit group seperators are optional. If no grouping is
specified then in thousands seperator characters are treated
as delimiters.
+ If space or none are part of the format pattern in
moneypunct then optional whitespace is consumed, except at
the end. See the moneypunct reference section for a description
of money specific formatting flags.
+ If iosbase::showbase is set in f.flags() then the currency
symbol is optional, and if it appears after all other elements
then it will not be consumed. Otherwise the currency symbol
is required, and will be consumed where ever it occurs.
+ digits will be preceded by a '-' , or units will be negated,
if the monetary value is negative.
+ See the moneypunct reference section for a description of
money specific formatting flags.
The err argument will be set to iosbase::failbit if an error
occurs during parsing.
Returns an iterator pointing one past the last character that is
part of a valid monetary sequence.
EXAMPLE
//
// moneyget.cpp
//
#include <string>
#include <sstream>
int main ()
{
using namespace std;
typedef istreambuf_iterator<char,char_traits<char> > iter_type;
locale loc;
string buffer("$100.02");
string dest;
long double ldest;
ios_base::iostate state;
iter_type end;
// Get a money_get facet
const money_get<char,false,iter_type>& mgf =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<money_get<char,false,iter_type> >(loc);
#else
use_facet(loc,(money_get<char,false,iter_type>*)0);
#endif
{
// Build an istringstream from the buffer and construct
// a beginning iterator on it.
istringstream ins(buffer);
iter_type begin(ins);
// Get a a string representation of the monetary value
mgf.get(begin,end,ins,state,dest);
}
{
// Build another istringstream from the buffer, etc.
// so we have an iterator pointing to the beginning
istringstream ins(buffer);
iter_type begin(ins);
// Get a a long double representation
// of the monetary value
mgf.get(begin,end,ins,state,ldest);
}
cout << buffer << " --> " << dest
<< " --> " << ldest << endl;
return 0;
}
SEE ALSO
locale, facets,money_put, moneypunct
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
money_put
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
money_put - Monetary formatting facet for output.
SYNOPSIS
#include <locale>
template <class charT, bool Intl = false,
class OutputIterator = ostreambuf_iterator<charT> >
class money_put;
DESCRIPTION
The money_put facet takes a long double value, or generic sequence
of digits and writes out a formatted representation of the
monetary value.
INTERFACE
template <class charT, bool Intl = false,
class OutputIterator = ostreambuf_iterator<charT> >
class money_put : public locale::facet {
public:
typedef charT char_type;
typedef OutputIterator iter_type;
typedef basic_string<charT> string_type;
explicit money_put(size_t = 0);
iter_type put(iter_type, ios_base&, char_type,
long double) const;
iter_type put(iter_type, ios_base&, char_type,
const string_type&) const;
static const bool intl = Intl;
static locale::id id;
protected:
~money_put(); // virtual
virtual iter_type do_put(iter_type, ios_base&, char_type,
long double) const;
virtual iter_type do_put(iter_type, ios_base&, char_type,
const string_type&) const;
};
TYPES
char_type
Type of the character upon which the facet is instantiated.
iter_type
Type of iterator used to scan the character buffer.
string_type
Type of character string passed to member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit money_put(size_t refs = 0)
Construct a money_put facet. If the refs argument is 0
then destruction of the object is delegated to the locale,
or locales, containing it. This allows the user to ignore
lifetime management issues. On the other had, if refs is
1 then the object must be explicitly deleted; the locale will
not do so. In this case, the object can be maintained across
the lifetime of multiple locales.
~money_put(); // virtual and protected
Destroy the facet
STATIC MEMBERS
static locale::id id;
Unique identifier for this type of facet.
static const bool intl = Intl;
true if international representation, false otherwise.
PUBLIC MEMBER FUNCTIONS
The public members of the money_put facet provide an interface to
protected members. Each public member put has a corresponding
virtual protected member do_put.
iter_type
put(iter_type s, ios_base& f, char_type fill,
long double units) const;
iter_type
put(iter_type s, ios_base& f, char_type fill,
const string_type& digits) const;
Each of these two overloads of the public member function put
simply calls the corresponding protected do_put function.
PROTECTED MEMBER FUNCTIONS
virtual iter_type
do_put(iter_type s, ios_base& f, char_type fill,
long double units) const;
Writes out a character string representation of the monetary
value contained in units. Since units represents the
monetary value in the smallest possible unit of
currency any fractional portions of the value are ignored.
f.flags() and the moneypunct<charT> facet from f.getloc() provide
the formatting information.
The fill argument is used for any padding.
Returns an iterator pointing one past the last character written.
virtual iter_type
do_put(iter_type s, ios_base& f, char_type fill,
const string_type& digits) const;
Writes out a character string representation of the monetary
contained in digits. digits represents the monetary value
as a sequence of digits in the smallest possible unit of
currency. do_put only looks at an optional - character and
any immediatly contigous digits. f.flags() and the
moneypunct<charT> facet from f.getloc() provide the formatting
information.
The fill argument is used for any padding.
Returns an iterator pointing one past the last character written.
EXAMPLE
//
// moneyput.cpp
//
#include <string>
#include <iostream>
int main ()
{
using namespace std;
typedef ostreambuf_iterator<char,char_traits<char> > iter_type;
locale loc;
string buffer("10002");
long double ldval = 10002;
// Construct a ostreambuf_iterator on cout
iter_type begin(cout);
// Get a money put facet
const money_put<char,false,iter_type>& mp =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<money_put<char,false,iter_type> >(loc);
#else
use_facet(loc,(money_put<char,false,iter_type>*)0);
#endif
// Put out the string representation of the monetary value
cout << buffer << " --> ";
mp.put(begin,cout,' ',buffer);
// Put out the long double representation
// of the monetary value
cout << endl << ldval << " --> ";
mp.put(begin,cout,' ',ldval);
cout << endl;
return 0;
}
SEE ALSO
locale, facets, money_get, moneypunct
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
numpunct
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
numpunct, numpunct_byname - Numeric punctuation facet.
SYNOPSIS
#include <locale>
template <class charT> class numpunct;
template <class charT> class numpunct_byname;
DESCRIPTION
The numpunct<charT> facet specifies numeric punctuation. This
template provides punctuation based on the "C" locale, while
the numpunct_byname facet provides the same facilities for named
locales.
Both num_put and num_get make use of this facet.
INTERFACE
template <class charT>
class numpunct : public locale::facet {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit numpunct(size_t refs = 0);
char_type decimal_point() const;
char_type thousands_sep() const;
string grouping() const;
string_type truename() const;
string_type falsename() const;
static locale::id id;
protected:
~numpunct(); // virtual
virtual char_type do_decimal_point() const;
virtual char_type do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_truename() const; // for bool
virtual string_type do_falsename() const; // for bool
};
template <class charT>
class numpunct_byname : public numpunct<charT> {
public:
explicit numpunct_byname(const char*, size_t refs = 0);
protected:
~numpunct_byname(); // virtual
virtual char_type do_decimal_point() const;
virtual char_type do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_truename() const; // for bool
virtual string_type do_falsename() const; // for bool
};
TYPES
char_type
Type of character upon which the facet is instantiated.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit numpunct(size_t refs = 0)
Construct a numpunct facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
explicit numpunct_byname(const char* name, size_t refs = 0);
Construct a numpunct_byname facet. Use the named locale
specified by the name argument. The refs argument serves the
same purpose as it does for the numpunct constructor.
~numpunct(); // virtual and protected
~numpunct_byname(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the numpunct facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public grouping function simply calls its protected cousin
do_grouping.
char_type decimal_point() const;
string_type falsename() const;
string grouping() const;
char_type thousands_sep() const;
string_type truename() const;
Each of these public member functions xxx simply call the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual char_type
do_decimal_point() const;
Returns the decimal radix separator . numpunct returns '.'.
virtual string_type
do_falsename() const; // for bool
virtual string_type
do_truename() const; // for bool
Returns a string representing the name of the boolean values true
and false respectively. numpunct returns "true" and
"false".
virtual string
do_grouping() const;
Returns a string in which each character is used as an integer
value to represent the number of digits in a particular grouping,
starting with the rightmost group. A group is simply the digits
between adjacent thousands separators. Each group at a
position larger than the size of the string gets the same
value as the last element in the string. If a value is less
than or equal to zero, or equal to CHAR_MAX then the size
of that group is unlimited. numpunct returns an empty string,
indicating no grouping.
virtual char_type
do_thousands_sep() const;
Returns the decimal digit group seperator. numpunct returns ','.
EXAMPLE
//
// numpunct.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
// Get a numpunct facet
const numpunct<char>& np =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<numpunct<char> >(loc);
#else
use_facet(loc,(numpunct<char>*)0);
#endif
cout << "Decimal point = "
<< np.decimal_point() << endl;
cout << "Thousands seperator = "
<< np.thousands_sep() << endl;
cout << "True name = "
<< np.truename() << endl;
cout << "False name = "
<< np.falsename() << endl;
return 0;
}
SEE ALSO
locale, facets, num_put, num_get, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
numpunct_byname
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
numpunct, numpunct_byname - Numeric punctuation facet.
SYNOPSIS
#include <locale>
template <class charT> class numpunct;
template <class charT> class numpunct_byname;
DESCRIPTION
The numpunct<charT> facet specifies numeric punctuation. This template
provides punctuation based on the "C" locale, while the numpunct_byname
facet provides the same facilities for named locales.
Both num_put and num_get make use of this facet.
INTERFACE
template <class charT>
class numpunct : public locale::facet {
public:
typedef charT char_type;
typedef basic_string<charT> string_type;
explicit numpunct(size_t refs = 0);
char_type decimal_point() const;
char_type thousands_sep() const;
string grouping() const;
string_type truename() const;
string_type falsename() const;
static locale::id id;
protected:
~numpunct(); // virtual
virtual char_type do_decimal_point() const;
virtual char_type do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_truename() const; // for bool
virtual string_type do_falsename() const; // for bool
};
template <class charT>
class numpunct_byname : public numpunct<charT> {
public:
explicit numpunct_byname(const char*, size_t refs = 0);
protected:
~numpunct_byname(); // virtual
virtual char_type do_decimal_point() const;
virtual char_type do_thousands_sep() const;
virtual string do_grouping() const;
virtual string_type do_truename() const; // for bool
virtual string_type do_falsename() const; // for bool
};
TYPES
char_type
Type of character upon which the facet is instantiated.
string_type
Type of character string returned by member functions.
CONSTRUCTORS AND DESTRUCTORS
explicit numpunct(size_t refs = 0)
Construct a numpunct facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
explicit numpunct_byname(const char* name, size_t refs = 0);
Construct a numpunct_byname facet. Use the named locale
specified by the name argument. The refs argument serves the
same purpose as it does for the numpunct constructor.
~numpunct(); // virtual and protected
~numpunct_byname(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the numpunct facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public grouping function simply calls its protected cousin
do_grouping.
char_type decimal_point() const;
string_type falsename() const;
string grouping() const;
char_type thousands_sep() const;
string_type truename() const;
Each of these public member functions xxx simply call the
corresponding protected do_xxx function.
PROTECTED MEMBER FUNCTIONS
virtual char_type
do_decimal_point() const;
Returns the decimal radix separator . numpunct returns '.'.
virtual string_type
do_falsename() const; // for bool
virtual string_type
do_truename() const; // for bool
Returns a string representing the name of the boolean values true
and false respectively. numpunct returns "true" and
"false".
virtual string
do_grouping() const;
Returns a string in which each character is used as an integer
value to represent the number of digits in a particular grouping,
starting with the rightmost group. A group is simply the digits
between adjacent thousands separators. Each group at a
position larger than the size of the string gets the same
value as the last element in the string. If a value is less
than or equal to zero, or equal to CHAR_MAX then the size
of that group is unlimited. numpunct returns an empty string,
indicating no grouping.
virtual char_type
do_thousands_sep() const;
Returns the decimal digit group seperator. numpunct returns ','.
EXAMPLE
//
// numpunct.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
// Get a numpunct facet
const numpunct<char>& np =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<numpunct<char> >(loc);
#else
use_facet(loc,(numpunct<char>*)0);
#endif
cout << "Decimal point = "
<< np.decimal_point() << endl;
cout << "Thousands seperator = "
<< np.thousands_sep() << endl;
cout << "True name = "
<< np.truename() << endl;
cout << "False name = "
<< np.falsename() << endl;
return 0;
}
SEE ALSO
locale, facets, num_put, num_get, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
num_get
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
num_get - Numeric formatting facet for input.
SYNOPSIS
#include <locale>
template <class charT, class InputIterator > class num_get;
DESCRIPTION
The num_get provides facilities for formatted input of numbers.
basic_istream and all other input-oriented streams use this facet to imple-
ment formatted numeric input.
INTERFACE
template <class charT, class InputIterator = istreambuf_iterator<charT> >
class num_get : public locale::facet {
public:
typedef charT char_type;
typedef InputIterator iter_type;
explicit num_get(size_t refs = 0);
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, bool&) const;
iter_type get(iter_type, iter_type, ios_base& ,
ios_base::iostate&, long&) const;
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, unsigned short&) const;
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, unsigned int&) const;
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, unsigned long&) const;
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, float&) const;
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, double&) const;
iter_type get(iter_type, iter_type, ios_base&,
ios_base::iostate&, long double&) const;
static locale::id id;
protected:
~num_get(); // virtual
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&, bool&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&, long&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&,
unsigned short&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&,
unsigned int&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&,
unsigned long&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&, float&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&, double&) const;
virtual iter_type do_get(iter_type, iter_type, ios_base&,
ios_base::iostate&,
long double&) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
iter_type
Type of iterator used to scan the character buffer.
CONSTRUCTOR AND DESTRUCTOR
explicit num_get(size_t refs = 0)
Construct a num_get facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
~num_get(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the num_get facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public get function simply calls its protected cousin
do_get.
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, bool& v) const;
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, long& v) const;
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, unsigned short& v) const;
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, unsigned int& v) const;
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, unsigned long& v) const;
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, float& v) const;
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, double& v) const;
iter_type
get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, long double& v) const;
Each of the eight overloads of the get function simply call the
corresponding do_get function.
PROTECTED MEMBER FUNCTIONS
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, bool& v) const;
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, long& v) const;
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err,
unsigned short& v) const;
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err,
unsigned int& v) const;
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err,
unsigned long& v) const;
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, float& v) const;
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& err, double& v) const;
virtual iter_type
do_get(iter_type in, iter_type end, ios_base& io,
ios_base::iostate& long double& v) const;
The eight overloads of the do_get member function all take a
sequence of characters [int,end), and extract a numeric
value. The numeric value is returned in v. The io argument
is used to obtain formatting information and the err argument
is used to set error conditions in a calling stream.
EXAMPLE
//
// numget.cpp
//
#include <sstream>
int main ()
{
using namespace std;
typedef istreambuf_iterator<char,char_traits<char> > iter_type;
locale loc;
ios_base::iostate state;
bool bval = false;
long lval = 0L;
long double ldval = 0.0;
iter_type end;
// Get a num_get facet
const num_get<char,iter_type>& tg =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<num_get<char,iter_type> >(loc);
#else
use_facet(loc,(num_get<char,iter_type>*)0);
#endif
{
// Build an istringstream from the buffer and construct
// beginning and ending iterators on it.
istringstream ins("true");
iter_type begin(ins);
// Get a bool value
tg.get(begin,end,ins,state,bval);
}
cout << bval << endl;
{
// Get a long value
istringstream ins("2422235");
iter_type begin(ins);
tg.get(begin,end,ins,state,lval);
}
cout << lval << endl;
{
// Get a long double value
istringstream ins("32324342.98908");
iter_type begin(ins);
tg.get(begin,end,ins,state,ldval);
}
cout << ldval << endl;
return 0;
}
SEE ALSO
locale, facets, num_put, numpunct, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
num_put
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
num_put - Numeric formatting facet for output.
SYNOPSIS
#include <locale>
template <class charT, class OutputIterator> class num_put;
DESCRIPTION
The num_put<charT,OutputIterator> template provides facilities for
formatted output of numbers. basic_ostream and all other input
oriented streams use this facet to implement formatted
numeric output.
INTERFACE
template <class charT, class OutputIterator =
ostreambuf_iterator<charT> >
class num_put : public locale::facet {
public:
typedef charT char_type;
typedef OutputIterator iter_type;
explicit num_put(size_t = 0);
iter_type put(iter_type, ios_base&, char_type, bool) const;
iter_type put(iter_type, ios_base&, char_type, long) const;
iter_type put(iter_type, ios_base&, char_type,
unsigned long) const;
iter_type put(iter_type, ios_base&, char_type,
double) const;
iter_type put(iter_type, ios_base&, char_type,
long double) const;
static locale::id id;
protected:
~num_put(); // virtual
virtual iter_type do_put(iter_type, ios_base&, char_type,
bool) const;
virtual iter_type do_put(iter_type, ios_base&, char_type,
long) const;
virtual iter_type do_put(iter_type, ios_base&, char_type,
unsigned long) const;
virtual iter_type do_put(iter_type, ios_base&, char_type,
double) const;
virtual iter_type do_put(iter_type, ios_base&, char_type,
long double) const;
};
TYPES
char_type
Type of character upon which the facet is instantiated.
iter_type
Type of iterator used to scan the character buffer.
CONSTRUCTORS AND DESTRUCTORS
explicit num_put(size_t refs = 0)
Construct a num_put facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
~num_put(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the num_put facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public put function simply calls its protected cousin
do_put.
iter_type
put(iter_type s, ios_base& io, char_type fill, bool v) const;
iter_type
put(iter_type s, ios_base& io, char_type fill, long v) const;
iter_type
put(iter_type s, ios_base& io, char_type fill,
unsigned long v) const;
iter_type
put(iter_type s, ios_base& io, char_type fill, double v) const;
iter_type
put(iter_type s, ios_base& io, char_type fill, long double v) const;
Each of the five overloads of the put function simply call the
corresponding do_put function.
PROTECTED MEMBER FUNCTIONS
virtual iter_type
do_put(iter_type s, ios_base& io,
char_type fill, bool v) const;
virtual iter_type
do_put(iter_type s, ios_base& io,
char_type fill, long v) const;
virtual iter_type
do_put(iter_type s, ios_base& io,
char_type fill,unsigned long) const;
virtual iter_type
do_put(iter_type s, ios_base& io,
char_type fill, double v) const;
virtual iter_type
do_put(iter_type s, ios_base& io,
char_type fill,long double v) const;
The five overloads of the do_put member function all take a
numeric value and output a formatted character string
representing that value. The character string is output
through the s argument to the function. The io argument is
used to obtain formatting specifications, and the fill
argument determines the character to use in padding.
EXAMPLE
//
// numput.cpp
//
#include <iostream>
int main ()
{
using namespace std;
typedef ostreambuf_iterator<char,char_traits<char> > iter_type;
locale loc;
bool bval = true;
long lval = 422432L;
unsigned long ulval = 12328889UL;
double dval = 10933.8934;
long double ldval = 100028933.8934;
// Construct a ostreambuf_iterator on cout
iter_type begin(cout);
// Get a num_put facet reference
const num_put<char,iter_type>& np =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<num_put<char,iter_type> >(loc);
#else
use_facet(loc,(num_put<char,iter_type>*)0);
#endif
// Put out a bool
cout << bval << " --> ";
np.put(begin,cout,' ',bval);
// Put out a long
cout << endl << lval << " --> ";
np.put(begin,cout,' ',lval);
// Put out an unsigned long
cout << endl << ulval << " --> ";
np.put(begin,cout,' ',ulval);
// Put out a double
cout << endl << dval << " --> ";
np.put(begin,cout,' ',dval);
// Put out a long double
cout << endl << ldval << " --> ";
np.put(begin,cout,' ',ldval);
cout << endl;
return 0;
}
SEE ALSO
locale, facets, numget, numpunct, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
time_get
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
time_get - Time formatting facet for input.
SYNOPSIS
#include <locale>
class time_base;
template <class charT, class InputIterator =
istreambuf_iterator<charT> >
class time_get;
DESCRIPTION
The time_get facet extracts time and date components from a
character string and stores the resulting values in a struct
tm argument. The facet parses the string using a specific format
as a guide. If the string does not fit the format, then the
facet will indicate an error by setting the err argument in the
public member functions to iosbase::failbit. See member function
descriptions for details.
The time_base class provides a set of values for specifying the
order in which the three parts of a date appear. The
dateorder function returns one of these five possible values:
Order Meaning
noorder Date format has no set ordering
dmy Date order is day, month, year
mdy Date order is month, day, year
ymd Date order is year, month, day
ydm Date order is year, day, month
INTERFACE
class time_base {
public:
enum dateorder { no_order, dmy, mdy, ymd, ydm };
};
template <class charT, class InputIterator =
istreambuf_iterator<charT> >
class time_get : public locale::facet, public time_base {
public:
typedef charT char_type;
typedef InputIterator iter_type;
explicit time_get(size_t = 0);
dateorder date_order() const;
iter_type get_time(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
iter_type get_date(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
iter_type get_weekday(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
iter_type get_monthname(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
iter_type get_year(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
static locale::id id;
protected:
~time_get(); // virtual
virtual dateorder do_date_order() const;
virtual iter_type do_get_time(iter_type, iter_type, os_base&,
ios_base::iostate&, tm*) const;
virtual iter_type do_get_date(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
virtual iter_type do_get_weekday(iter_type, iter_type, os_base&,
ios_base::iostate&, tm*) const;
virtual iter_type do_get_monthname(iter_type, ios_base&,
ios_base::iostate&, tm*) const;
virtual iter_type do_get_year(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
iter_type
Type of iterator used to scan the character buffer.
CONSTRUCTORS AND DESTRUCTORS
explicit time_get(size_t refs = 0)
Construct a time_get facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
~time_get(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
The public members of the time_get facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the long version of the
public get_time function simply calls its protected cousin
do_get_time.
dateorder
date_order() const;
iter_type
get_date(iter_type s, iter_type end, ios_base& f,
ios_base::iostate& err, tm* t) const;
iter_type
get_monthname(iter_type s, iter_type end, ios_base& f,
ios_base::iostate& err, tm* t) const;
iter_type
get_time(iter_type s, iter_type end, ios_base& f,
ios_base::iostate& err, tm* t) const;
iter_type
get_weekday(iter_type s, iter_type end, ios_base& f,
ios_base::iostate& err, tm* t) const;
iter_type
get_year(iter_type s, iter_type end, ios_base& f,
ios_base::iostate& err, tm* t) const;
Each of these public functions simply calls a corresponding protected
virtual do_ function.
PROTECTED MEMBER FUNCTIONS
virtual dateorder
do_date_order() const;
Return the a value indicating the relative ordering of the three
basic parts of a date. Possible return values are:
+ noorder, indicating that the date format has no ordering,
an ordering cannot be determined, or the date format
contains variable components other than Month, Day and
Year. noorder is never returned by the default time_put, but
may be used by derived classes.
+ one of dmy, mdy, ymd, ydm, indicating the relative ordering
of Day, Month and Year.
virtual iter_type
do_get_date(iter_type s, iter_type end, ios_base&,
ios_base::iostate& err, tm* t) const;
Fills out the t argument with date values parsed from the
character buffer specified by the range (s,end]. If the
buffer does not contain a valid date representation
then the err argument will be set to iosbase::failbit.
Returns an iterator pointing just beyond the last character that
can be determined to be part of a valid date.
virtual iter_type
do_get_monthname(iter_type s, ios_base&,
ios_base::iostate& err, tm* t) const;
Fills out the tm_mon member of the t argument with a month name
parsed from the character buffer specified by the range (s,end].
As with do_get_weekday, this name may be an abbreviation, but the
function will attempt to read a full name if valid characters
are found after an abbreviation. For example, if a full
name is "December", and an abbreviation is "Dec", then
the string "Dece" will cause an error. If an error occurs
then the err argument will be set to iosbase::failbit.
Returns an iterator pointing just beyond the last character that
can be determined to be part of a valid name.
virtual iter_type
do_get_time(iter_type s, iter_type end, os_base&,
ios_base::iostate& err, tm* t) const;
Fills out the t argument with time values parsed from the
character buffer specified by the range (s,end]. The buffer
must contain a valid time representation. Returns an iterator
pointing just beyond the last character that can be determined
to be part of a valid time.
virtual iter_type
do_get_weekday(iter_type s, iter_type end, os_base&,
ios_base::iostate& err, tm* t) const;
Fills out the tm_wday member of the t argument with a weekday
name parsed from the character buffer specified by the range
(s,end]. This name may be an abbreviation, but the function will
attempt to read a full name if valid characters are found
after an abbreviation. For instance, if a full name is "Monday",
and an abbreviation is "Mon", then the string "Mond" will
cause an error. If an error occurs then the err argument
will be set to iosbase::failbit.
Returns an iterator pointing just beyond the last character that
can be determined to be part of a valid name.
virtual iter_type
do_get_year(iter_type s, iter_type end, ios_base&,
ios_base::iostate& err, tm* t) const;
Fills in the tm_year member of the t argument with a year parsed
from the character buffer specified by the range (s,end]. If an
error occurs then the err argument will be set to
iosbase::failbit.
Returns an iterator pointing just beyond the last character that
can be determined to be part of a valid year.
EXAMPLE
//
// timeget.cpp
//
#include <locale>
#include <sstream>
#include <time.h>
using namespace std;
// Print out a tm struct
ostream& operator<< (ostream& os, const struct tm& t)
{
os << "Daylight Savings = " << t.tm_isdst << endl;
os << "Day of year = " << t.tm_yday << endl;
os << "Day of week = " << t.tm_wday << endl;
os << "Year = " << t.tm_year << endl;
os << "Month = " << t.tm_mon << endl;
os << "Day of month = " << t.tm_mday << endl;
os << "Hour = " << t.tm_hour << endl;
os << "Minute = " << t.tm_min << endl;
os << "Second = " << t.tm_sec << endl;
return os;
}
int main ()
{
typedef istreambuf_iterator<char,char_traits<char> > iter_type;
locale loc;
time_t tm = time(NULL);
struct tm* tmb = localtime(&tm);
struct tm timeb;
memcpy(&timeb,tmb,sizeof(struct tm));
ios_base::iostate state;
iter_type end;
// Get a time_get facet
const time_get<char,iter_type>& tg =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<time_get<char,iter_type> >(loc);
#else
use_facet(loc,(time_get<char,iter_type>*)0);
#endif
cout << timeb << endl;
{
// Build an istringstream from the buffer and construct
// beginning and ending iterators on it.
istringstream ins("12:46:32");
iter_type begin(ins);
// Get the time
tg.get_time(begin,end,ins,state,&timeb);
}
cout << timeb << endl;
{
// Get the date
istringstream ins("Dec 6 1996");
iter_type begin(ins);
tg.get_date(begin,end,ins,state,&timeb);
}
cout << timeb << endl;
{
// Get the weekday
istringstream ins("Tuesday");
iter_type begin(ins);
tg.get_weekday(begin,end,ins,state,&timeb);
}
cout << timeb << endl;
return 0;
}
SEE ALSO
locale, facets, time_put
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
time_get_byname
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
time_get_byname - A facet that provides formatted time input
facilities based on the named locales.
SYNOPSIS
#include <locale>
template <class charT, class InputIterator =
istreambuf_iterator<charT> >
class time_get_byname;
DESCRIPTION
The time_get_byname template provides the same functionality as the
time_get template, but specific to a particular named locale. For
a description of the member functions of time_get_byname, see the
reference for time_get. Only the constructor is described
here.
INTERFACE
template <class charT, class InputIterator =
istreambuf_iterator<charT> >
class time_get_byname : public time_get<charT, InputIterator> {
public:
explicit time_get_byname(const char*, size_t = 0);
protected:
~time_get_byname(); // virtual
virtual dateorder do_date_order() const;
virtual iter_type do_get_time(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
virtual iter_type do_get_date(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
virtual iter_type do_get_weekday(iter_type, iter_type, ios_base&,
ios_base::iostate& err, tm*) const;
virtual iter_type do_get_monthname(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
virtual iter_type do_get_year(iter_type, iter_type, ios_base&,
ios_base::iostate&, tm*) const;
};
CONSTRUCTOR
explicit time_get_byname(const char* name, size_t refs = 0);
Construct a time_get_byname facet. The facet will provide time
formatting facilities relative to the named locale specified by
the name argument. If the refs argument is 0 then
destruction of the object is delegated to the locale, or locales,
containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then the
object must be explicitly deleted; the locale will not do so. In
this case, the object can be maintained across the lifetime of
multiple locales.
SEE ALSO
locale, facets, time_get, time_put_byname
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
time_put
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
time_put - Time formatting facet for ouput.
SYNOPSIS
#include <locale>
template <class charT, class OutputIterator =
ostreambuf_iterator<charT> >
class time_put;
DESCRIPTION
The time_put facet provides facilities for formated output of
date/time values. The member function of time_put take a
date/time in the form of a struct tm and translate this into
character string representation.
INTERFACE
template <class charT, class OutputIterator =
ostreambuf_iterator<charT> >
class time_put : public locale::facet {
public:
typedef charT char_type;
typedef OutputIterator iter_type;
explicit time_put(size_t = 0);
iter_type put(iter_type, ios_base&,
char_type, const tm*,
const charT*, const charT*) const;
iter_type put(iter_type, ios_base&, char_type,
const tm*, char, char = 0) const;
static locale::id id;
protected:
~time_put(); // virtual
virtual iter_type do_put(iter_type, ios_base&,
char_type, const tm*,
char, char) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
iter_type
Type of iterator used to scan the character buffer.
CONSTRUCTORS AND DESTRUCTORS
explicit time_put(size_t refs = 0)
Construct a time_put facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore lifetime
management issues. On the other had, if refs is 1 then
the object must be explicitly deleted; the locale will not do
so. In this case, the object can be maintained across the
lifetime of multiple locales.
~time_put(); // virtual and protected
Destroy the facet
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PUBLIC MEMBER FUNCTIONS
iter_type
put(iter_type s, ios_base& f,
char_type fill, const tm* tmb,
const charT* pattern, const charT* pat_end) const;
Creates a character string representing the Date/Time contained
in tmb. The format of the string is determined by a sequence of
format modifiers contained in the range [pattern,pat_end). These
modifiers are from the same set as those use by the strftime
function and apply in exactly the same way. The resulting
string is written out to the buffer pointed to by the iterator
s. See the Table 1 below for a description of strftime
formatting characters.
The fill argument is used for any padding.
Returns an iterator pointing one past the last character written.
iter_type
put(iter_type s, ios_base& f, char_type fill,
const tm* tmb, char format, char modifier = 0) const;
Calls the protected virtual do_put function.
PROTECTED MEMBER FUNCTIONS
virtual iter_type
do_put(iter_type s, ios_base&,
char_type fill, const tm* t,
char format, char modifier) const;
Writes out a character string representation of the Date/Time
contained in t. The string is formatted according the the
specifier format and modifier modifier. These values are
interpreted in exactly the same way that the strftime function
intrprets its format and modifier flags. See the Table 1 below
for a description of strftime formatting characters.
The fill argument is used for any padding.
Returns an iterator pointing one past the last character written.
Table 1. Formatting characters used by strftime().
For those formats that do not use all members of the struct tm,
only those members that are actually used are noted [in
brackets].
Format
character Meaning Example
a Abbreviated weekday name
[from tm::tm_wday] Sun
A Full weekday name
[from tm::tm_wday] Sunday
b Abbreviated month name Feb
B Full month name February
c Date and time
[may use all members] Feb 29 14:34:56 1984
d Day of the month 29
H Hour of the 24-hour day 14
I Hour of the 12-hour day 02
j Day of the year,
from 001 [from tm::tm_yday] 60
m Month of the year, from 01 02
M Minutes after the hour 34
p AM/PM indicator, if any AM
S Seconds after the minute 56
U Sunday week of the year,
from 00 [from tm::tm_yday
and tm::tm_wday]
w Day of the week,
with 0 for Sunday 0
W Monday week of the year,
from 00 [from tm::tm_yday
and tm::tm_wday]
x Date [uses tm::tm_yday
in some locales] Feb 29 1984
X Time 14:34:56
y Year of the century,
from 00 (deprecated) 84
Y Year 1984
Z Time zone name
[from tm::tm_isdst] PST or PDT
EXAMPLE
//
// timeput.cpp
//
#include <iostream>
int main ()
{
using namespace std;
typedef ostreambuf_iterator<char,char_traits<char> > iter_type;
locale loc;
time_t tm = time(NULL);
struct tm* tmb = localtime(&tm);
struct tm timeb;
memcpy(&timeb,tmb,sizeof(struct tm));
char pat[] = "%c";
// Get a time_put facet
const time_put<char,iter_type>& tp =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<time_put<char,iter_type> >(loc);
#else
use_facet(loc,(time_put<char,iter_type>*)0);
#endif
// Construct a ostreambuf_iterator on cout
iter_type begin(cout);
cout << " --> ";
tp.put(begin,cout,' ',&timeb,pat,pat+2);
cout << endl << " --> ";
tp.put(begin,cout,' ',&timeb,'c',' ');
cout << endl;
return 0;
}
SEE ALSO
locale, facets, time_get
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
time_put_byname
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
time_put_byname - A facet that provides formatted time output
facilities based on the named locales.
SYNOPSIS
#include <locale>
template <class charT, class OuputIterator =
ostreambuf_iterator<charT> >
class time_put_byname;
DESCRIPTION
The time_put_byname template provides the same functionality as the
time_put template, but specific to a particular named locale. For
a description of the member functions of time_put_byname, see the
reference for time_put. Only the constructor is described
here.
INTERFACE
template <class charT, class OutputIterator =
ostreambuf_iterator<charT> >
class time_put_byname : public time_put<charT, OutputIterator>
{
public:
explicit time_put_byname(const char*, size_t refs = 0);
protected:
~time_put_byname(); // virtual
virtual iter_type do_put(iter_type s, ios_base&,
char_type, const tm* t,
char format, char modifier) const;
};
CONSTRUCTOR
explicit time_put_byname(const char* name, size_t refs = 0);
Construct a time_put_byname facet. The facet will provide time
formatting facilities relative to the named locale specified by
the name argument. If the refs argument is 0 then destruction of the
object is delegated to the locale, or locales, containing it.
This allows the user to ignore lifetime management issues. On
the other had, if refs is 1 then the object must be explicitly
deleted; the locale will not do so. In this case, the object
can be maintained across the lifetime of multiple locales.
SEE ALSO
locale, facets, time_put, time_get_byname
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
tolower
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
tolower - Converts a character to lower case.
SYNOPSIS
#include <locale>
template <class charT>
charT tolower (charT c, const locale& loc) const;
DESCRIPTION
The tolower returns the the parameter c converted to lower case.
The conversion is made using the ctype facet from the locale
parameter.
EXAMPLE
//
// toupper.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
cout << 'a' << toupper('c') << tolower('F') << endl;
return 0;
}
SEE ALSO
toupper, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
toupper
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
toupper - Converts a character to upper case.
SYNOPSIS
#include <locale>
template <class charT>
charT toupper (charT c, const locale& loc) const;
DESCRIPTION
The toupper returns the the parameter c converted to upper case.
The conversion is made using the ctype facet from the locale
parameter.
EXAMPLE
//
// toupper.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
cout << 'a' << toupper('c') << tolower('F') << endl;
return 0;
}
SEE ALSO
tolower, locale, ctype
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
use_facet
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
use_facet - Template function used to obtain a facet.
SYNOPSIS
#include <locale>
template <class Facet> const Facet& use_facet(const locale&);
DESCRIPTION
use_facet returns a reference to the corresponding facet contained
in the locale argument. You specify the facet type be
explicitly providing the template parameter (See the example below).
If that facet is not present then use_facet throws
bad_cast. Otherwise, the reference will remain valid for as
long as any copy of the locale exists.
Note that if your compiler cannot overload function templates on
return type then you'll need to use an alternate use_facet
template. The alternate template takes an additional
argument that's a pointer to the type of facet you want to
extract from the locale. The declaration looks like this:
template <class Facet> const Facet& use_facet(const locale&,
Facet*);
The example below shows the use of both variations of use_facet.
EXAMPLE
//
// usefacet.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
// Get a ctype facet
const ctype<char>& ct =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<ctype<char> >(loc);
#else
use_facet(loc,(ctype<char>*)0);
#endif
cout << 'a' << ct.toupper('c') << endl;
return 0;
}
SEE ALSO
locale, facets, has_facet
