basic_string<charT, traits, Alloc>

Category: containers

Component type: type

Description

The basic_string class represents a Sequence of characters.
It contains all the usual operations of a Sequence, and, additionally,
it contains standard string operations such as search and concatenation.

The basic_string class is parameterized by character type, and by
that type's Character Traits. Most of the time, however, there is
no need to use the basic_string template directly. The types
string and wstring are typedefs for, respectively,
basic_string<char> and basic_string<wchar_t>.

Some of basic_string's member functions use an unusual method of
specifying positions and ranges. In addition to the conventional
method using iterators, many of basic_string's member functions use
a single value pos of type size_type to represent a position (in
which case the position is begin() + pos, and many of
basic_string's member functions use two values, pos and n, to
represent a range. In that case pos is the beginning of the range
and n is its size. That is, the range is [begin() + pos, begin() +
pos + n).

Note that the C++ standard does not specify the complexity of
basic_string operations. In this implementation, basic_string
has performance characteristics very similar to those of vector:
access to a single character is O(1), while copy and concatenation
are O(N). By contrast, rope has very different performance
characteristics: most rope operations have logarithmic complexity.

Note also that, according to the C++ standard, basic_string has very
unusual iterator invalidation semantics. Iterators may be invalidated
by swap, reserve, insert, and erase (and by functions that are
equivalent to insert and/or erase, such as clear, resize,
append, and replace). Additionally, however, the first call to
any non-const member function, including the non-const version of
begin() or operator[], may invalidate iterators. (The intent of
these iterator invalidation rules is to give implementors greater
freedom in implementation techniques.) In this implementation,
begin(), end(), rbegin(), rend(), operator[], c_str(), and
data() do not invalidate iterators. In this implementation,
iterators are only invalidated by member functions that explicitly
change the string's contents.

Number of elements for which memory has been allocated. That is,
the size to which the string can grow before memory must be
reallocated. capacity() is always greater than or equal to
size().

const charT* c_str() const

Returns a pointer to a null-terminated array of characters representing
the string's contents. For any string s it is guaranteed that
the first s.size() characters in the array pointed to by s.c_str()
are equal to the character in s, and that s.c_str()[s.size()]
is a null character. Note, however, that it not necessarily the first
null character. Characters within a string are permitted to be null.

const charT* data() const

Returns a pointer to an array of characters, not necessarily
null-terminated, representing the string's contents. data()
is permitted, but not required, to be identical to c_str().
The first size() characters of that array are guaranteed to be identical
to the characters in *this. The return value of data() is never
a null pointer, even if size() is zero.

Constructs a string from a substring of s. The substring begins at
character position pos and terminates at character position
pos + n or at the end of s, whichever comes first. This constructor
throws out_of_range if pos > s.size(). Note that when pos and n
have their default values, this is just a copy constructor.

basic_string(const charT* s)

Equivalent to basic_string(s, s + traits::length(s)).

basic_string(const charT* s, size_type n)

Equivalent to basic_string(s, s + n).

basic_string& operator=(const charT* s)

Equivalent to operator=(basic_string(s)).

basic_string& operator=(charT c)

Assigns to *this a string whose size is 1 and whose contents is
the single character c.

void reserve(size_t n)

Requests that the string's capacity be changed; the postcondition
for this member function is that, after it is called,
capacity() >= n. You may request that a string decrease its
capacity by calling reserve() with an argument less than the
current capacity. (If you call reserve() with an argument less
than the string's size, however, the capacity will only be reduced
to size(). A string's size can never be greater than its capacity.)
reserve() throws length_error if n > max_size().

Copies at most n characters from *this to a character array.
Throws out_of_range if pos > size(). Otherwise, equivalent to
copy(begin() + pos, begin() + pos + min(n, size()), buf).
Note that this member function does nothing other than copy
characters from *this to buf; in particular, it does not terminate
buf with a null character.

size_type find(const basic_string& s, size_type pos = 0) const

Searches for s as a substring of *this, beginning at
character position pos. It is almost the same as search,
except that search tests elements for equality using
operator== or a user-provided function object, while this member
function uses traits::eq. Returns the lowest character position
N such that pos <= N and pos + s.size() <= size() and such that, for every
i less than s.size(), (*this)[N + i] compares equal to s[i].
Returns npos if no such position N exists. Note that it is legal
to call this member function with arguments such that
s.size() > size() - pos, but such a search will always fail.

size_type find(const charT* s, size_type pos, size_type n) const

Searches for the first n characters of s as a substring of *this, beginning at
character pos of *this. This is equivalent to
find(basic_string(s, n), pos).

size_type find(const charT* s, size_type pos = 0) const

Searches for a null-terminated character array as a substring of *this, beginning at
character pos of *this. This is equivalent to
find(basic_string(s), pos).

size_type find(charT c, size_type pos = 0) const

Searches for the character c, beginning at character position pos.
That is, returns the first character position N greater than or equal
to pos, and less than size(), such that (*this)[N] compares equal
to c. Returns npos if no such character position N exists.

size_type rfind(const basic_string& s, size_type pos = npos) const

Searches backward for s as a substring of *this.
It is almost the same as find_end,
except that find_end tests elements for equality using
operator== or a user-provided function object, while this member
function uses traits::eq. This member function returns the largest
character position N such that N <= pos and N + s.size() <= size(),
and such that, for every i less than s.size(), (*this)[N + i]
compares equal to s[i].
Returns npos if no such position N exists. Note that it is legal
to call this member function with arguments such that
s.size() > size(), but such a search will always fail.

size_type rfind(const charT* s, size_type pos, size_type n) const

Searches backward for the first n characters of s as a substring of *this.
Equivalent to rfind(basic_string(s, n), pos).

size_type rfind(const charT* s, size_type pos = npos) const

Searches backward for a null-terminated character array as a substring of *this.
Equivalent to rfind(basic_string(s), pos).

size_type rfind(charT c, size_type pos = npos) const

Searches backward for the character c. That is, returns the largest
character position N such that N <= pos and N < size(), and
such that (*this)[N] compares equal to c. Returns npos if
no such character position exists.

Searches within *this, beginning at pos, for the first character
that is equal to any character within s. This is similar to the
standard algorithm find_first_of, but differs because
find_first_of compares characters using operator== or a
user-provided function object, while this member function uses
traits::eq. Returns the smallest character position N
such that pos <= N < size(), and such that (*this)[N]
compares equal to some character within s.
Returns npos if no such character position exists.

Searches within *this, beginning at pos, for the first character
that is equal to any character within the range [s, s+n). That is,
returns the smallest character position N
such that pos <= N < size(), and such that (*this)[N]
compares equal to some character in [s, s+n).
Returns npos if no such character position exists.

Searches within *this, beginning at pos, for the first character
that is not equal to any character within s.
Returns the smallest character position N
such that pos <= N < size(), and such that (*this)[N]
does not compare equal to any character within s.
Returns npos if no such character position exists.

Searches within *this, beginning at pos, for the first character
that is not equal to any character within the range [s, s+n). That is,
returns the smallest character position N
such that pos <= N < size(), and such that (*this)[N]
does not compare equal to any character in [s, s+n).
Returns npos if no such character position exists.

size_type find_first_not_of(const charT* s, size_type pos = 0) const

Equivalent to find_first_not_of(s, pos, traits::length(s)).

size_type find_first_not_of(charT c, size_type pos = 0) const

Returns the smallest character position N
such that pos <= N < size(), and such that (*this)[N]
does not compare equal to c.
Returns npos if no such character position exists.

Searches backward within *this for the first character
that is equal to any character within s. That is, returns the largest
character position N such that N <= pos and N < size(), and such
that (*this)[N] compares equal to some character within s.
Returns npos if no such character position exists.

Searches backward within *this for the first character
that is equal to any character within the range [s, s+n).
That is, returns the largest
character position N such that N <= pos and N < size(), and such
that (*this)[N] compares equal to some character within [s, s+n).
Returns npos if no such character position exists.

Searches backward within *this for the first character
that is not equal to any character within s.
That is, returns the largest
character position N such that N <= pos and N < size(), and such
that (*this)[N] does not compare equal to any character within s.
Returns npos if no such character position exists.

Searches backward within *this for the first character
that is not equal to any character within [s, s+n).
That is, returns the largest
character position N such that N <= pos and N < size(), and such
that (*this)[N] does not compare equal to any character within
[s, s+n). Returns npos if no such character position exists.

Searches backward *this for the first character
that is not equal to c. That is, returns the largest character
position N such that N <= pos and N < size(), and such
that (*this)[N] does not compare equal to c.

basic_string substr(size_type pos = 0, size_type n = npos) const

Equivalent to basic_string(*this, pos, n).

int compare(const basic_string& s) const

Three-way lexicographical comparison of s and *this, much like
strcmp. If traits::compare(data, s.data(), min(size(), s.size()))
is nonzero, then it returns that nonzero value. Otherwise returns a
negative number if size() < s.size(), a positive number if
size() > s.size(), and zero if the two are equal.

int compare(size_type pos, size_type n, const basic_string& s) const

Three-way lexicographical comparison of s and a substring of *this.
Equivalent to basic_string(*this, pos, n).compare(s).

Three-way lexicographical comparison of the first min(len, traits::length(s)
characters of s and a substring of *this.
Equivalent to basic_string(*this, pos, n).compare(basic_string(s, min(len, traits::length(s)))).

Reads s from the input stream is. Specifically, it skips
whitespace, and then replaces the contents of s with characters
read from the input stream. It continues reading characters until
it encounters a whitespace character (in which case that character is
not extracted), or until end-of-file, or, if is.width() is nonzero,
until it has read is.width() characters. This member function
resets is.width() to zero.

Replaces the contents of s with characters read from the input
stream. It continues reading characters until it encounters
the character delim (in which case that character is extracted
but not stored in s), or until end of file. Note that getline,
unlike operator>>, does not skip whitespace. As the name suggests,
it is most commonly used to read an entire line of text precisely as
the line appears in an input file.