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(clear)(void clear())
       (the string's content is erased.)
    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 content, 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(contains)(bool contains(argument) const)
       (returns tt(true) if the object contains tt(argument's) characters as a
        substring. The argument can be a tt(string), a tt(string_view) (see
        section ref(STRINGVIEW)), a tt(char) or an NTBS.)
    ithtq(copy)(size_t copy(char *argument, size_t on, size_type opos) const)
       (the content 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 content of the current string object as an NTBS.)
    ithtq(data)(char const *data() const)
       (the raw content 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(ends_with)(bool ends_with(argument) const)
       (returns tt(true) if the object's characters end with tt(argument). The
        argument can be a tt(string), a tt(string_view), a tt(char) or an
        NTBS.)
    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 is returned where
        tt(argument) is found.)
    ittq(size_t find(char const *argument, size_type opos, size_type an) const)
       (the first index in the current string object is returned where
        tt(argument) is found. 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 is returned where tt(ch)
        is found.)
    ithtq(find_first_of)(size_t find_first_of(string const &argument,
                                               size_type opos) const)
       (the first index in the current string object is returned whose
        character matches any character from tt(argument).)
    ittq(size_type find_first_of(char const *argument, size_type opos,
        size_type an) const)
       (the first index in the current string object is returned whose
        character matches any character from tt(argument). 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 completely scanned.  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 is returned whose
        character is equal to tt(ch).)
    ithtq(find_first_not_of)(size_t find_first_not_of(string const &argument,
                                               size_type opos) const)
       (the first index in the current string object is returned whose
        character does not match any character from tt(argument).)
    ittq(size_type find_first_not_of(char const *argument, size_type opos,
        size_type an) const)
       (the first index in the current string object is returned whose
        character does not match any character from tt(argument). The tt(opos)
        and tt(an) parameters are handled as with tt(find_first_of))
    ittq(size_t find_first_not_of(char ch, size_type opos) const)
       (the first index in the current string object is returned whose
        character is unequal to tt(ch).)
    ithtq(find_last_of)(size_t find_last_of(string const &argument,
                                               size_type opos) const)
       (the last index in the current string object is returned whose
        character matches any character from tt(argument).)
    ittq(size_type find_last_of(char const *argument, size_type opos,
            size_type an) const)
       (the last index in the current string object is returned whose
        character matches any character from tt(argument). If tt(opos) is
        provided it refers to the last index in the current string object
        where the search for tt(argument) should start (searching backward
        towards the beginning of the current object). 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 is returned whose
        character is equal to  tt(ch).)
    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 is returned whose
        character does not match any character from tt(argument).)
    ittq(size_type find_last_not_of(char const *argument, size_type opos,
        size_type an) const)
       (the last index in the current string object is returned whose
        character does not match any character from tt(argument). The tt(opos)
        and tt(an) parameters are handled as with tt(find_last_of).)
    ittq(size_t find_last_not_of(char ch, size_type opos) const)
       (the last index in the current string object is returned whose
        character is unequal to tt(ch).)
    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 content 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(const_reverse_iterator) is returned.)
    ithtq(rend)(string::reverse_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(const_reverse_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(starts_with)(bool starts_with(argument) const) 
       (returns tt(true) if the object's character range starts with
        tt(argument). The argument can be a tt(string), a tt(string_view), a
        tt(char) or an NTBS.)
    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 content of the current string object are swapped with the
        content 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)
