Share via


basic_string Class

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

See Also

Reference

Thread Safety in the Standard C++ Library