# 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

- `char_traits<char>`
- `char_traits<wchar_t>`

### Notes

### See also

`string`

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation