basic_string
|
 |
A standard, templatized string
class defined by the ANSI/ISO standard committee. A basic_string
uses two template parameters to define the following.
- Type of element-The first
template parameter specifies the type of element that comprises the string.
For example, you can instantiate a
basic_string
of char to obtain a traditional C-like string, or a basic_string
of wchar_t (wide characters) to obtain an
international string.
- String traits-The second
template parameter specifies the string's traits. A trait class is an
auxiliary helper class controlling how the
basic_string
class assigns and compares elements, calculates the length of strings, and
defines the value denoting end-of-string. By using this approach, you can
vary specific low-level characteristics of each string type without altering
the code for basic_string .
Although you can create a wide
variety of different strings by using a template, most C++ programs only require
a couple of common string types. Standards<ToolKit> includes the following
typedefs that handle most situations.
// Regular string of characters.
typedef
basic_string< char, string_char_traits_char, allocator<char> > string
// Regular string of wide characters.
typedef
basic_string< wchar_t, string_char_traits<wchar_t>, allocator<wchar_t> >
wstring
The string_char_traits
class is a standard template class containing the
default behaviors for a string's traits. The string_char_traits_char
class is derived from the string_char_traits class
containing specialized behaviors for a string of regular char
s. The header file <ospace/string/traits.h>
contains the definition of these trait classes.
To enhance readability, this
reference page only documents the string
specialization of basic_string . The interface for wstring
is identical to that of string , except wchar_t
is used in place of char .
Errors
In general, input parameters
are checked. Typically, a range is specified as a starting position pos
and a length n . The pos
parameter is strictly checked to refer to a legal position within the string;
otherwise, an out_of_range error is generated.
The n parameter is more flexible; it is clamped to
the available length. A too-large value of n is not
an error, but takes all remaining characters. The descriptions below use the
language "clamped length" to refer to the shorter of the specified
value and available length.
The value npos
, defined as the largest number a size_t can
represent, is used as both an input value and a return value. When functions
return this value, typically something was not found, such as a specific
character, an index of a character, and so forth. If a string is created with
a value equal to npos , or an existing string is
modified to a length exceeding npos , a length_error
is generated.
Errors from elements
The basic_string
template does not make special considerations for errors that occur during
manipulation of the underlying elements. This container is not designed to
handle an element that has constructors, a destructor, or an assignment
operator that can fail.
Library
Standards<ToolKit>
Declaration
#include <string>
template< class CharT, class Traits, class Allocator >
class basic_string
Typedefs
// os_string and os_wstring.
typedef
basic_string< char, string_char_traits_char, allocator<char> >
string;
typedef
basic_string< wchar_t, string_char_traits< wchar_t >, allocator<wchar_t> >
wstring;
Interface
Constructor
string()
Constructs an empty
string.
Constructor
explicit
string( const Allocator& alloc )
Constructs an empty
string, using alloc to manage storage.
Constructor
string(
const string& str ,
const Allocator& alloc )
Constructs a string that
is a copy of str , using alloc
(default Allocator() ) to manage storage.
Constructor
string(
const string& str ,
size_t pos ,
size_t n ,
const Allocator& alloc )
Constructs a string that
is a copy of a portion of str , using alloc
(default Allocator() ) to manage storage. The
portion starts at pos and is the clamped value of n
in length.
Throws: out_of_range
, length_error
Constructor
string(
const char* str ,
const Allocator& alloc )
Constructs a string that
is a copy of the array str , using alloc
(default Allocator() ) to manage storage.
Constructor
string(
const char* str ,
size_t n ,
const Allocator& alloc )
Constructs a string that
is a copy of the array str , using alloc
(default Allocator() ) to manage storage.
Exactly n elements are copied from str
; nuls contained within that length have no
significance.
Constructor
string(
size_t n ,
char c ,
const Allocator& alloc )
Constructs a string that
contains n repetitions of the element c
, using alloc (default Allocator()
) to manage storage.
Constructor
string(
iterator first ,
iterator last ,
const Allocator& alloc )
Constructs a string that
contains characters in the range [ first
, last )
, using alloc (default Allocator()
) to manage storage.
Destructor
~string()
Destructor.
+=
string&
operator+=( const char* str )
Appends a copy of the nul
-terminated array of elements str . The
terminating element is not taken as part of the input. Returns a reference
to the string. This function is a synonym for append()
.
+=
string&
operator+=( const string& str )
Appends a copy of str
to the string. This function is a synonym for append()
. Returns a reference to the string.
+=
string&
operator+=( char c )
Appends a copy of element
c to the string. Returns a reference to the
string. This function is a synonym for append()
.
=
string&
operator=( const char* str )
Assigns the string to be
a copy of the nul -terminated array of elements
str . The terminating element is not taken as part
of the input. Returns a reference to the string. This function is a synonym
for assign() .
=
string&
operator=( char c )
Assigns the string to
contain a single element with value c . Returns a
reference to the string.
=
string&
operator=( const string& str )
Assigns string from str
. Returns a reference to the string. This is a synonym for assign()
.
[]
char&
operator[]( size_t pos )
Returns a reference to
the element at index pos .
Throws: out_of_range
[]
char
operator[]( size_t pos )
const
Returns a copy of the
element at index pos . It is legal to access one
past the end ( pos == size()
) in which case Traits::eos() is returned.
Throws: out_of_range
append
string&
append( const string& str )
Appends a portion of str
to the string and returns a reference to the string.
Throws: length_error
append
string&
append( const string& str ,
size_t pos ,
size_t n )
Appends a portion of str
to the string. The portion begins at offset pos
and is the clamped length of n . Returns a
reference to the string.
Throws: length_error
append
string&
append( const char* str )
Appends a copy of the nul
-terminated array of elements str . The
terminating element is not taken as part of the input. Returns a reference
to the string.
append
string&
append( const char* str ,
size_t n )
Append a copy of the
array str to the string. Exactly n
elements are copied from str ; any nuls
contained within that length have no significance. Returns a reference to
the string.
append
string&
append( size_t n ,
char c )
Appends n
copies of element c to the string. Returns a
reference to the string.
append
string&
append( iterator first ,
iterator last )
Appends the elements in
the range [ first ,
last ) to the string
and returns a reference to the string.
assign
string&
assign( const string& str )
Assigns the string from str
. Returns a reference to the string.
assign
string&
assign( const string& str ,
size_t pos ,
size_t n )
Assigns the string to be
a copy of a portion of str . The portion starts at
pos and is the clamped value of n
in length. Returns a reference to the string.
assign
string&
assign( const char* str )
Assigns the string to be
a copy of the nul -terminated array of elements
str . The terminating element is not taken as part
of the input. Returns a reference to the string.
assign
string&
assign( const char* str ,
size_t n )
Assigns the string to be
a copy of the array str . Exactly n
elements are copied from str ; nul
s contained within that length have no significance. Returns a reference to
the string.
assign
string&
assign( size_t n ,
char c )
Assigns the string to
contain n repetitions of the element c
.
assign
string&
assign( iterator first ,
iterator last )
Assigns the elements in
the range [ first ,
last ) to the string
and returns a reference to the string.
at
char&
at( size_t pos )
Returns a reference to
the element at index pos .
at
char
at( size_t pos )
const
Returns a copy of the
element at index pos .
begin
iterator
begin()
Returns an iterator
positioned at the first character in the string.
begin
const_iterator
begin() const
Returns a constant
iterator positioned at the first character in the string.
c_str
const
char* c_str() const
Returns a pointer to the
beginning of a sequence of size()+1 elements,
containing elements the string controls followed by a nul
-terminating value. The pointer returned refers to internal storage and can
become invalid when a non-const function, c_str()
(again), or data() is executed on the string.
capacity
size_t
capacity() const
Returns the storage
capacity of the string.
compare
int
compare( const string& str )
const
Compares string to str
.
The return value is zero
when the strings are equal, negative when this string is less than the other
string, and positive when this string is greater than the other string.
compare
int
compare( size_t pos ,
size_t n ,
const string& str )
const
Compares a portion of the
string (from position pos running through the
clamped length of n ) against the entire value of str
.
The return value is zero
when the compared portions of the strings are equal, negative when this
string's compared portion is less than the other string , and positive when
this string's compared portion is greater than the other string.
compare
int
compare( size_t pos1 ,
size_t n1 ,
const string& str ,
size_t pos2 ,
size_t n2 )
const
Compares a portion of the
string (from position pos1 running through the
clamped length of n1 ) against str
(from position pos2 running through the clamped
length of n2 ).
The return value is zero
when the compared portions of the strings are equal, negative when this
string's compared portion is less than the other string's compared portion,
and positive when this string's compared portion is greater than the other
string's compared portion.
compare
int
compare( const char* str )
const
Equivalent to compare(string(
str ) .
compare
int
compare( size_t pos, size_t n1, const char* str
, size_t n2 ) const
Equivalent to compare(
pos, n1, string( str ,
n2) ) .
copy
size_t
copy( char* str ,
size_t n ,
size_t pos )
const
Copies the elements
starting at pos (default 0) running the clamped
length of n to the area specified with str
.
data
const
char* data() const
Returns the internal data
of the string as an array of elements. No special terminating value is
added. For a zero-length string, the return value is unspecified (it may or
may not be NULL ). The pointer returned refers
to internal storage and can become invalid when a non-const function, c_str()
(again), or data() is executed on the string.
This is a very efficient function. See also c_str()
and copy() .
empty
bool
empty() const
Returns true
if the string does not contain any elements.
end
iterator
end()
Returns an iterator
positioned immediately after the last character in the string.
end
const_iterator
end() const
Returns a constant
iterator positioned immediately after the last character in the string.
erase
string&
erase() const
Clears the contents of
the string, creating an empty string. Returns a reference to the string.
erase
string&
erase( size_t pos ,
size_t n )
Removes the substring
starting at position pos with length n
from the string.
Returns a reference to the string.
erase
iterator
erase( iterator pos )
Removes the character at
position pos , and returns an iterator to the
character following pos , or end()
if pos was the last element.
erase
iterator
erase( iterator first ,
iterator last )
Removes the substring
specified by the range [ first
, last )
.
find
size_t
find( const string& str ,
size_t pos )
const
Starting the search from
index pos (default 0
) of the string, returns the index of the first occurrence of str
, or npos if no such index exists. Note that
unlike most other members, a value of pos that is
out-of-range is not an error. Instead, the string is never found.
find
size_t
find( char c ,
size_t pos )
const
Searches the string from
index pos (default 0
) for the first occurrence of character c .
Returns the index if a match is found, npos
otherwise.
Equivalent to find(
string( c ), pos
)
find
size_t
find( const char* str ,
size_t pos )
const
Equivalent to find(
string( str ), pos
)
find
size_t
find( const char* str ,
size_t pos ,
size_t n )
const
Equivalent to find(string(
str , n
), pos )
.
find_first_not_of
size_t
find_first_not_of( const string& str ,
size_t pos )
const
Returns the lowest index
greater than or equal to pos (default 0
) containing an element that does not also occur in str
. If no such index exists, returns npos .
find_first_not_of
size_t
find_first_not_of( const char& c ,
size_t pos )
const
Equivalent to find_first_not_of(string(
c ), pos
) .
find_first_not_of
size_t
find_first_not_of( const char* str ,
size_t pos )
const
Equivalent to find_first_not_of(string(
str ), pos
) .
find_first_not_of
size_t
find_first_not_of( const char* str ,
size_t pos ,
size_t n )
const
Equivalent to find_first_not_of(string(
str , n
), pos )
.
find_first_of
size_t
find_first_of( const string& str ,
size_t pos )
const
Returns the lowest index
greater than or equal to pos (default 0
) containing an element that also occurs in str .
If no such index exists, returns npos .
find_first_of
size_t
find_first_of( const char& c ,
size_t pos )
const
Equivalent to find_first_of(string(
c ), pos
) .
find_first_of
size_t
find_first_of( const char* str ,
size_t pos ,
size_t n )
const
Equivalent to find_first_of(string(
str , n
), pos )
.
find_first_of
size_t
find_first_of( const char* str ,
size_t pos )
const
Equivalent to find_first_of(string(
str ), pos
) .
find_last_not_of
size_t
find_last_not_of( const string& str ,
size_t pos )
const
Returns the highest index
less than or equal to pos (default npos
) containing an element that is not also present in str
. If no such index exists, returns npos .
find_last_not_of
size_t
find_last_not_of( const char& c ,
size_t pos )
const
Equivalent to find_last_not_of(string(
c ), pos
) .
find_last_not_of
size_t
find_last_not_of( const char* str ,
size_t pos )
const
Equivalent to find_last_not_of(string(
str ), pos
) .
find_last_not_of
size_t
find_last_not_of( const char* str ,
size_t pos
, size_t n
) const
Equivalent to find_last_not_of(string(
str , n
), pos )
.
find_last_of
size_t
find_last_of( const string& str ,
size_t pos )
const
Returns the highest index
less than or equal to pos (default npos
) containing an element that also occurs in str .
If no such index exists, returns npos .
find_last_of
size_t
find_last_of( const char& c ,
size_t pos )
const
Equivalent to find_last_of(string(
c ), pos
) .
find_last_of
size_t
find_last_of( const char* str ,
size_t pos )
const
Equivalent to find_last_of(string(
str ), pos
) .
find_last_of
size_t
find_last_of( const char* str ,
size_t pos ,
size_t n )
const
Equivalent to find_last_of(string(
str , n
), pos )
.
get_allocator
const
Allocator& get_allocator() const
Returns a constant
reference to the allocator the string is using to manage storage.
insert
string&
insert( size_t pos ,
const string& str )
Inserts at position pos
a copy of str and returns a reference to the
string.
insert
string&
insert( size_t pos1 ,
const string& str ,
size_t pos2 ,
size_t n_npos )
Inserts at index pos1
a portion of str, starting from pos2
(default 0) and running for the clamped length of n
. Returns a reference to the string.
insert
string&
insert( size_t pos ,
const char* str )
Inserts at position pos
a copy of the nul -terminated array of elements
str . The terminating element is not taken as part
of the input.
insert
string&
insert( size_t pos ,
const char* str ,
size_t n )
Inserts at position pos
a copy of the array str . Exactly n
elements are copied from str ; nuls
contained within that length have no significance. Returns a reference to
the string.
insert
string&
insert( size_t pos ,
size_t n ,
char c )
Inserts n
copies of c at position pos
. Returns a reference to the string.
insert
iterator
insert( iterator pos ,
char c )
Inserts character c
at position pos , and returns an iterator pointing
to the new element position.
insert
void
insert( iterator pos ,
size_t n ,
char c )
Inserts n
copies of character c at position pos
.
insert
void
insert( iterator pos ,
iterator first ,
iterator last )
Inserts at position pos
the characters from the range [ first
, last )
.
length
size_t
length() const
Returns the number of
elements the string contains.
max_size
size_t
max_size() const
Returns the maximum
possible string length.
rbegin
reverse_iterator
rbegin()
Returns an iterator
positioned at the first character in the string.
rbegin
const_reverse_iterator
rbegin() const
Returns a constant
iterator positioned at the first character in the string.
rend
reverse_iterator
rend()
Returns an iterator
positioned immediately after the last character in the string.
rend
const_reverse_iterator
rend() const
Returns a constant
iterator positioned immediately after the last character in the string.
replace
string&
replace( size_t pos ,
size_t n ,
const string& str )
Targets the sequence of
elements starting at pos with a length that is the
clamped value of n . Replaces the targeted
sequence with str and returns a reference to the
string.
replace
string&
replace( size_t pos1 ,
size_t n1 ,
const string& str ,
size_t pos2 ,
size_t n2 )
Targets the sequence of
elements starting at pos1 with a length that is
the clamped value of n1 . Replaces the targeted
sequence with a portion of str, starting at pos2
(default 0) and running for the clamped length of n2
(default npos ). Returns a reference to the
string.
replace
string&
replace( size_t pos ,
size_t n ,
const char* str )
Targets the sequence of
elements starting at pos with a length that is the
clamped value of n . Replaces the targeted
sequence with a copy of the nul -terminated
array of elements str . The terminating element is
not taken as part of the input. Returns a reference to the string.
replace
string&
replace( size_t pos ,
size_t n1 ,
const char* str ,
size_t n2 )
Targets the sequence of
elements starting at pos1 with a length that is
the clamped value of n1 . Replaces the targeted
sequence with a copy of the array str . Exactly n
elements are copied from str ; nul
s contained within that length have no significance. Returns a reference to
the string.
replace
string&
replace( size_t pos ,
size_t n1 ,
size_t n2 ,
char c )
Targets the sequence of
elements starting at pos with a length that is the
clamped value of n1 . Replaces the targeted
sequence with n2 copies of c
. Returns a reference to the string.
replace
string&
replace( iterator first ,
iterator last
, const string&
str )
Replaces the characters
in the range [ first ,
last ) with str
.
replace
string&
replace( iterator first ,
iterator last ,
const char* str )
Replaces the characters
in the range [ first ,
last ) with the
null-terminated string str .
replace
string&
replace( iterator first ,
iterator last ,
const char* str ,
size_t n )
Replaces the characters
in the range [ first ,
last ) with the first
n elements of the null-terminated string str
.
replace
string&
replace( iterator first ,
iterator last ,
size_t n ,
char c )
Replaces the characters
in the range [ first ,
last ) with n
copies of c .
replace
string&
replace( iterator first1 ,
iterator last1 ,
iterator first2 ,
iterator last2 )
Replaces the characters
in the range [ first1
, last1 )
with the characters in the range [ first2
, last2 )
, and returns a reference to the string.
reserve
void
reserve( size_t size )
If necessary, expands the
string's internal storage so that it can hold at least size
characters. This optimizes subsequent append()
and operator+=() calls. The string can grow,
through appending, up to a total length of size
before reallocating storage. Calling other functions to manipulate the
string, or assigning this string to another string, disables the reserve
effect.
reserve
size_t
reserve() const
Returns the number of
characters the string can hold without reallocating internal storage.
resize
void
resize( size_t n ,
char c )
If the string size is
less than n , appends n -
size ()
copies of c to the string; otherwise, truncates
the string to n characters in length.
Throws: length_error
resize
void
resize( size_t n )
Equivalent to resize(
n , Traits::eos() )
.
Throws: length_error
rfind
size_t
rfind( const string& str ,
size_t pos )
const
Returns the index of the
last occurrence of str that starts before or at pos
(default npos ), or returns npos
if no match was found.
rfind
size_t
rfind( const char* str ,
size_t pos )
const
Returns the index of the
last occurrence of the null-terminated string str
that starts before or at pos (default npos
), or returns npos if no match was found.
Equivalent to rfind(
string( str ), pos
) .
rfind
size_t
rfind( const char* str ,
size_t pos ,
size_t n )
const
Equivalent to rfind(
string( str , n
), pos )
.
rfind
size_t
rfind( char c ,
size_t pos )
const
Returns the index of the
last occurrence of c that starts before or at pos
(default npos ), or returns npos
if no match was found.
Equivalent to rfind(
string( c ), pos
) .
size
size_t
size() const
Returns the number of
elements the string contains.
substr
string
substr( size_t pos ,
size_t n )
const
Returns a string with a
length that is the smaller of n (default npos
) and size() - pos,
and with contents that are copied from index pos
(default 0) of the string.
swap
void
swap( string& other )
Exchanges contents with
those of other .
Non-Member Functions
+
string
operator+ ( const string& x ,
const string& y )
Returns the concatenation
of x and y .
+
string
operator+( const string& x ,
const char* y )
Returns the concatenation
of x and y .
+
string
operator+( const char* x ,
const string& y )
Returns the concatenation
of x and y .
+
string
operator+( const string& x ,
const char y )
Returns the concatenation
of x and y .
+
string
operator+( const char x ,
const string& y )
Returns the concatenation
of x and y .
>,
<, >=, <=,
==,
!=
various
relational operators
A full complement of
relational operators are provided, which simplify the use of compare()
.
swap
void
swap( string& x ,
string& y )
Exchanges the contents of
x and y .
<<
ostream&
operator<<( ostream& stream ,
const string& str )
Prints str
to stream .
Copyright©1994-2026 Recursion
Software LLC
All Rights Reserved - For use by licensed users only.