|
|
|
| |
|
| Category : utilities | | Component type: concept |
Description
Several library components, including basic_string, need to perform operations on characters. A Character Traits class is similar to a functors : 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
basic_string
|
