Warning: main(/www/www/htdocs/style/globals.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/dinkum_en/cpp/string2.html on line 1

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/globals.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/dinkum_en/cpp/string2.html on line 1

Warning: main(/www/www/htdocs/style/header.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/dinkum_en/cpp/string2.html on line 4

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/header.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/dinkum_en/cpp/string2.html on line 4

`<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 template class 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);
    };

`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);
    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);
    void push_back(value_type ch);
    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);

    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);

    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 off) const;
    allocator_type get_allocator() const;
    };

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 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 Tr, 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 Alloc, 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:

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, 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.

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.)

`basic_string::allocator_type`

typedef Alloc allocator_type;

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);

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 to the end of the sequence controlled by *this, then return *this.

In this implementation, if a translator does not support member template functions, the template:

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

is replaced by:

basic_string& append(const_pointer first,
    const_pointer last);

`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);

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, then return *this.

In this implementation, if a translator does not support member template functions, the template:

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

is replaced by:

basic_string& assign(const_pointer first,
    const_pointer last);

`basic_string::at`

const_reference at(size_type off) const;
reference at(size_type off);

The member functions each return a reference to the element of the controlled sequence at position off, or report an out-of-range error.

`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);

All constructors store an allocator object 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 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, 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);

are replaced by:

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

`basic_string::begin`

const_iterator begin() const;
iterator begin();

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;

The member function returns a pointer to a non-modifiable C string 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;

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();

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 off) const;

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. 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;

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;

The type is a synonym for allocator_type::const_pointer.

`basic_string::const_reference`

typedef typename allocator_type::const_reference
    const_reference;

The type is a synonym for allocator_type::const_reference.

`basic_string::const_reverse_iterator`

typedef reverse_iterator<const_iterator>
    const_reverse_iterator;

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;

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;

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;

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;

The member function returns true for an empty controlled sequence.

`basic_string::end`

const_iterator end() const;
iterator end();

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);

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;

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

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

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

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

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

The member function returns the stored allocator object.

`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);

The member functions each insert, before position off or before the element pointed to by where in the controlled sequence, the operand sequence 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, if a translator does not support member template functions, the template:

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

is replaced by:

void insert(iterator where,
    const_pointer first, const_pointer last);

`basic_string::iterator`

typedef T0 iterator;

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;

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

`basic_string::max_size`

size_type max_size() const;

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

`basic_string::npos`

static const size_type npos = -1;

The constant is the largest representable value of type 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);

The operators each append the operand sequence 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);

The operators each replace the sequence controlled by *this with the operand sequence, then return *this.

`basic_string::operator[]`

const_reference operator[](size_type off) const;
reference operator[](size_type off);

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;

The type is a synonym for allocator_type::pointer.

`basic_string::push_back`

void push_back(value_type ch);

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

`basic_string::rbegin`

const_reverse_iterator rbegin() const;
reverse_iterator rbegin();

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;

The type is a synonym for allocator_type::reference.

`basic_string::rend`

const_reverse_iterator rend() const;
reverse_iterator rend();

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);

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 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, 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);

is replaced by:

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

`basic_string::reserve`

void reserve(size_type count = 0);

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

`basic_string::resize`

void resize(size_type newsize, value_type ch = value_type());

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;

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;

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

The member function returns the length of the controlled sequence.

`basic_string::size_type`

typedef T2 size_type;

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;

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);

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;

The type is a synonym for the template parameter Tr.

`basic_string::value_type`

typedef typename allocator_type::value_type
    value_type;

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);
    };

The template class describes various character traits for type Elem. The template class basic_string as well as several iostreams template classes, including 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.

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 and formatted output functions 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);

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).

`char_traits::char_type`

typedef Elem char_type;

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);

The static member function compares the sequence of length count beginning at first1to 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);

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();

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);

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);

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);

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;

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);

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);

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);

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);

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;

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;

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

The type is an opaque type T4 that describes an object that can represent a conversion state. 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);

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);

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

The class is an explicit specialization of template class 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>;

The class is an explicit specialization of template class 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);

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:

at end of file
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
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);

The functions each overload operator+ to concatenate two objects of template class 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);

The template functions each overload operator!= to compare two objects of template class 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);

The template functions each overload operator== to compare two objects of template class 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);

The template functions each overload operator< to compare two objects of template class 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);

The template function overloads operator<< to insert an object str of template class 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);

The template functions each overload operator<= to compare two objects of template class 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);

The template functions each overload operator> to compare two objects of template class 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);

The template functions each overload operator>= to compare two objects of template class 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);

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;

The type describes a specialization of template class 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);

The template function executes left.swap(right).

`wstring`

typedef basic_string<wchar_t> wstring;

The type describes a specialization of template class basic_string for elements of type wchar_t.

See also the Table of Contents and the Index.

Warning: main(/www/www/htdocs/style/footer.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/dinkum_en/cpp/string2.html on line 1801

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/footer.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/dinkum_en/cpp/string2.html on line 1801