The tt(std::string) class offers many member function as well as additional
non-member functions that should be considered part of the string class.
All these functions are listed below in alphabetic order.

The symbolic value tt(string::npos) is defined by the string class. It
represents `index-not-found' when returned by member functions returning
string offset positions. Example: when calling `tt(object.find('x'))' (see
below) on a string object not containing the character tt('x'), tt(npos)
is returned, as the requested position does not exist.

The final 0-byte used in bf(C) strings to indicate the end of an NTBS is
em(not) considered part of a bf(C++) string, and so the member function will
return tt(npos), rather than tt(length()) when looking for 0 in a string
object containing the characters of a bf(C) string.

Here are the standard functions that operate on objects of the class
string. When a parameter of tt(size_t) is mentioned it may be interpreted as a
parameter of type tt(string::size_type), but without defining a default
argument value. The type tt(size_type) should be read as
tt(string::size_type). With tt(size_type) the default argument values
mentioned in section ref(STRINGOVERVIEW) apply. All quoted functions are
member functions of the class tt(std::string), except where indicated
otherwise.
    itemization(
    ithtq(at)(char &at(size_t opos))
       (a reference to the character at the indicated position is
        returned. When called with tt(string const) objects a tt(char const &)
        is returned. The member function performs range-checking, raising an
        exception (that by default aborts the program) if an invalid index is
        passed.)
    ithtq(append)
        (string &append(InputIterator begin, InputIterator end))
        (the characters in the range defined by tt(begin) and tt(end) are
        appended to the current string object.)
    ittq(string &append(string const &argument, size_type apos,
        size_type an))
        (tt(argument) (or a substring) is appended to the current string
        object.)
    ittq(string &append(char const *argument, size_type an))
       (the first tt(an) characters of tt(argument) are appended to the
        string object.)
    ittq(string &append(size_type n, char ch))
       (tt(n) characters tt(ch) are appended to the current string object.)
    ithtq(assign)(string &assign(string const &argument, size_type
        apos, size_type an))
       (tt(argument) (or a substring) is assigned to the string object.
        If tt(argument) is of type tt(char const *) and one additional
        argument is provided the second argument is interpreted as a value
        initializing tt(an), using 0 to initialize tt(apos).)
    ittq(string &assign(size_type n, char ch))
       (tt(n) characters tt(ch) are assigned to the current string object.)
    ithtq(back)(char &back())
       (returns a reference to the last tt(char) stored inside the string
        object. The result is undefined for empty strings.)
    ithtq(begin)(string::iterator begin())
       (an iterator referring to the first character of the current string
        object is returned. With tt(const) string objects a tt(const_iterator)
        is returned.)
    ithtq(capacity)(size_type capacity() const)
       (the number of characters that can currently be stored in the string
        object without needing to resize it is returned.)
    ithtq(cbegin)(string::const_iterator cbegin())
       (a tt(const_iterator) referring to the first character of the current
        string object is returned.)
    ithtq(cend)(string::const_iterator cend())
       (a tt(const_iterator) referring to the end of the current
        string object is returned.)
    ithtq(compare)(int compare(string const &argument) const)
       (the text stored in the current string object and the text stored in
        tt(argument) is compared using a lexicographical comparison using the
        ASCII character collating sequence. zero is returned if the two
        strings have identical contents, a negative value is returned if the
        text in the current object should be ordered em(before) the text in
        tt(argument); a positive value is returned if the text in the current
        object should be ordered em(beyond) the text in tt(argument).)
    ittq(int compare(size_t opos, size_t on, string const &argument) const)
       (a substring of the text stored in the current string object is
        compared to the text stored in tt(argument). At most tt(on) characters
        starting at offset tt(opos) are compared to the text in tt(argument).)
    ittq(int compare(size_t opos, size_t on, string const &argument,
            size_type apos, size_type an))
       (a substring of the text stored in the current string object is
        compared to a substring of the text stored in tt(argument). At most
        tt(on) characters of the current string object, starting at offset
        tt(opos), are compared to at most tt(an) characters of tt(argument),
        starting at offset tt(apos). In this case tt(argument) em(must) be a
        string object.)
    ittq(int compare(size_t opos, size_t on, char const *argument, size_t an))
       (a substring of the text stored in the current string object is
        compared to a substring of the text stored in tt(argument). At most
        tt(on) characters of the current string object starting at offset
        tt(opos) are compared to at most tt(an) characters of
        tt(argument). tt(Argument) must have at least tt(an) characters. The
        characters may have arbitrary values: 0-valued characters have no
        special meanings.)
    ithtq(copy)(size_t copy(char *argument, size_t on, size_type opos) const)
       (the contents of the current string object are (partially) copied into
        tt(argument). The actual number of characters copied is returned.  The
        second argument, specifying the number of characters to copy, from the
        current string object is required. No 0-valued character is appended
        to the copied string but can be appended to the copied text using an
        idiom like the following: 
       verb(
    argument[object.copy(argument, string::npos)] = 0;
        )
       Of course, the programmer should make sure that tt(argument)'s size is
        large enough to accommodate the additional 0-byte.)
    ithtq(crbegin)(string::const_reverse_iterator crbegin())
       (a tt(const_reverse_iterator) referring to the last character of the
        current string object is returned.)
    ithtq(crend)(string::const_reverse_iterator crend())
       (a tt(const_reverse_iterator) referring to the begin of the current
        string object is returned.)
    ithtq(c_str)(char const *c_str() const)
       (the contents of the current string object as an NTBS.)
    ithtq(data)(char const *data() const)
       (the raw contents of the current string object are returned. Since this
        member does not return an NTBS (as
        tt(c_str) does), it can be used to retrieve any kind of information
        stored inside the current string object including, e.g., series of
        0-bytes:
       verb(
    string s(2, 0);
    cout << static_cast<int>(s.data()[1]) << '\n';
        )
        )
    ithtq(empty)(bool empty() const)
       (tt(true) is returned if the current string object contains no data.)
    ithtq(end)(string::iterator end())
       (an iterator referring to the position just beyond the last character
        of the current string object is returned. With tt(const) string
        objects a tt(const_iterator) is returned.)
    ithtq(erase)(string &erase(size_type opos, size_type on))
       (a (sub)string of the information stored in the current string object
        is erased.)
    ittq(string::iterator erase(string::iterator begin, string::iterator end))
       (the parameter tt(end) is optional. If omitted the value returned by
        the current object's tt(end) member is used. The characters defined by
        the tt(begin) and tt(end) iterators are erased. The iterator tt(begin)
        is returned, which is then referring to the position immediately
        following the last erased character.)
    ithtq(find)(size_t find(string const &argument, size_type opos) const)
       (the first index in the current string object where tt(argument) is
        found is returned.)
    ittq(size_t find(char const *argument, size_type opos, size_type an) const)
       (the first index in the current string object where tt(argument) is
        found is returned. When all three arguments are specified the first
        argument em(must) be a tt(char const *).)
    ittq(size_t find(char ch, size_type opos) const)
       (the first index in the current string object where tt(ch) is found is
        returned.)
    ithtq(find_first_of)(size_t find_first_of(string const &argument,
                                               size_type opos) const)
       (the first index in the current string object where any character in
        tt(argument) is found is returned.)
    ittq(size_type find_first_of(char const *argument, size_type opos,
        size_type an) const)
       (the first index in the current string object where any character in
        tt(argument) is found is returned. If tt(opos) is provided it refers
        to the first index in the current string object where the search for
        tt(argument) should start. If omitted, the string object is scanned
        completely.  If tt(an) is provided it indicates the number of
        characters of the tt(char const *) argument that should be used in the
        search. It defines a substring starting at the beginning of
        tt(argument). If omitted, all of tt(argument)'s characters are used.)
    ittq(size_type find_first_of(char ch, size_type opos))
       (the first index in the current string object where character tt(ch) is
        found is returned.)
    ittq(size_t find_first_not_of(char ch, size_type opos) const)
       (the first index in the current string object where another
        character than tt(ch) is found is returned.)
    ithtq(find_last_of)(size_t find_last_of(string const &argument,
                                               size_type opos) const)
       (the last index in the current string object where any character in
        tt(argument) is found is returned.)
    ittq(size_type find_last_of(char const *argument, size_type opos,
            size_type an) const)
       (the last index in the current string object where any character in
        tt(argument) is found is returned. If tt(opos) is provided it refers
        to the last index in the current string object where the search for
        tt(argument) should start. If omitted, the string object is scanned
        completely.  If tt(an) is provided it indicates the number of
        characters of the tt(char const *) argument that should be used in the
        search. It defines a substring starting at the beginning of
        tt(argument). If omitted, all of tt(argument)'s characters are used.)
    ittq(size_type find_last_of(char ch, size_type opos))
       (the last index in the current string object where character tt(ch) is
        found is returned.)
    ithtq(find_last_not_of)(size_t find_last_not_of(string const &argument,
                                                size_type opos) const)
       (the last index in the current string object where any character em(not)
        appearing in tt(argument) is found is returned.)
    ithtq(front)(char &front())
       (returns a reference to the first tt(char) stored inside the string
        object. The result is undefined for empty strings.)
    ithtq(get_allocator)(allocator_type get_allocator())
       (returns the allocator of the class tt(std::string))
    ithtq(getline)(istream &std::getline(istream &istr, string &object,
            char delimiter = '\n'))
       (Note: this is em(not) a member function of the class tt(string).nl()
       A line of text is read from tt(istr). All characters until
        tt(delimiter) (or the end of the stream, whichever comes first) are
        read from tt(istr) and are stored in tt(object). If the delimiter is
        encountered it is removed from the stream, but is not stored in
        tt(object).nl()
       If the delimiter is not found, tt(istr.eof) returns tt(true) (see
        section ref(IOSTATES)). Since streams may be interpreted as tt(bool)
        values (cf. section ref(IOSTATES)) a commonly encountered idiom to
        read all lines from a stream successively into a string object
        tt(line) looks like this:
       verb(
    while (getline(istr, line))
        process(line);
        )
       The contents of the last line, whether or not it was terminated
        by a delimiter, is eventually also assigned to tt(object).)
    ithtq(insert)(string &insert(size_t opos, string const &argument,
        size_type apos, size_type an))
       (a (sub)string of tt(argument) is inserted into the current string
        object at the current string object's index position
        tt(opos). Arguments for tt(apos) and tt(an) must either both be
        provided or they must both be omitted.)
    ittq(string &insert(size_t opos, char const *argument,
                size_type an))
       (tt(argument) (of type tt(char const *)) is inserted at index tt(opos)
        into the current string object.)
    ittq(string &insert(size_t opos, size_t count, char ch))
       (tt(Count) characters tt(ch) are inserted at index tt(opos) into the
        current string object.)
    ittq(string::iterator insert(string::iterator begin, char ch))
       (the character tt(ch) is inserted at the current object's position
        referred to by tt(begin). tt(Begin) is returned.)
    ittq(string::iterator insert(string::iterator begin, size_t count,
        char ch))
       (tt(Count) characters tt(ch) are inserted at the current object's
        position referred to by tt(begin). tt(Begin) is returned.)
    ittq(string::iterator insert(string::iterator begin, InputIterator
        abegin, InputIterator aend))
       (the characters in the range defined by the tt(InputIterators abegin)
        and tt(aend) are inserted at the current object's position referred to
        by tt(begin). tt(Begin) is returned.)
    ithtq(length)(size_t length() const)
       (the number of characters stored in the current string object is
        returned.)
    ithtq(max_size)(size_t max_size() const)
       (the maximum number of characters that can be stored in the current
        string object is returned.)
    ithtq(pop_back)(void pop_back())
       (The string's last character is removed from the string object.)
    ithtq(push_back)(void push_back(char ch))
       (The character tt(ch) is appended to the string object.)
    ithtq(rbegin)(string::reverse_iterator rbegin())
       (a reverse iterator referring to the last character of the current
        string object is returned. With tt(const) string objects a
        tt(reverse_const_iterator) is returned.)
    ithtq(rend)(string::iterator rend())
       (a reverse iterator referring to the position just before the first
        character of the current string object is returned. With tt(const)
        string objects a tt(reverse_const_iterator) is returned.)
    ithtq(replace)(string &replace(size_t opos, size_t on, string const
        &argument, size_type apos, size_type an))
       (a (sub)string of characters in tt(object) are replaced by the (subset
        of) characters of tt(argument).  If tt(on) is specified as 0
        tt(argument) is inserted into tt(object) at offset tt(opos).)
    ittq(string &replace(size_t opos, size_t on, char const *argument,
        size_type an))
       (a series of characters in tt(object) are replaced by the first tt(an)
        characters of tt(char const *) argument.)
    ittq(string &replace(size_t opos, size_t on, size_type count, char ch))
       (tt(on) characters of the current string object, starting at index
        position tt(opos), are replaced by tt(count) characters tt(ch).)
    ittq(string &replace(string::iterator begin, string::iterator end,
        string const &argument))
       (the series of characters in the current string object defined by the
        iterators tt(begin) and tt(end) are replaced by tt(argument). If
        tt(argument) is a tt(char const *), an additional argument tt(an) may
        be used, specifying the number of characters of tt(argument) that are
        used in the replacement.)
    ittq(string &replace(string::iterator begin, string::iterator end,
        size_type count, char ch))
       (the series of characters in the current string object defined by the
        iterators tt(begin) and tt(end) are replaced by tt(count) characters
        having values tt(ch).)
    ittq(string &replace(string::iterator begin, string::iterator end,
        InputIterator abegin, InputIterator aend))
       (the series of characters in the current string object defined by the
        iterators tt(begin) and tt(end) are replaced by the characters in the
        range defined by the tt(InputIterators abegin) and tt(aend).)
    ithtq(reserve)(void reserve(size_t request))
       (the current string object's capacity is changed to at least
        tt(request). After calling this member, tt(capacity)'s return value
        will be at least tt(request). A request for a smaller size than the
        value returned by tt(capacity) is ignored. A
        hi(length_error)tt(std::length_error) exception is thrown if
        tt(request) exceeds the value returned by tt(max_size)
        (tt(std::length_error) is defined in the ti(stdexcept)
        header). Calling tt(reserve()) has the effect of redefining a string's
        capacity: when enlarging the capacity extra memory is allocated, but
        not immediately available to the program. This is illustrated by the
        exception thrown by the string's tt(at()) member when trying to access
        an element exceeding the string's tt(size) but not the string's
        tt(capacity).)
    ithtq(resize)(void resize(size_t size, char ch = 0))
       (the current string object is resized to
        tt(size) characters. If the string object is resized to a size larger
        than its current size the additional characters will be initialized to
        tt(ch). If it is reduced in size the characters having the highest
        indices are chopped off.)
    ithtq(rfind)(size_t rfind(string const &argument, size_type opos) const)
       (the last index in the current string object where tt(argument) is
        found is returned. Searching proceeds from the current object's offset
        tt(opos) back to its beginning.)
    ittq(size_t rfind(char const *argument, size_type opos, size_type an) const)
       (the last index in the current string object where tt(argument) is
        found is returned.  Searching proceeds from the current object's
        offset tt(opos) back to its beginning.  The parameter tt(an) specifies
        the length of the substring of tt(argument) to look for, starting at
        tt(argument)'s beginning.)
    ittq(size_t rfind(char ch, size_type opos)const)
       (the last index in the current string object where tt(ch) is found
        is returned.  Searching proceeds from the current object's offset
        tt(opos) back to its beginning.)
    ithtq(shrink_to_fit)(void shrink_to_fit())
       (optionally reduces the amount of memory allocated by a vector to its
        current size. The implementor is free to ignore or otherwise optimize
        this request. In order to guarantee a `shrink to fit' operation the
        verb(
    string(stringObject).swap(stringObject)
            ) 
        idiom can be used.)
    ithtq(size)(size_t size() const)
       (the number of characters stored in the current string object is
        returned. This member is a synonym of tt(length()).)
    ithtq(substr)(string substr(size_type opos, size_type on) const)
       (a substring of the current string object of at most tt(on) characters
        starting at index tt(opos) is returned.)
    ithtq(swap)(void swap(string &argument))
       (the contents of the current string object are swapped with the
        contents of tt(argument). For this member tt(argument) must be a
        string object and cannot be a tt(char const *).)
    )

COMMENT(
        verbinclude(-a examples/stringassign.cc)
        verbinclude(-a examples/stringcstr.cc)
        verbinclude(-a examples/stringsubscript.cc)
        verbinclude(-a examples/stringcompare.cc)
        verbinclude(-a examples/stringcompare2.cc)
        verbinclude(-a examples/stringappend.cc)
        verbinclude(-a examples/stringinsert.cc)
        verbinclude(-a examples/stringreplace.cc)
        verbinclude(-a examples/stringswap.cc)
        verbinclude(-a examples/stringerase.cc)
        verbinclude(-a examples/stringsubstr.cc)
        verbinclude(-a examples/stringfindfirst.cc)
         verbinclude(-a examples/stringsize.cc)
         verbinclude(-a examples/stringempty.cc)
END COMMENT)
