basic_string Class

Article
07/25/2013

The sequences controlled by an object of template class basic_string are the Standard C++ string class and are usually referred to as strings, but they should not be confused with the null-terminated C-strings used throughout the Standard C++ Library. The string class is a container that enables the use of strings as normal types, such as using comparison and concatenation operations, iterators, and STL algorithms and copying and assigning with class allocator managed memory.

template < 
   class CharType, 
   class Traits=char_traits<CharType>,  
   class Allocator=allocator<CharType>  
> 
class basic_string

Parameters

CharType
The data type of a single character to be stored in the string. 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.
Traits
Various important properties of the CharType elements in a basic_string specialization are described by the class Traits.
Allocator
The type that represents the stored allocator object that encapsulates details about the string's allocation and deallocation of memory. The default value is allocator*<Type>.*

Many member functions require an operand sequence of elements. You can specify such an operand sequence several ways.

Element	Description
_Ch	One element with character value _Ch.
_Count, _Ch	A repetition of _Count elements each with value _Ch.
_Ptr	A null-terminated sequence, such as a C string, with a CharType 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.
_Str	The sequence specified by a basic_string object.
_Str, _Off, _Count	The substring of the basic_string object _Str with up to _Count elements (or through the end of the string, whichever comes first) beginning at position _Off.
_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 _Off) 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 type out_of_range Class.

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 type length_error Class.

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 a non-const member function.

Constructors

basic_string

Constructs a string that is empty or initialized by specific characters or that is a copy of all or part of some other string object or C-string.

Typedefs

allocator_type	A type that represents the allocator class for a string object.
const_iterator	A type that provides a random-access iterator that can access and read a const element in the string.
const_pointer	A type that provides a pointer to a const element in a string.
const_reference	A type that provides a reference to a const element stored in a string for reading and performing const operations.
const_reverse_iterator	A type that provides a random-access iterator that can read any const element in the string.
difference_type	A type that provides the difference between two iterators that refer to elements within the same string.
iterator	A type that provides a random-access iterator that can read or modify any element in a string.
npos	An unsigned integral value initialized to –1 that indicates either "not found" or "all remaining characters" when a search function fails.
pointer	A type that provides a pointer to a character element in a string or character array.
reference	A type that provides a reference to an element stored in a string.
reverse_iterator	A type that provides a random-access iterator that can read or modify an element in a reversed string.
size_type	An unsigned integral type for the number of elements in a string.
traits_type	A type for the character traits of the elements stored in a string.
value_type	A type that represents the type of characters stored in a string.

Member Functions

append	Adds characters to the end of a string.
assign	Assigns new character values to the contents of a string.
at	Returns a reference to the element at a specified location in the string.
back
begin	Returns an iterator addressing the first element in the string.
c_str	Converts the contents of a string as a C-style, null-terminated, string.
capacity	Returns the largest number of elements that could be stored in a string without increasing the memory allocation of the string.
cbegin	Returns a const iterator addressing the first element in the string.
cend	Returns a const iterator that addresses the location succeeding the last element in a string.
clear	Erases all elements of a string.
compare	Compares a string with a specified string to determine if the two strings are equal or if one is lexicographically less than the other.
copy	Copies at most a specified number of characters from an indexed position in a source string to a target character array. Deprecated. Use basic_string::_Copy_s instead.
crbegin	Returns a const iterator that addresses the first element in a reversed string.
crend	Returns a const iterator that addresses the location succeeding the last element in a reversed string.
_Copy_s	Copies at most a specified number of characters from an indexed position in a source string to a target character array.
data	Converts the contents of a string into an array of characters.
empty	Tests whether the string contains characters.
end	Returns an iterator that addresses the location succeeding the last element in a string.
erase	Removes an element or a range of elements in a string from a specified position.
find	Searches a string in a forward direction for the first occurrence of a substring that matches a specified sequence of characters.
find_first_not_of	Searches through a string for the first character that is not any element of a specified string.
find_first_of	Searches through a string for the first character that matches any element of a specified string.
find_last_not_of	Searches through a string for the last character that is not any element of a specified string.
find_last_of	Searches through a string for the last character that is an element of a specified string.
front	Returns a reference to the first element in a string.
get_allocator	Returns a copy of the allocator object used to construct the string.
insert	Inserts an element or a number of elements or a range of elements into the string at a specified position.
length	Returns the current number of elements in a string.
max_size	Returns the maximum number of characters a string could contain.
pop_back	Erases the last element of the string.
push_back	Adds an element to the end of the string.
rbegin	Returns an iterator to the first element in a reversed string.
rend	Returns an iterator that points just beyond the last element in a reversed string.
replace	Replaces elements in a string at a specified position with specified characters or characters copied from other ranges or strings or C-strings.
reserve	Sets the capacity of the string to a number at least as great as a specified number.
resize	Specifies a new size for a string, appending or erasing elements as required.
rfind	Searches a string in a backward direction for the first occurrence of a substring that matches a specified sequence of characters.
shrink_to_fit	Discards the excess capacity of the string.
size	Returns the current number of elements in a string.
substr	Copies a substring of at most some number of characters from a string beginning from a specified position.
swap	Exchange the contents of two strings.

Operators

operator+=	Appends characters to a string.
operator=	Assigns new character values to the contents of a string.
operator[]	Provides a reference to the character with a specified index in a string.

Requirements

Header: <string>

Namespace: std

Share via