Silicon Graphics, Inc.

Character Traits

Category: utilities Component type: concept

Description

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.

All other operations are constant time.

Models

Notes

See also

string
[Silicon Surf] [STL Home]
Copyright © 1996 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation