|
VMS Help CXXLSTD, IOStreams, ctype *Conan The Librarian |
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
ctype, ctype<char> - A facet that provides character classification
facilities. (The description for ctype<char>, a specialization of
ctype, follows the ctype description.)
SYNOPSIS
#include <locale>
class ctype_base;
template <class charT> class ctype;
SPECIALIZATION
class ctype<char>;
DESCRIPTION
ctype<charT> is the character classification facet. This facet
provides facilities for classifying characters and performing
simple conversions. ctype<charT> provides conversions for upper
to lower and lower to upper case. The facet also
provides conversions between charT, and char. ctype<charT>
relies on ctype_base for a set of masks that identify the
various classes of characters. These classes are:
space
print
cntrl
upper
lower
alpha
digit
punct
xdigit
alnum
graph
The masks are passed to member functions of ctype in order to obtain
verify the classifications of a character or range of characters.
INTERFACE
class ctype_base {
public:
enum mask {
space, print, cntrl, upper, lower,
alpha, digit, punct, xdigit,
alnum=alpha|digit, graph=alnum|punct
};
};
template <class charT>
class ctype : public locale::facet, public ctype_base {
public:
typedef charT char_type;
explicit ctype(size_t);
bool is(mask, charT) const;
const charT* is(const charT*,
const charT*, mask*) const;
const charT* scan_is(mask,
const charT*,
const charT*) const;
const charT* scan_not(mask,
const charT*,
const charT*) const;
charT toupper(charT) const;
const charT* toupper(charT*, const charT*) const;
charT tolower(charT) const;
const charT* tolower(charT*, const charT*) const;
charT widen(char) const;
const char* widen(const char*,
const char*, charT*) const;
char narrow(charT, char) const;
const charT* narrow(const charT*, const charT*,
char, char*) const;
static locale::id id;
protected:
~ctype(); // virtual
virtual bool do_is(mask, charT) const;
virtual const charT* do_is(const charT*,
const charT*,
mask*) const;
virtual const charT* do_scan_is(mask,
const charT*,
const charT*) const;
virtual const charT* do_scan_not(mask,
const charT*,
const charT*) const;
virtual charT do_toupper(charT) const;
virtual const charT* do_toupper(charT*,
const charT*) const;
virtual charT do_tolower(charT) const;
virtual const charT* do_tolower(charT*,
const charT*) const;
virtual charT do_widen(char) const;
virtual const char* do_widen(const char*,
const char*,
charT*) const;
virtual char do_narrow(charT, char) const;
virtual const charT* do_narrow(const charT*,
const charT*,
char, char*) const;
};
TYPE
char_type
Type of character the facet is instantiated on.
CONSTRUCTOR AND DESTRUCTOR
explicit ctype(size_t refs = 0)
Construct a ctype 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.
~ctype(); // virtual and protected
Destroy the facet.
PUBLIC MEMBER FUNCTIONS
The public members of the ctype 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 public widen function
simply calls its protected cousin do_widen.
bool
is(mask m, charT c) const;
const charT*
is(const charT* low,
const charT* high, mask* vec) const;
Returns do_is(m,c) or do_is(low,high,vec).
char
narrow(charT c, char dfault) const;
const charT*
narrow(const charT* low, const charT*, char dfault,
char* to) const;
Returns do_narrow(c,dfault) or do_narrow(low,high,dfault,to).
const charT*
scan_is(mask m, const charT*, const charT* high) const;
Returns do_scan_is(m,low,high).
const charT*
scan_not(mask m, const charT* low, const charT* high) const;
Returns do_scan_not(m,low,high).
charT
tolower(charT c) const;
const charT*
tolower(charT* low, const charT* high) const;
Returns do_tolower(c) or do_tolower(low,high).
charT
toupper(charT) const;
const charT*
toupper(charT* low, const charT* high) const;
Returns do_toupper(c) or do_toupper(low,high).
charT
widen(char c) const;
const char*
widen(const char* low, const char* high, charT* to) const;
Returns do_widen(c) or do_widen(low,high,to).
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PROTECTED MEMBER FUNCTIONS
virtual bool
do_is(mask m, charT c) const;
Returns true if c matches the classification indicated by the
mask m, where m is one of the values available from
ctype_base. For instance, the following call returns true
since 'a' is an alphabetic character:
ctype<char>().is(ctype_base::alpha,'a');
See ctype_base for a description of the masks.
virtual const charT*
do_is(const charT* low, const charT* high,
mask* vec) const;
Fills vec with every mask from ctype_base that applies to the
range of characters indicated by [low,high). See
ctype_base for a description of the masks. For instance,
after the following call v would contain {alpha, lower,
print,alnum ,graph}:
char a[] = "abcde";
ctype_base::mask v[12];
ctype<char>().is(a,a+5,v);
This function returns high.
virtual char
do_narrow(charT, char dfault) const;
Returns the appropriate char representation for c, if such
exists. Otherwise do_narrow returns dfault.
virtual const charT*
do_narrow(const charT* low, const charT* high,
char dfault, char* dest) const;
Converts each character in the range [low,high) to its char
representation, if such exists. If a char representation is
not available then the character will be converted to
dfault. Returns high.
virtual const charT*
do_scan_is(mask m, const charT* low, const charT* high) const;
Finds the first character in the range [low,high) that matches
the classification indicated by the mask m.
virtual const charT*
do_scan_not(mask m, const charT* low, const charT* high) const;
Finds the first character in the range [low,high) that does not
match the classification indicated by the mask m.
virtual charT
do_tolower(charT) const;
Returns the lower case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_tolower(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its lower case
representation, if such exists. If a lower case representation
does not exist then the character is not changed. Returns
high.
virtual charT
do_toupper(charT c) const;
Returns the upper case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_toupper(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its upper case
representation, if such exists. If an upper case representation
does not exist then the character is not changed. Returns
high.
virtual charT
do_widen(char c) const;
Returns the appropriate charT representation for c.
virtual const char*
do_widen(const char* low, const char* high,charT* dest) const;
Converts each character in the range [low,high) to its charT
representation. Returns high.
EXAMPLE
//
// ctype.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
string s1("blues Power");
// Get a reference to the ctype<char> 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
// Check the classification of the 'a' character
cout << ct.is(ctype_base::alpha,'a') << endl;
cout << ct.is(ctype_base::punct,'a') << endl;
// Scan for the first upper case character
cout << (char)*(ct.scan_is(ctype_base::upper,
s1.begin(),s1.end())) << endl;
// Convert characters to upper case
ct.toupper(s1.begin(),s1.end());
cout << s1 << endl;
return 0;
}
SEE ALSO
locale, facets, collate, ctype<char>, ctype_byname
NAME
ctype<char> - A specialization of the ctype facet.
SYNOPSIS
#include <locale>
class ctype<char>;
DESCRIPTION
This specialization of the ctype<charT> template provides inline
versions of ctype's member functions. The facet provides the same
public interface, and uses the same set of masks, as the ctype
template.
INTERFACE
template <>
class ctype<char> : public locale::facet, public ctype_base {
public:
typedef char char_type;
explicit ctype(const mask* = 0, bool = false,
size_t = 0);
bool is(mask, char) const;
const charT* is(const char*,
const char*, mask*) const;
const charT* scan_is(mask,
const char*,
const char*) const;
const charT* scan_not(mask,
const char*,
const char*) const;
charT toupper(char) const;
const charT* toupper(char*, const charT*) const;
charT tolower(char) const;
const charT* tolower(char*, const char*) const;
charT widen(char) const;
const char* widen(const char*,
const char*, char*) const;
char narrow(char, char) const;
const charT* narrow(const char*, const char*,
char, char*) const;
static locale::id id;
static const size_t table_size = 256;
protected:
const mask* table() const throw();
static const mask* classic_table() throw();
~ctype(); // virtual
virtual charT do_toupper(charT) const;
virtual const charT* do_toupper(charT*,
const charT*) const;
virtual charT do_tolower(charT) const;
virtual const charT* do_tolower(charT*,
const charT*) const;
};
TYPE
char_type
Type of character the facet is instantiated on.
CONSTRUCTORS AND DESTRUCTORS
explicit ctype(const mask* tbl = 0, bool del = false,
size_t refs = 0)
Construct a ctype facet. The three parameters set up the
following conditions:
+ The tbl argument must be either 0 or an array of at least
table_size elements. If tbl is non zero then the supplied
table will be used for character classification.
+ If tbl is non zero, and del is true then the tbl array will
be deleted by the destructor, so the calling program need
not concern itself with the lifetime of the facet.
+ If the refs argument is 0 then destruction of the object
itself 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.
~ctype(); // virtual and protected
Destroy the facet. If the constructor was called with a non-zero
tbl argumentand a true del argument, then the array supplied
by the tbl argument will be deleted
PUBLIC MEMBER FUNCTIONS
The public members of the ctype<char> facet specialization do not
all serve the same purpose as the functions in the template. In
many cases these functions implement functionality, rather than just
forwarding a call to a protected implementation function.
static const mask*
classic_table() throw();
Returns a pointer to a table_size character array that represents
the classifications of characters in the "C" locale.
bool
is(mask m, charT c) const;
Determines if the character c has the classification indicated by
the mask m. Returns table()[(unsigned char)c] & m.
const charT*
is(const charT* low,
const charT* high, mask* vec) const;
Fills vec with every mask from ctype_base that applies to the
range of characters indicated by [low,high). See
ctype_base for a description of the masks. For instance,
after the following call v would contain {alpha, lower,
print,,alnum ,graph}:
char a[] = "abcde";
ctype_base::mask v[12];
ctype<char>().do_is(a,a+5,v);
This function returns high.
char
narrow(charT c, char dfault) const;
Returns c.
const charT*
narrow(const charT* low, const charT*, char dfault,
char* to) const;
Performs ::memcpy(to,low,high-low). Returns high.
const charT*
scan_is(mask m, const charT*, const charT* high) const;
Finds the first character in the range [low,high) that matches
the classification indicated by the mask m. The
classification is matched by checking for table()[(unsigned char)
p] & m, where p is in the range [low,high). Returns the
first p that matches, or high if none do.
const charT*
scan_not(mask m, const charT* low, const charT* high) const;
Finds the first character in the range [low,high) that does not
match the classification indicated by the mask m. The
classification is matched by checking for
!(table()[(unsigned char) p] & m), where p is in the range
[low,high). Returns the first p that matches, or high if none
do.
const mask*
table() const throw();
If the tbl argument that was passed to the constructor was
non-zero, then this function returns that argument,
otherwise it returns classic_table().
charT
tolower(charT c) const;
const charT*
tolower(charT* low, const charT* high) const;
Returns do_tolower(c) or do_tolower(low,high).
charT
toupper(charT) const;
const charT*
toupper(charT* low, const charT* high) const;
Returns do_toupper(c) or do_toupper(low,high).
charT
widen(char c) const;
Returns c.
const char*
widen(const char* low, const char* high, charT* to) const;
Performs ::memcpy(to,low,high-low. Returns high.
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PROTECTED MEMBER FUNCTIONS
virtual charT
do_tolower(charT) const;
Returns the lower case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_tolower(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its lower case
representation, if such exists. If a lower case representation
does not exist then the character is not changed. Returns
high.
virtual charT
do_toupper(charT c) const;
Returns the upper case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_toupper(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its upper case
representation, if such exists. If an upper case representation
does not exist then the character is not changed. Returns
high.
SEE ALSO
locale, facets, collate, ctype<char>, ctype_byname
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
|
|