Several library components, including strings, need to perform
operations on characters. A Character Traits class is similar to
a function object: it encapsulates some information about a
particular character type, and some operations on that type.
Note that every member of a Character Traits class is static.
There is never any need to create a Character Traits object, and, in
fact, there is no guarantee that creating such objects is possible.
Refinement of
Character Traits is not a refinement of any other concept.
Associated types
Value type
X::char_type
The character type described by this Character Traits type.
Int type
X::int_type
A type that is capable of representing every valid value of type
char_type, and, additionally an end-of-file value. For char,
for example, the int type may be int, and for wchar_t it may
be wint_t.
Position type
X::pos_type
A type that can represent the position of a character of type
char_type within a file. This type is usually streampos.
Offset type
X::off_type
An integer type that can represent the difference between two
pos_type values. This type is usually streamoff.
State type
X::state_type
A type that can represent a state in a multibyte encoding
scheme. This type, if used at all, is usually mbstate_t.
Notation
X
A type that is a model of Character Traits.
c, c1, c2
A value of X's value type, X::char_type.
e, e1, e2
A value of X's int type, X::int_type.
n
A value of type size_t.
p, p1, p2
A non-null pointer of type const X::char_type*.
s
A non-null pointer of type X::char_type*.
Valid Expressions
Name
Expression
Type requirements
Return type
Character assignment
X::assign(c1, c2)
c1 is a modifiable lvalue.
void
Character equality
X::eq(c1, c2)
bool
Character comparison
X::lt(c1, c2)
bool
Range comparison
X::compare(p1, p2, n)
int
Length
X::length(p)
size_t
Find
X::find(p, n, c)
const X::char_type*
Move
X::move(s, p, n)
X::char_type*
Copy
X::copy(s, p, n)
X::char_type*
Range assignment
X::assign(s, n, c)
X::char_type*
EOF value
X::eof()
X::int_type
Not EOF
X::not_eof(e)
X::int_type
Convert to value type
X::to_char_type(e)
X::char_type
Convert to int type
X::to_int_type(c)
X::int_type
Equal int type values
X::eq_int_type(e1, e2)
bool
Expression semantics
Name
Expression
Precondition
Semantics
Postcondition
Character assignment
X::assign(c1, c2)
Performs the assignment c1 = c2
X::eq(c1, c2) is true.
Character equality
X::eq(c1, c2)
Returns true if and only if c1 and c2 are equal.
Character comparison
X::lt(c1, c2)
Returns true if and only if c1 is less than c2. Note that
for any two value values c1 and c2, exactly one of
X::lt(c1, c2), X::lt(c2, c1), and X::eq(c1, c2) should be
true.
Range comparison
X::compare(p1, p2, n)
[p1, p1+n) and [p2, p2+n) are valid ranges.
Generalization of strncmp. Returns 0 if every element
in [p1, p1+n) is equal to the corresponding element
in [p2, p2+n), a negative value if there exists an element
in [p1, p1+n) less than the corresponding element in [p2, p2+n)
and all previous elements are equal, and a positive value
if there exists an element in [p1, p1+n) greater than the
corresponding element in [p2, p2+n) and all previous elements
are equal.
Length
X::length(p)
Generalization of strlen.
Returns the smallest non-negative number n such that
X::eq(p+n, X::char_type()) is true. Behavior is undefined
if no such n exists.
Find
X::find(p, n, c)
[p, p+n) is a valid range.
Generalization of strchr. Returns the first pointer q
in [p, p+n) such that X::eq(*q, c) is true. Returns a
null pointer if no such pointer exists. (Note that this method
for indicating a failed search differs from that is
find.)
Move
X::move(s, p, n)
[p, p+n) and [s, s+n) are valid ranges (possibly overlapping).
Generalization of memmove. Copies values from the range
[p, p+n) to the range [s, s+n), and returns s.
Copy
X::copy(s, p, n)
[p, p+n) and [s, s+n) are valid ranges which do not overlap.
Generalization of memcpy. Copies values from the range
[p, p+n) to the range [s, s+n), and returns s.
Range assignment
X::assign(s, n, c)
[s, s+n) is a valid range.
Generalization of memset. Assigns the value c to each pointer
in the range [s, s+n), and returns s.
EOF value
X::eof()
Returns a value that can represent EOF.
X::eof() is distinct from every valid value of type
X::char_type. That is, there exists no value c
such that X::eq_int_type(X::to_int_type(c), X::eof()) is true.
Not EOF
X::not_eof(e)
Returns e if e represents a valid char_type value, and some
non-EOF value if e is X::eof().
Convert to value type
X::to_char_type(e)
Converts e to X's int type. If e is a representation of some
char_type value then it returns that value; if e is X::eof()
then the return value is unspecified.
Convert to int type
X::to_int_type(c)
Converts c to X's int type.
X::to_char_type(X::to_int_type(c)) is a null operation.
Equal int type values
X::eq_int_type(e1, e2)
Compares two int type values. If there exist values of type
X::char_type such that e1 is X::to_int_type(c1)) and
e2 is X::to_int_type(c2)), then X::eq_int_type(e1, e2) is
the same as X::eq(c1, c2). Otherwise, eq_int_type returns
true if e1 and e2 are both EOF and false if one of
e1 and e2 is EOF and the other is not.
Complexity guarantees
length, find, move, copy, and the range version of assign
are linear in n.