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 char 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

char_traits<char>
char_traits<wchar_t>