basic_string

  • Article

basic_string

allocator_type·append·assign·at·basic_string·begin·c_str·capacity ·char_type·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·rbegin·reference·rend·replace·reserve·resize·reverse_iterator ·rfind·size·size_type·substr·swap·traits_type·value_type 

template<class E,
    class T = char_traits<E>,
    class A = allocator<T> >
    class basic_string {
public:
    typedef T traits_type;
    typedef A allocator_type;
    typedef T::char_type char_type;
    typedef A::size_type size_type;
    typedef A::difference_type difference_type;
    typedef A::pointer pointer;
    typedef A::const_pointer const_pointer;
    typedef A::reference reference;
    typedef A::const_reference const_reference;
    typedef A::value_type value_type;
    typedef T0 iterator;
    typedef T1 const_iterator;
    typedef reverse_iterator<iterator, value_type,
        reference, pointer, difference_type>
            reverse_iterator;
    typedef reverse_iterator<const_iterator, value_type,
        const_reference, const_pointer, difference_type>
            const_reverse_iterator;
    static const size_type npos = -1;
    explicit basic_string(const A& al = A());
    basic_string(const basic_string& rhs);
    basic_string(const basic_string& rhs, size_type pos, size_type n,
        const A& al = A());
    basic_string(const E *s, size_type n, const A& al = A());
    basic_string(const E *s, const A& al = A());
    basic_string(size_type n, E c, const A& al = A());
    basic_string(const_iterator first, const_iterator last,
        const A& al = A());
    basic_string& operator=(const basic_string& rhs);
    basic_string& operator=(const E *s);
    basic_string& operator=(E c);
    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 pos) const;
    reference at(size_type pos);
    const_reference operator[](size_type pos) const;
    reference operator[](size_type pos);
    const E *c_str() const;
    const E *data() const;
    size_type length() const;
    size_type size() const;
    size_type max_size() const;
    void resize(size_type n, E c = E());
    size_type capacity() const;
    void reserve(size_type n = 0);
    bool empty() const;
    basic_string& operator+=(const basic_string& rhs);
    basic_string& operator+=(const E *s);
    basic_string& operator+=(E c);
    basic_string& append(const basic_string& str);
    basic_string& append(const basic_string& str,
        size_type pos, size_type n);
    basic_string& append(const E *s, size_type n);
    basic_string& append(const E *s);
    basic_string& append(size_type n, E c);
    basic_string& append(const_iterator first, const_iterator last);
    basic_string& assign(const basic_string& str);
    basic_string& assign(const basic_string& str,
        size_type pos, size_type n);
    basic_string& assign(const E *s, size_type n);
    basic_string& assign(const E *s);
    basic_string& assign(size_type n, E c);
    basic_string& assign(const_iterator first, const_iterator last);
    basic_string& insert(size_type p0,
        const basic_string& str);
    basic_string& insert(size_type p0,
        const basic_string& str, size_type pos, size_type n);
    basic_string& insert(size_type p0,
        const E *s, size_type n);
    basic_string& insert(size_type p0, const E *s);
    basic_string& insert(size_type p0, size_type n, E c);
    iterator insert(iterator it, E c);
    void insert(iterator it, size_type n, E c);
    void insert(iterator it,
        const_iterator first, const_iterator last);
    basic_string& erase(size_type p0 = 0, size_type n = npos);
    iterator erase(iterator it);
    iterator erase(iterator first, iterator last);
    basic_string& replace(size_type p0, size_type n0,
        const basic_string& str);
    basic_string& replace(size_type p0, size_type n0,
        const basic_string& str, size_type pos, size_type n);
    basic_string& replace(size_type p0, size_type n0,
        const E *s, size_type n);
    basic_string& replace(size_type p0, size_type n0,
        const E *s);
    basic_string& replace(size_type p0, size_type n0,
        size_type n, E c);
    basic_string& replace(iterator first0, iterator last0,
        const basic_string& str);
    basic_string& replace(iterator first0, iterator last0,
        const E *s, size_type n);
    basic_string& replace(iterator first0, iterator last0,
        const E *s);
    basic_string& replace(iterator first0, iterator last0,
        size_type n, E c);
    basic_string& replace(iterator first0, iterator last0,
        const_iterator first, const_iterator last);
    size_type copy(E *s, size_type n, size_type pos = 0) const;
    void swap(basic_string& str);
    size_type find(const basic_string& str,
        size_type pos = 0) const;
    size_type find(const E *s, size_type pos, size_type n) const;
    size_type find(const E *s, size_type pos = 0) const;
    size_type find(E c, size_type pos = 0) const;
    size_type rfind(const basic_string& str,
        size_type pos = npos) const;
    size_type rfind(const E *s, size_type pos,
        size_type n = npos) const;
    size_type rfind(const E *s, size_type pos = npos) const;
    size_type rfind(E c, size_type pos = npos) const;
    size_type find_first_of(const basic_string& str,
        size_type pos = 0) const;
    size_type find_first_of(const E *s, size_type pos,
        size_type n) const;
    size_type find_first_of(const E *s, size_type pos = 0) const;
    size_type find_first_of(E c, size_type pos = 0) const;
    size_type find_last_of(const basic_string& str,
        size_type pos = npos) const;
    size_type find_last_of(const E *s, size_type pos,
        size_type n = npos) con/t;
    size_type find_last_of(const E *s, size_type pos = npos) const;
    size_type find_last_of(E c, size_type pos = npos) const;
    size_type find_first_not_of(const basic_string& str,
        size_type pos = 0) const;
    size_type find_first_not_of(const E *s, size_type pos,
        size_type n) const;
    size_type find_first_not_of(const E *s, size_type pos = 0) const;
    size_type find_first_not_of(E c, size_type pos = 0) const;
    size_type find_last_not_of(const basic_string& str,
        size_type pos = npos) const;
    size_type find_last_not_of(const E *s, size_type pos,
         size_type n) const;
    size_type find_last_not_of(const E *s,
        size_type pos = npos) const;
    size_type find_last_not_of(E c, size_type pos = npos) const;
    basic_string substr(size_type pos = 0, size_type n = npos) const;
    int compare(const basic_string& str) const;
    int compare(size_type p0, size_type n0,
        const basic_string& str);
    int compare(size_type p0, size_type n0,
        const basic_string& str, size_type pos, size_type n);
    int compare(const E *s) const;
    int compare(size_type p0, size_type n0,
        const E *s) const;
    int compare(size_type p0, size_type n0,
        const E *s, size_type pos) const;
    A get_allocator() const;
protected:
    A allocator;
    };

The template class describes an object that controls a varying-length sequence of elements of type E. 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. 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 protected object named allocator, of class A. Such an allocator object must have the same external interface as an object of template class allocator. (Class char_traits has no provision for alternative addressing schemes, such as might be required to implement a far heap.) Note that allocator is not copied when the 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 of type E. You can specify such an operand sequence several ways:

  • c -- a sequence of 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 E(0) 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)

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.