# <string>

<head><title>&lt;string&gt;</title></head>

# `<string>`

* * *

**`basic_string· char_traits· char_traits<char>· char_traits<wchar_t>· getline· operator+· operator!=· operator==· operator<· operator<<· operator<=· operator>· operator>=· operator>>· string· swap· wstring`**

* * *

Include the standard header **`<string>`**
to define the
[container](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cont.html#Containers)
template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string) and various
supporting templates.

    namespace std {
    template<class Elem>
        class char_traits;
    template<>
        class char_traits<char>;
    template<>
        class char_traits<wchar_t>;
    template<class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_string;
    typedef basic_string<char> string;
    typedef basic_string<wchar_t> wstring;
    
            // TEMPLATE FUNCTIONS
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const basic_string<Elem, Tr, Alloc>& left,
            Elem right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            Elem left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator==(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator==(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator==(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator!=(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator!=(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator!=(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator<(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator<(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator<(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator>(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator>(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator>(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator<=(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator<=(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator<=(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator>=(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator>=(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator>=(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        void swap(
            basic_string<Elem, Tr, Alloc>& left,
            basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        basic_ostream<Elem>& operator<<(
            basic_ostream<Elem>& ostr,
            const basic_string<Elem, Tr, Alloc>& str);
    template<class Elem, class Tr, class Alloc>
        basic_istream<Elem>& operator>>(
            basic_istream<Elem>& istr,
            basic_string<Elem, Tr, Alloc>& str);
    template<class Elem, class Tr, class Alloc>
        basic_istream<Elem, Tr>& getline(
            basic_istream<Elem, Tr>& istr,
            basic_string<Elem, Tr, Alloc>& str);
     template<class Elem, class Tr, class Alloc>
        basic_istream<Elem, Tr>& getline(
            basic_istream<Elem, Tr>& istr,
            basic_string<Elem, Tr, Alloc>& str,
            Elem delim);
    }  // namespace stdCopy to clipboard

## `basic_string`

* * *

**`basic_string· allocator_type· append· assign· at· begin· c_str· capacity· clear· compare· const_iterator· const_pointer· const_reference· const_reverse_iterator· copy· data· difference_type· empty· end· erase· find· find_first_not_of· find_first_of· find_last_not_of· find_last_of· get_allocator· insert· iterator· length· max_size· npos· operator+=· operator=· operator[]· pointer· push_back· rbegin· reference· rend· replace· reserve· resize· reverse_iterator· rfind· size· size_type· substr· swap· traits_type· value_type`**

* * *

    template<class Elem,
        class Tr = char_traits<Elem>,
        class Alloc = allocator<Elem> >
        class basic_string {
    public:
        typedef Tr traits_type;
        typedef Alloc allocator_type;
        typedef T0 iterator;
        typedef T1 const_iterator;
        typedef T2 size_type;
        typedef T3 difference_type;
        typedef reverse_iterator<const_iterator>
            const_reverse_iterator;
        typedef reverse_iterator<iterator>
            reverse_iterator;
        typedef typename allocator_type::pointer
            pointer;
        typedef typename allocator_type::const_pointer
            const_pointer;
        typedef typename allocator_type::reference
            reference;
        typedef typename allocator_type::const_reference
            const_reference;
        typedef typename allocator_type::value_type
            value_type;
    
        static const size_type npos = -1;
    
        basic_string();
        explicit basic_string(const allocator_type& al);
        basic_string(const basic_string& right);
        basic_string(const basic_string& right, size_type roff,
            size_type count = npos);
        basic_string(const basic_string& right, size_type roff,
            size_type count, const allocator_type& al);
        basic_string(const value_type *ptr, size_type count);
        basic_string(const value_type *ptr, size_type count,
            const allocator_type& al);
        basic_string(const value_type *ptr);
        basic_string(const value_type *ptr,
            const allocator_type& al);
        basic_string(size_type count, value_type ch);
        basic_string(size_type count, value_type ch,
            const allocator_type& al);
        template <class InIt>
            basic_string(InIt first, InIt last);
        template <class InIt>
            basic_string(InIt first, InIt last,
                const allocator_type& al);
    
        allocator_type get_allocator() const;
    
        basic_string& operator=(const basic_string& right);
        basic_string& operator=(const value_type *ptr);
        basic_string& operator=(value_type ch);
    
        iterator begin();
        const_iterator begin() const;
        iterator end();
        const_iterator end() const;
        reverse_iterator rbegin();
        const_reverse_iterator rbegin() const;
        reverse_iterator rend();
        const_reverse_iterator rend() const;
    
        const_reference at(size_type off) const;
        reference at(size_type off);
        const_reference operator[](size_type off) const;
        reference operator[](size_type off);
    
        const value_type *c_str() const;
        const value_type *data() const;
    
        size_type length() const;
        size_type size() const;
        size_type max_size() const;
        void resize(size_type newsize, value_type ch = value_type());
        size_type capacity() const;
        void reserve(size_type count = 0);
        bool empty() const;
    
        basic_string& operator+=(const basic_string& right);
        basic_string& operator+=(const value_type *ptr);
        basic_string& operator+=(value_type ch);
    
        void push_back(value_type ch);Copy to clipboard

        basic_string& append(const basic_string& right);
        basic_string& append(const basic_string& right,
            size_type roff, size_type count);
        basic_string& append(const value_type *ptr,
            size_type count);
        basic_string& append(const value_type *ptr);
        basic_string& append(size_type count, value_type ch);
        template<class InIt>
            basic_string& append(InIt first, InIt last);
    
        basic_string& assign(const basic_string& right);
        basic_string& assign(const basic_string& right,
            size_type roff, size_type count);
        basic_string& assign(const value_type *ptr,
            size_type count);
        basic_string& assign(const value_type *ptr);
        basic_string& assign(size_type count, value_type ch);
        template<class InIt>
            basic_string& assign(InIt first, InIt last);
    
        basic_string& insert(size_type off,
            const basic_string& right);
        basic_string& insert(size_type off,
            const basic_string& right, size_type roff,
                size_type count);
        basic_string& insert(size_type off,
            const value_type *ptr, size_type count);
        basic_string& insert(size_type off,
            const value_type *ptr);
        basic_string& insert(size_type off,
            size_type count, value_type ch);
        iterator insert(iterator where,
            value_type ch = value_type());
        void insert(iterator where, size_type count, value_type ch);
        template<class InIt>
            void insert(iterator where,
                InIt first, InIt last);
    
        basic_string& erase(size_type off = 0,
            size_type count = npos);
        iterator erase(iterator where);
        iterator erase(iterator first, iterator last);
        void clear();
    
        basic_string& replace(size_type off, size_type n0,
            const basic_string& right);
        basic_string& replace(size_type off, size_type n0,
            const basic_string& right, size_type roff,
                size_type count);
        basic_string& replace(size_type off, size_type n0,
            const value_type *ptr, size_type count);
        basic_string& replace(size_type off, size_type n0,
            const value_type *ptr);
        basic_string& replace(size_type off, size_type n0,
            size_type count, value_type ch);
        basic_string& replace(iterator first, iterator last,
            const basic_string& right);
        basic_string& replace(iterator first, iterator last,
            const value_type *ptr, size_type count);
        basic_string& replace(iterator first, iterator last,
            const value_type *ptr);
        basic_string& replace(iterator first, iterator last,
            size_type count, value_type ch);
        template<class InIt>
            basic_string&
                replace(iterator first, iterator last,
                    InIt first2, InIt last2);
    
        size_type copy(value_type *ptr, size_type count,
            size_type off = 0) const;
        void swap(basic_string& right);Copy to clipboard

        size_type find(const basic_string& right,
            size_type off = 0) const;
        size_type find(const value_type *ptr, size_type off,
            size_type count) const;
        size_type find(const value_type *ptr,
            size_type off = 0) const;
        size_type find(value_type ch, size_type off = 0) const;
    
        size_type rfind(const basic_string& right,
            size_type off = npos) const;
        size_type rfind(const value_type *ptr, size_type off,
            size_type count = npos) const;
        size_type rfind(const value_type *ptr,
            size_type off = npos) const;
        size_type rfind(value_type ch,
            size_type off = npos) const;
    
        size_type find_first_of(const basic_string& right,
            size_type off = 0) const;
        size_type find_first_of(const value_type *ptr,
            size_type off, size_type count) const;
        size_type find_first_of(const value_type *ptr,
            size_type off = 0) const;
        size_type find_first_of(value_type ch,
            size_type off = 0) const;
    
        size_type find_last_of(const basic_string& right,
            size_type off = npos) const;
        size_type find_last_of(const value_type *ptr,
            size_type off, size_type count = npos) const;
        size_type find_last_of(const value_type *ptr,
            size_type off = npos) const;
        size_type find_last_of(value_type ch,
            size_type off = npos) const;
    
        size_type find_first_not_of(const basic_string& right,
            size_type off = 0) const;
        size_type find_first_not_of(const value_type *ptr,
            size_type off, size_type count) const;
        size_type find_first_not_of(const value_type *ptr,
            size_type off = 0) const;
        size_type find_first_not_of(value_type ch,
            size_type off = 0) const;
    
        size_type find_last_not_of(const basic_string& right,
            size_type off = npos) const;
        size_type find_last_not_of(const value_type *ptr,
            size_type off, size_type count) const;
        size_type find_last_not_of(const value_type *ptr,
            size_type off = npos) const;
        size_type find_last_not_of(value_type ch,
            size_type off = npos) const;
    
        basic_string substr(size_type off = 0,
            size_type count = npos) const;
    
        int compare(const basic_string& right) const;
        int compare(size_type off, size_type n0,
            const basic_string& right) const;
        int compare(size_type off, size_type n0,
            const basic_string& right, size_type roff, size_type count) const;
        int compare(const value_type *ptr) const;
        int compare(size_type off, size_type n0,
            const value_type *ptr) const;
        int compare(size_type off, size_type n0,
            const value_type *ptr, size_type roff) const;
        };Copy to clipboard

The template class describes an object that controls a
varying-length sequence of elements of type `Elem`,
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 `Elem`
parameter to
[`basic_istream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#basic_istream) or
[`basic_ostream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#string),
for elements of type *char,* and
[`wstring`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#wstring), for elements of type
`wchar_t`.

Various important properties of the elements
in a `basic_string`
specialization are described by the class `Tr`, also known as
`traits_type`.
A class that specifies these
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) must
have the same external interface as an object of template class
[`char_traits`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#char_traits).

The object allocates and frees storage for the sequence it controls
through a stored [allocator object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator%20object)
of class `Alloc`, also known as
`allocator_type`.
Such an allocator object must have
the same external interface as an object of template class
[`allocator`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator).
(Class
[`char_traits`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#char_traits) has
no provision for alternate addressing schemes, such as might be required
to implement a
[far heap](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#far%20heap).)
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](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string) used throughout the
Standard C++ library.

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

- `ch` -- one element
with value `ch`
- `count, ch` -- a repetition of `count` elements each
with value `ch`
- `ptr` -- a null-terminated sequence
(such as a [C string](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string),
for `Elem` of type *char*) beginning at
`ptr` (which must not be a null pointer),
where the terminating element is the value
`value_type()` and is not part of
the operand sequence
- `ptr, count` -- a sequence of `count` elements
beginning at `ptr` (which must not be a null pointer)
- `right` -- the sequence specified by the
`basic_string` object `right`
- `right, roff, count` -- the substring of the
`basic_string` object `right` with up to `count`
elements (or through the end of the string, whichever comes first)
beginning at position `roff`
- `first, last` -- a sequence of elements delimited
by the iterators `first` and `last`, in the
range `[first, last)`, which *may* overlap
the sequence controlled by the string object whose member function
is being called

If a **position argument**
(such as `roff` 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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stdexcep.html#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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stdexcep.html#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 (but not require)
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**.)

### `basic_string::allocator_type`

    typedef Alloc allocator_type;Copy to clipboard

The type is a synonym for the template parameter `Alloc`.

### `basic_string::append`

    basic_string& append(const value_type *ptr);
    basic_string& append(const value_type *ptr,
        size_type count);
    basic_string& append(const basic_string& right,
        size_type roff, size_type count);
    basic_string& append(const basic_string& right);
    basic_string& append(size_type count, value_type ch);
    template<class InIt>
        basic_string& append(InIt first, InIt last);Copy to clipboard

If `InIt` is an integer type, the template member
function behaves the same as `append((size_type)first, (value_type)last)`.
Otherwise, the
member functions each append the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) to the end of the
sequence controlled by `*this`,
then return `*this`.

In this
[implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation), if a
translator does not support member template functions, the template:

    template<class InIt>
        basic_string& append(InIt first, InIt last);Copy to clipboard

is replaced by:

    basic_string& append(const_pointer first,
        const_pointer last);Copy to clipboard

### `basic_string::assign`

    basic_string& assign(const value_type *ptr);
    basic_string& assign(const value_type *ptr,
        size_type count);
    basic_string& assign(const basic_string& right,
        size_type roff, size_type count);
    basic_string& assign(const basic_string& right);
    basic_string& assign(size_type count, value_type ch);
    template<class InIt>
        basic_string& assign(InIt first, InIt last);Copy to clipboard

If `InIt` is an integer type, the template member
function behaves the same as `assign((size_type)first, (value_type)last)`.
Otherwise, the
member functions each replace
the sequence controlled by `*this` with the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence), then return `*this`.

In this
[implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation), if a
translator does not support member template functions, the template:

    template<class InIt>
        basic_string& assign(InIt first, InIt last);Copy to clipboard

is replaced by:

    basic_string& assign(const_pointer first,
        const_pointer last);Copy to clipboard

### `basic_string::at`

    const_reference at(size_type off) const;
    reference at(size_type off);Copy to clipboard

The member functions each return a reference to the element of the
controlled sequence at position `off`,
or report an [out-of-range error](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#out-of-range%20error).

### `basic_string::basic_string`

    basic_string(const value_type *ptr);
    basic_string(const value_type *ptr,
        const allocator_type& al);
    basic_string(const value_type *ptr, size_type count);
    basic_string(const value_type *ptr, size_type count,
        const allocator_type& al);
    basic_string(const basic_string& right);
    basic_string(const basic_string& right, size_type roff,
        size_type count = npos);
    basic_string(const basic_string& right, size_type roff,
        size_type count, const allocator_type& al);
    basic_string(size_type count, value_type ch);
    basic_string(size_type count, value_type ch,
        const allocator_type& al);
    basic_string();
    explicit basic_string(const allocator_type& al);
    template <class InIt>
        basic_string(InIt first, InIt last);
    template <class InIt>
        basic_string(InIt first, InIt last, const allocator_type& al);Copy to clipboard

All constructors store an
[allocator object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator%20object) and
initialize the controlled sequence. The allocator object is the argument
`al`, if present. For the copy constructor, it is
`right.get_allocator()`.
Otherwise, it is `Alloc()`.

The controlled sequence is initialized to a copy of the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. A constructor with no operand sequence specifies an
empty initial controlled sequence.
If `InIt` is an integer type in a template constructor,
the operand sequence `first, last` behaves the same as
`(size_type)first, (value_type)last`.

In this
[implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation), if a
translator does not support member template functions, the templates:

    template <class InIt>
        basic_string(InIt first, InIt last);
    template <class InIt>
        basic_string(InIt first, InIt last,
            const allocator_type& al);Copy to clipboard

are replaced by:

    basic_string(const_pointer first, const_pointer last);
    basic_string(const_pointer first, const_pointer last,
        const allocator_type& al);Copy to clipboard

### `basic_string::begin`

    const_iterator begin() const;
    iterator begin();Copy to clipboard

The member functions each return a random-access iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).

### `basic_string::c_str`

    const value_type *c_str() const;Copy to clipboard

The member function returns a pointer to a non-modifiable
[C string](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string) constructed by adding a
terminating null element
(`value_type()`) to the controlled
sequence. Calling any non-const member function for
`*this` can invalidate the pointer.

### `basic_string::capacity`

    size_type capacity() const;Copy to clipboard

The member function returns the storage currently allocated to hold
the controlled sequence, a value at least as large as
`size()`.

### `basic_string::clear`

    void clear();Copy to clipboard

The member function calls
`erase(
begin(),
end())`.

### `basic_string::compare`

    int compare(const basic_string& right) const;
    int compare(size_type off, size_type n0,
        const basic_string& right) const;
    int compare(size_type off, size_type n0,
        const basic_string& right, size_type roff, size_type count) const;
    int compare(const value_type *ptr) const;
    int compare(size_type off, size_type n0,
        const value_type *ptr) const;
    int compare(size_type off, size_type n0,
        const value_type *ptr, size_type roff) const;Copy to clipboard

The member functions each compare up to `n0` elements of the
controlled sequence beginning with position `off`, or the
entire controlled sequence if these arguments are not supplied,
to the [operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence).
Each function returns:

- a negative value if the first differing element in the controlled
sequence compares less than the corresponding element in the operand
sequence (as determined by
`traits_type::compare`), or if the
two have a common prefix but the operand sequence is longer
- zero if the two compare equal element by element and are the same
length
- a positive value otherwise

### `basic_string::const_iterator`

    typedef T1 const_iterator;Copy to clipboard

The type describes an object that can serve as a constant
random-access iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type `T1`.

### `basic_string::const_pointer`

    typedef typename allocator_type::const_pointer
        const_pointer;Copy to clipboard

The type is a synonym for `allocator_type::const_pointer`.

### `basic_string::const_reference`

    typedef typename allocator_type::const_reference
        const_reference;Copy to clipboard

The type is a synonym for `allocator_type::const_reference`.

### `basic_string::const_reverse_iterator`

    typedef reverse_iterator<const_iterator>
        const_reverse_iterator;Copy to clipboard

The type describes an object that can serve as a constant reverse
iterator for the controlled sequence.

### `basic_string::copy`

    size_type copy(value_type *ptr, size_type count,
        size_type off = 0) const;Copy to clipboard

The member function copies up to `count` elements from the
controlled sequence, beginning at position `off`, to the
array of `value_type` beginning at `ptr`. It returns the
number of elements actually copied.

### `basic_string::data`

    const value_type *data() const;Copy to clipboard

The member function returns a pointer to the first element
of the sequence (or, for an empty sequence, a non-null pointer
that cannot be dereferenced).

### `basic_string::difference_type`

    typedef T3 difference_type;Copy to clipboard

The signed integer type describes an object that can represent the
difference between the addresses of any two elements in the controlled
sequence. It is described here as a
synonym for the implementation-defined type `T3`.

### `basic_string::empty`

    bool empty() const;Copy to clipboard

The member function returns true for an empty controlled sequence.

### `basic_string::end`

    const_iterator end() const;
    iterator end();Copy to clipboard

The member functions each return a random-access iterator that points
just beyond the end of the sequence.

### `basic_string::erase`

    iterator erase(iterator first, iterator last);
    iterator erase(iterator where);
    basic_string& erase(size_type off = 0,
        size_type count = npos);Copy to clipboard

The first member function removes the elements of the controlled
sequence in the range `[first, last)`.
The second member function removes the element of the controlled
sequence pointed to by `where`.
Both return an iterator that designates the first element remaining
beyond any elements removed, or
`end()`
if no such element exists.

The third member function removes up to `count` elements of
the controlled sequence beginning at position `off`, then
returns `*this`.

### `basic_string::find`

    size_type find(value_type ch, size_type off = 0) const;
    size_type find(const value_type *ptr,
        size_type off = 0) const;
    size_type find(const value_type *ptr, size_type off,
        size_type count) const;
    size_type find(const basic_string& right,
        size_type off = 0) const;Copy to clipboard

The member functions each find the first (lowest beginning position)
subsequence in the controlled sequence, beginning on or after position
`off`, that matches the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. If it succeeds, it returns the position where the
matching subsequence begins. Otherwise, the function returns
`npos`.

### `basic_string::find_first_not_of`

    size_type find_first_not_of(value_type ch,
        size_type off = 0) const;
    size_type find_first_not_of(const value_type *ptr,
        size_type off = 0) const;
    size_type find_first_not_of(const value_type *ptr,
        size_type off, size_type count) const;
    size_type find_first_not_of(const basic_string& right,
        size_type off = 0) const;Copy to clipboard

The member functions each find the first (lowest position) element of the
controlled sequence, at or after position `off`, that
matches *none* of the elements in the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
`npos`.

### `basic_string::find_first_of`

    size_type find_first_of(value_type ch,
        size_type off = 0) const;
    size_type find_first_of(const value_type *ptr,
        size_type off = 0) const;
    size_type find_first_of(const value_type *ptr,
        size_type off, size_type count) const;
    size_type find_first_of(const basic_string& right,
        size_type off = 0) const;Copy to clipboard

The member functions each find the first (lowest position) element of the
controlled sequence, at or after position `off`, that
matches *any* of the elements in the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
`npos`.

### `basic_string::find_last_not_of`

    size_type find_last_not_of(value_type ch,
        size_type off = npos) const;
    size_type find_last_not_of(const value_type *ptr,
        size_type off = npos) const;
    size_type find_last_not_of(const value_type *ptr,
        size_type off, size_type count) const;
    size_type find_last_not_of(const basic_string& right,
        size_type off = npos) const;Copy to clipboard

The member functions each find the last (highest position) element of the
controlled sequence, at or before position `off`, that
matches *none* of the elements in the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
`npos`.

### `basic_string::find_last_of`

    size_type find_last_of(value_type ch,
        size_type off = npos) const;
    size_type find_last_of(const value_type *ptr,
        size_type off = npos) const;
    size_type find_last_of(const value_type *ptr,
        size_type off, size_type count = npos) const;
    size_type find_last_of(const basic_string& right,
        size_type off = npos) const;Copy to clipboard

The member functions each find the last (highest position) element of the
controlled sequence, at or before position `off`, that
matches *any* of the elements in the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
`npos`.

### `basic_string::get_allocator`

    allocator_type get_allocator() const;Copy to clipboard

The member function returns the stored
[allocator object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator%20object).

### `basic_string::insert`

    basic_string& insert(size_type off, const value_type *ptr);
    basic_string& insert(size_type off, const value_type *ptr,
        size_type count);
    basic_string& insert(size_type off,
        const basic_string& right);
    basic_string& insert(size_type off,
        const basic_string& right, size_type roff, size_type count);
    basic_string& insert(size_type off,
        size_type count, value_type ch);
    iterator insert(iterator where,
        value_type ch = value_type());
    template<class InIt>
        void insert(iterator where, InIt first, InIt last);
    void insert(iterator where, size_type count, value_type ch);Copy to clipboard

The member functions each insert, before position `off` or
before the element pointed to by `where` in the controlled
sequence, the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. A function that returns a value returns
`*this`.
If `InIt` is an integer type in the template member function,
the operand sequence `first, last` behaves the same as
`(size_type)first, (value_type)last`.

In this
[implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation), if a
translator does not support member template functions, the template:

    template<class InIt>
        void insert(iterator where, InIt first, InIt last);Copy to clipboard

is replaced by:

    void insert(iterator where,
        const_pointer first, const_pointer last);Copy to clipboard

### `basic_string::iterator`

    typedef T0 iterator;Copy to clipboard

The type describes an object that can serve as a random-access
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type `T0`.

### `basic_string::length`

    size_type length() const;Copy to clipboard

The member function returns the length of the controlled sequence
(same as `size()`).

### `basic_string::max_size`

    size_type max_size() const;Copy to clipboard

The member function returns the length of the longest sequence that
the object can control.

### `basic_string::npos`

    static const size_type npos = -1;Copy to clipboard

The constant is the largest representable value of type
[`size_type`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string::size_type). It is
assuredly larger than
`max_size()`, hence
it serves as either a very large value or as a special code.

### `basic_string::operator+=`

    basic_string& operator+=(value_type ch);
    basic_string& operator+=(const value_type *ptr);
    basic_string& operator+=(const basic_string& right);Copy to clipboard

The operators each append the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) to the end of the
sequence controlled by `*this`, then return `*this`.

### `basic_string::operator=`

    basic_string& operator=(value_type ch);
    basic_string& operator=(const value_type *ptr);
    basic_string& operator=(const basic_string& right);Copy to clipboard

The operators each replace the sequence controlled by `*this`
with the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence),
then return `*this`.

### `basic_string::operator[]`

    const_reference operator[](size_type off) const;
    reference operator[](size_type off);Copy to clipboard

The member functions each return a reference to the element of the
controlled sequence at position `off`. If that position is
invalid, the behavior is undefined. Note, however, that
`cstr[cstr.size()] == 0` for the first member function.

### `basic_string::pointer`

    typedef typename allocator_type::pointer
        pointer;Copy to clipboard

The type is a synonym for `allocator_type::pointer`.

### `basic_string::push_back`

    void push_back(value_type ch);Copy to clipboard

The member function effectively calls
`insert(
end(), ch)`.

### `basic_string::rbegin`

    const_reverse_iterator rbegin() const;
    reverse_iterator rbegin();Copy to clipboard

The member function returns a reverse iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.

### `basic_string::reference`

    typedef typename allocator_type::reference
        reference;Copy to clipboard

The type is a synonym for `allocator_type::reference`.

### `basic_string::rend`

    const_reverse_iterator rend() const;
    reverse_iterator rend();Copy to clipboard

The member functions each return a reverse iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, the function designates the end of the reverse sequence.

### `basic_string::replace`

    basic_string& replace(size_type off, size_type n0,
        const value_type *ptr);
    basic_string& replace(size_type off, size_type n0,
        const value_type *ptr, size_type count);
    basic_string& replace(size_type off, size_type n0,
        const basic_string& right);
    basic_string& replace(size_type off, size_type n0,
        const basic_string& right, size_type roff, size_type count);
    basic_string& replace(size_type off, size_type n0,
        size_type count, value_type ch);
    basic_string& replace(iterator first, iterator last,
        const value_type *ptr);
    basic_string& replace(iterator first, iterator last,
        const value_type *ptr, size_type count);
    basic_string& replace(iterator first, iterator last,
        const basic_string& right);
    basic_string& replace(iterator first, iterator last,
        size_type count, value_type ch);
    template<class InIt>
        basic_string&
            replace(iterator first, iterator last,
                InIt first2, InIt last2);Copy to clipboard

The member functions each replace up to `n0` elements of the
controlled sequence beginning with position `off`, or the
elements of the controlled sequence beginning with the one pointed to by
`first`, up to but not including `last`. The
replacement is the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. The function then returns
`*this`.
If `InIt` is an integer type in the template member function,
the operand sequence `first2, last2` behaves the same as
`(size_type)first2, (value_type)last2`.

In this
[implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation), if a
translator does not support member template functions, the template:

    template<class InIt>
        basic_string& replace(iterator first, iterator last,
            InIt first2, InIt last2);Copy to clipboard

is replaced by:

    basic_string& replace(iterator first, iterator last,
        const_pointer first2, const_pointer last2);Copy to clipboard

### `basic_string::reserve`

    void reserve(size_type count = 0);Copy to clipboard

The member function ensures that
`capacity()`
henceforth returns at least `count`.

### `basic_string::resize`

    void resize(size_type newsize, value_type ch = value_type());Copy to clipboard

The member function ensures that
`size()` henceforth
returns `newsize`. If it must make the controlled sequence longer,
it appends elements with value `ch`.
To make the controlled sequence shorter, the member function effectively calls
`erase(begin() + newsize, end())`.

### `basic_string::reverse_iterator`

    typedef reverse_iterator<iterator>
        reverse_iterator;Copy to clipboard

The type describes an object that can serve as a reverse
iterator for the controlled sequence.

### `basic_string::rfind`

    size_type rfind(value_type ch, size_type off = npos) const;
    size_type rfind(const value_type *ptr,
        size_type off = npos) const;
    size_type rfind(const value_type *ptr,
        size_type off, size_type count = npos) const;
    size_type rfind(const basic_string& right,
        size_type off = npos) const;Copy to clipboard

The member functions each find the last
(highest beginning position) subsequence in
the controlled sequence, beginning on or before position `off`,
that matches the
[operand sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#operand%20sequence) specified by the
remaining operands. If it succeeds, the function returns the position where the
matching subsequence begins. Otherwise, it returns
`npos`.

### `basic_string::size`

    size_type size() const;Copy to clipboard

The member function returns the length of the controlled sequence.

### `basic_string::size_type`

    typedef T2 size_type;Copy to clipboard

The unsigned integer type describes an object that can represent the
length of any controlled sequence. It is described here as a
synonym for the implementation-defined type `T2`.

### `basic_string::substr`

    basic_string substr(size_type off = 0,
        size_type count = npos) const;Copy to clipboard

The member function returns an object whose controlled sequence is a
copy of up to `count` elements of the controlled sequence
beginning at position `off`.

### `basic_string::swap`

    void swap(basic_string& right);Copy to clipboard

The member function swaps the controlled sequences between
`*this` and `str`. If
`get_allocator()
== right.get_allocator()`, it does so in constant time,
it throws no exceptions, and it invalidates no references, pointers,
or iterators that designate elements in the two controlled sequences.
Otherwise, it performs a number of element assignments and constructor calls
proportional to the number of elements in the two controlled sequences.

### `basic_string::traits_type`

    typedef Tr traits_type;Copy to clipboard

The type is a synonym for the template parameter `Tr`.

### `basic_string::value_type`

    typedef typename allocator_type::value_type
        value_type;Copy to clipboard

The type is a synonym for `allocator_type::value_type`.

## `char_traits`

    template<class Elem>
        class char_traits {
    public:
        typedef Elem char_type;
        typedef T1 int_type;
        typedef T2 pos_type;
        typedef T3 off_type;
        typedef T4 state_type;
        static void assign(char_type& left, const char_type& right);
        static char_type *assign(char_type *first, size_t count,
            char_type ch);
        static bool eq(const char_type& left,
            const char_type& right);
        static bool lt(const char_type& left,
            const char_type& right);
        static int compare(const char_type *first1,
            const char_type *first2, size_t count);
        static size_t length(const char_type *first);
        static char_type *copy(char_type *first1,
            const char_type *first2, size_t count);
        static char_type *move(char_type *first1,
            const char_type *first2, size_t count);
        static const char_type *find(const char_type *first,
            size_t count, const char_type& ch);
        static char_type to_char_type(const int_type& meta);
        static int_type to_int_type(const char_type& ch);
        static bool eq_int_type(const int_type& left,
            const int_type& right);
        static int_type eof();
        static int_type not_eof(const int_type& meta);
        };Copy to clipboard

The template class describes various
**character traits**
for type `Elem`.
The template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string)
as well as several iostreams template classes, including
[`basic_ios`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#basic_ios), use this information
to manipulate elements of type `Elem`.
Such an element type must not require explicit construction or
destruction. It must supply a default constructor, a copy constructor,
and an assignment operator, with the expected semantics.
A bitwise copy must have the same effect as an assignment.

Note that the C++ Standard requires **only**
the explicit specializations
`char_traits<char>` and
`char_traits<wchar_t>`.

This
[implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation), also supplies
the template version, with:

- `int_type` defined as `long`
- `eof()` defined as `(int_type)EOF`

If these choices don't meet your needs, you must supply your own
traits class.

Not all parts of the Standard C++ Library rely completely upon the member
functions of `char_traits<Elem>` to manipulate an element.
Specifically,
[formatted input functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_istream.html#formatted%20input%20functions) and
[formatted output functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#formatted%20output%20functions)
make use of the following additional operations,
also with the expected semantics:

- `operator==(Elem)` and `operator!=(Elem)`
to compare elements
- `(char)ch` to convert an element `ch`
to its corresponding single-byte character code,
or `'\0'` if no such code exists
- `(Elem)ch` to convert a `char` value `ch` to
its correponding character code of type `Elem`

None of the member functions of class `char_traits` may
throw exceptions.

### `char_traits::assign`

    static void assign(char_type& left, const char_type& right);
    static char_type *assign(char_type *first, size_t count,
        char_type ch);Copy to clipboard

The first static member function assigns `right`
to `left`. The second static member function assigns `ch`
to each element `X[N]` for `N`
in the range `[0, count)`, then returns `first`

### `char_traits::char_type`

    typedef Elem char_type;Copy to clipboard

The type is a synonym for the template parameter `Elem`.

### `char_traits::compare`

    static int compare(const char_type *first1,
        const char_type *first2, size_t count);Copy to clipboard

The static member function compares the sequence of length `count`
beginning at `first1`to the sequence of the same length beginning
at `first2`. The function returns:

- a negative value if the first differing element in `first1`
(as determined by
`eq`) compares less
than the corresponding element in `first2` (as determined by
`lt`)
- zero if the two compare equal element by element
- a positive value otherwise

### `char_traits::copy`

    static char_type *copy(char_type *first1, const char_type *first2,
        size_t count);Copy to clipboard

The static member function copies the sequence of `count`
elements beginning at `first2` to the array beginning at `first1`,
then returns `first1`. The source and destination
must not overlap.

### `char_traits::eof`

    static int_type eof();Copy to clipboard

The static member function returns a value that represents
end-of-file (such as `EOF` or
`WEOF`). If the value is also
representable as type `Elem`,
it must correspond to no *valid* value of that type.

### `char_traits::eq`

    static bool eq(const char_type& left, const char_type& right);Copy to clipboard

The static member function returns true if `left` compares
equal to `right`.

### `char_traits::eq_int_type`

    static bool eq_int_type(const int_type& left,
        const int_type& right);Copy to clipboard

The static member function returns true if
`left` compares equal to `right`.

### `char_traits::find`

    static const char_type *find(const char_type *first,
        size_t count, const char_type& ch);Copy to clipboard

The static member function determines the lowest `N`
in the range `[0, count)` for which
`eq(first[N], ch)`
is true. If successful, it returns `first + N`. Otherwise,
it returns a null pointer.

### `char_traits::int_type`

    typedef T1 int_type;Copy to clipboard

The type is (typically) an integer type `T1` that
describes an object that can represent any element of the controlled
sequence as well as the value returned by `
eof()`.

### `char_traits::length`

    static size_t length(const char_type *first);Copy to clipboard

The static member function returns the number of elements
`N` in the sequence beginning at `first`
up to but not including the element `first[N]` which
compares equal to `char_type()`.

### `char_traits::lt`

    static bool lt(const char_type& left, const char_type& right);Copy to clipboard

The static member function returns true if `left` compares
less than `right`.

### `char_traits::move`

    static char_type *move(char_type *first1, const char_type *first2,
        size_t count);Copy to clipboard

The static member function copies the sequence of `count`
elements beginning at `first2` to the array beginning at `first1`,
then returns `first1`. The source and destination may overlap.

### `char_traits::not_eof`

    static int_type not_eof(const int_type& meta);Copy to clipboard

If
`!eq_int_type(
eof(), meta)`,
the static member function returns `meta`.
Otherwise, it returns a value other than
`eof()`.

### `char_traits::off_type`

    typedef T3 off_type;Copy to clipboard

The type is a signed integer type `T3` that describes an
object that can store a byte offset involved in various stream
positioning operations. It is typically a synonym for
`streamoff`, but in any case it
has essentially the same properties as that type.

### `char_traits::pos_type`

    typedef T2 pos_type;Copy to clipboard

The type is an opaque type `T2` that describes an object
that can store all the information needed to restore an arbitrary
[file-position indicator](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_file.html#file-position%20indicator)
within a stream. It is typically a synonym for
`streampos`, but in any case it
has essentially the same properties as that type.

### `char_traits::state_type`

    typedef T4 state_type;Copy to clipboard

The type is an opaque type `T4` that describes an object
that can represent a
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_charset.html#conversion%20state). It is
typically a synonym for
`mbstate_t`, but in any
case it has essentially the same properties as that type.

### `char_traits::to_char_type`

    static char_type to_char_type(const int_type& meta);Copy to clipboard

The static member function returns `meta` represented as
type `Elem`. A value of `meta` that cannot be so
represented yields an unspecified result.

### `char_traits::to_int_type`

    static int_type to_int_type(const char_type& ch);Copy to clipboard

The static member function returns `ch` represented as
type `int_type`. It must be possible to convert any value `ch` of type
`Elem` to `int_type` (by evaluating
`meta = to_int_type(ch)`)
then back to `Elem` (by evaluating
`ch = to_char_type(meta)`)
and obtain a value that compares equal to `ch`.

## `char_traits<char>`

    template<>
        class char_traits<char>;Copy to clipboard

The class is an explicit specialization of template class
[`char_traits`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#char_traits)
for elements of type *char,* (so that it
can take advantage of library functions that manipulate objects of this
type).

## `char_traits<wchar_t>`

    template<>
        class char_traits<wchar_t>;Copy to clipboard

The class is an explicit specialization of template class
[`char_traits`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#char_traits)
for elements of type `wchar_t` (so
that it can take advantage of library functions that manipulate objects
of this type).

## `getline`

    template<class Elem, class Tr, class Alloc>
        basic_istream<Elem, Tr>& getline(
            basic_istream<Elem, Tr>& istr,
            basic_string<Elem, Tr, Alloc>& str);
    template<class Elem, class Tr, class Alloc>
        basic_istream<Elem, Tr>& getline(
            basic_istream<Elem, Tr>& istr,
            basic_string<Elem, Tr, Alloc>& str,
            Elem delim);Copy to clipboard

The first function returns `getline(istr, str, istr.widen('\n'))`.

The second function replaces the sequence controlled by
`str` with a sequence of elements extracted from the stream
`istr`. In order of testing, extraction stops:

1. at end of file
2. after the function extracts an element that compares equal to
`delim`, in which case the element is neither put back nor
appended to the controlled sequence
3. after the function extracts
`str.max_size()`
elements, in which case the function calls
`setstate(ios_base::failbit)`.

If the function extracts no elements, it calls
`setstate(failbit)`.
In any case, it returns `istr`.

## `operator+`

    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const basic_string<Elem, Tr, Alloc>& left,
            Elem right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        basic_string<Elem, Tr, Alloc> operator+(
            Elem left,
            const basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The functions each overload `operator+` to
concatenate two objects of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string).
All effectively return `basic_string<Elem, Tr,
Alloc>(left).append(right)`.

## `operator!=`

    template<class Elem, class Tr, class Alloc>
        bool operator!=(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator!=(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator!=(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The template functions each overload `operator!=` to compare
two objects of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string). All effectively
return `basic_string<Elem, Tr,
Alloc>(left).compare(right) != 0`.

## `operator==`

    template<class Elem, class Tr, class Alloc>
        bool operator==(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator==(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator==(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The template functions each overload `operator==` to compare
two objects of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string). All effectively
return `basic_string<Elem, Tr,
Alloc>(left).compare(right) == 0`.

## `operator<`

    template<class Elem, class Tr, class Alloc>
        bool operator<(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator<(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator<(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The template functions each overload `operator<` to
compare two objects of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string). All effectively
return `basic_string<Elem, Tr,
Alloc>(left).compare(right)
< 0`.

## `operator<<`

    template<class Elem, class Tr, class Alloc>
        basic_ostream<Elem, Tr>& operator<<(
            basic_ostream<Elem, Tr>& ostr,
            const basic_string<Elem, Tr, Alloc>& str);Copy to clipboard

The template function overloads `operator<<` to
insert an object `str` of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string) into the stream
`ostr` The function effectively returns
`ostr.write(
str.c_str(),
str.size())`.

## `operator<=`

    template<class Elem, class Tr, class Alloc>
        bool operator<=(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator<=(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator<=(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The template functions each overload `operator<=` to
compare two objects of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string). All effectively
return `basic_string<Elem, Tr,
Alloc>(left).compare(right)
<= 0`.

## `operator>`

    template<class Elem, class Tr, class Alloc>
        bool operator>(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator>(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator>(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The template functions each overload `operator>` to
compare two objects of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string). All effectively
return `basic_string<Elem, Tr,
Alloc>(left).compare(right)
> 0`.

## `operator>=`

    template<class Elem, class Tr, class Alloc>
        bool operator>=(
            const basic_string<Elem, Tr, Alloc>& left,
            const basic_string<Elem, Tr, Alloc>& right);
    template<class Elem, class Tr, class Alloc>
        bool operator>=(
            const basic_string<Elem, Tr, Alloc>& left,
            const Elem *right);
    template<class Elem, class Tr, class Alloc>
        bool operator>=(
            const Elem *left,
            const basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The template functions each overload `operator>=` to
compare two objects of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string). All effectively
return `basic_string<Elem, Tr,
Alloc>(left).compare(right)
>= 0`.

## `operator>>`

    template<class Elem, class Tr, class Alloc>
        basic_istream<Elem, Tr>& operator>>(
            basic_istream<Elem, Tr>& istr,
            basic_string<Elem, Tr, Alloc>& str);Copy to clipboard

The template function overloads `operator>>` to
replace the sequence controlled by `str` with a sequence of
elements extracted from the stream `istr`. Extraction stops:

- at end of file
- after the function extracts
`istr.width()`
elements, if that value is nonzero
- after the function extracts
`istr.max_size()`
elements
- after the function extracts an element `ch` for which
`use_facet<
ctype<Elem> >(
getloc()).
is(
ctype<Elem>::space, ch)`
is true, in which case the character is put back

If the function extracts no elements, it calls
`setstate(ios_base::failbit)`.
In any case, it calls `istr.width(0)` and
returns `*this`.

## `string`

    typedef basic_string<char> string;Copy to clipboard

The type describes a specialization of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string) specialized for
elements of type *char.*

## `swap`

    template<class Tr, class Alloc>
        void swap(
            basic_string<Elem, Tr, Alloc>& left,
            basic_string<Elem, Tr, Alloc>& right);Copy to clipboard

The template function executes
`left.swap(right)`.

## `wstring`

    typedef basic_string<wchar_t> wstring;Copy to clipboard

The type describes a specialization of template class
[`basic_string`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#basic_string) for
elements of type `wchar_t`.

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<string.h></string.h> Next Topic

<strstream></strstream>