Description

The template class describes an object that controls a varying-length sequence of elements of type E, also known as value_type. Such an element type must not require explicit construction or destruction, and it must be suitable for use as the E parameter to basic_istream or basic_ostream (A "plain old data structure", or POD, from C generally meets this criterion.) The Standard C++ Library provides two specializations of this template class, with the type definitions string, for elements of type char, and wstring, for elements of type wchar_t.

Various important properties of the elements in a basic_string specialization are described by the class T, also known as traits_type. A class that specifies these character traits must have the same external interface as an object of template class char_traits.

The object allocates and frees storage for the sequence it controls through a stored allocator object of class A, also known as allocator_type. Such an allocator object must have the same external interface as an object of template class allocator. (Class char_traits has no provision for alternate addressing schemes, such as might be required to implement a far heap.) Note that the stored allocator object is not copied when the container object is assigned.

The sequences controlled by an object of template class basic_string are usually called strings. These objects should not be confused, however, with the null-terminated C strings used throughout the Standard C++ Library.

Many member functions require an operand sequence of elements. You can specify such an operand sequence several ways:

• c — one element with value c
• n, c — a repetition of n elements each with value c
• s — a null-terminated sequence (such as a C string, for E of type char) beginning at s (which must not be a null pointer), where the terminating element is the value value_type() and is not part of the operand sequence
• s, n — a sequence of n elements beginning at s (which must not be a null pointer)
• str — the sequence specified by the basic_string object str
• str, pos, n — the substring of the basic_string object str with up to n elements (or through the end of the string, whichever comes first) beginning at position pos
• first, last — a sequence of elements delimited by the iterators first and last, in the range [first, last), which must not overlap the sequence controlled by the string object whose member function is being called

If a position argument (such as pos above) is beyond the end of the string on a call to a basic_string member function, the function reports an out-of-range error by throwing an object of class out_of_range.

If a function is asked to generate a sequence longer than max_size() elements, the function reports a length error by throwing an object of class length_error.

References, pointers, and iterators that designate elements of the controlled sequence can become invalid after any call to a function that alters the controlled sequence, or after the first call to the non-const member functions at, begin, end , operator[], rbegin, or rend. (The idea is to permit multiple strings to share the same representation until one string becomes a candidate for change, at which point that string makes a private copy of the representation, using a discipline called copy on write.)