ctype (3C++std) - Tru64 UNIX
Standard C++ LibraryCopyright 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
privacy and legal statement
