Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
ctype
- A facet that includes character classification facili-
ties.
CTYPE
The ctype<char> man page has been concatenated to this man
page because of the difficulty of entering 'man ctype<char>'
on the command line.
SYNOPSIS
#include <locale>
class ctype_base;
template <class charT> class ctype;
SPECIALIZATIONS
class ctype<char>;
DESCRIPTION
ctype<charT> is a facet that allows you to classify charac-
ters and perform simple conversions. ctype<charT> also con-
verts upper to lower and lower to upper case, and converts
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:
alnum
alpha
cntrl
digit
graph
lower
print
punct
space
upper
xdigit
The masks are passed to member functions of ctype to obtain
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
};
};
template <class charT>
class ctype : public locale::facet, public ctype_base {
public:
typedef charT char_type;
explicit ctype(size_t refs = 0);
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;
};
TYPES
char_type
Type of character the facet is instantiated on.
CONSTRUCTORS
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 hand, if refs is
1, then the object must be explicitly deleted; the locale
does not do so.
DESTRUCTORS
~ctype(); // virtual and protected
Destroy the facet.
PUBLIC MEMBER FUNCTIONS
The public members of the ctype facet include an interface
to protected members. Each public member xxx has a
corresponding virtual protected member do_xxx. All work is
delegated 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, the first five entries in the
array v would each contain the mask value:
alpha|lower|print|alnum|graph:
char a[] = "abcde";
ctype_base::mask v[12];
ctype<char>().is(a,a+5,v);
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 represen-
tation is not available, then the character is 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_byname
NAME
ctype<char>
- A specialization of the ctype facet.
SYNOPSIS
#include <locale>
class ctype<char>;
DESCRIPTION
This specialization of the ctype<charT> template includes
inline versions of ctype's member functions. The facet has
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 char* is(const char*,
const char*, mask*) const;
const char* scan_is(mask,
const char*,
const char*) const;
const char* scan_not(mask,
const char*,
const char*) const;
char toupper(char) const;
const char* toupper(char*, const char*) const;
char tolower(char) const;
const char* tolower(char*, const char*) const;
char widen(char) const;
const char* widen(const char*,
const char*, char*) const;
char narrow(char, char) const;
const char* 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 char do_toupper(char) const;
virtual const char* do_toupper(char*,
const char*) const;
virtual char do_tolower(char) const;
virtual const char* do_tolower(char*,
const char*) const;
};
TYPES
char_type
Type of character the facet is instantiated on.
CONSTRUCTORS
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:
o 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 is used for character clas-
sification.
o If tbl is non zero, and del is true, then the tbl
array is deleted by the destructor, so the calling
program need not concern itself with the lifetime of
the table.
o 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
hand, if refs is 1, then the object must be expli-
citly deleted; the locale does not do so.
DESTRUCTORS
~ctype(); // virtual and protected
Destroy the facet. If the constructor was called with a
non-zero tbl argument and a true del argument, then the
array supplied by the tbl argument is 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 func-
tionality, 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, char c) const;
Determines if the character c has the classification
indicated by the mask m. Returns table()[(unsigned
char)c] and m.
const char*
is(const char* low,
const char* 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, the first five elements of v
would contain: alpha|lower|print|xdigit|graph}:
char a[] = "abcde";
ctype_base::mask v[12];
ctype<char>().do_is(a,a+5,v);
Returns high.
char
narrow(char c, char dfault) const;
Returns c.
const char*
narrow(const char* low, const char*, char dfault,
char* to) const;
Performs ::memcpy(to,low,high-low). Returns high.
const char*
scan_is(mask m, const char*, const char* 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 char*
scan_not(mask m, const char* low, const char* 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().
char
tolower(char c) const;
const char*
tolower(char* low, const char* high) const;
Returns do_tolower(c) or do_tolower(low,high).
char
toupper(char) const;
const char*
toupper(char* low, const char* high) const;
Returns do_toupper(c) or do_toupper(low,high).
char
widen(char c) const;
Returns c.
const char*
widen(const char* low, const char* high, char* 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 char
do_tolower(char) const;
Returns the lower case representation of c, if such
exists. Otherwise returns c.
virtual const char*
do_tolower(char* low, const char* 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 char
do_toupper(char c) const;
Returns the upper case representation of c, if such
exists. Otherwise returns c.
virtual const char*
do_toupper(char* low, const char* 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_byname