std::basic_string

The class template basic_string stores and manipulates sequences of character-like objects, which are non-array objects of TrivialType and StandardLayoutType . The class is dependent neither on the character type nor on the nature of operations on that type. The definitions of the operations are supplied via the Traits template parameter - a specialization of std::char_traits

The elements of a basic_string are stored contiguously, that is, for a basic_string s, & * (s.begin ( ) + n) == & *s.begin ( ) + for any n in [ ​0​ ,  s.size() ) , and * (s.begin ( ) + s.size ( ) ) has value CharT() (since C++11) ; or, equivalently, a pointer to s[0] can be passed to functions that expect a pointer to the first element of an array(until C++11) a null-terminated array(since C++11) of CharT

std::basic_string satisfies the requirements of AllocatorAwareContainer (except that customized construct/destroy are not used for construction/destruction of elements), SequenceContainer and ContiguousContainer (since C++17)

If any of Traits::char_type and Allocator::char_type is different from CharT, the program is ill-formed.

Several typedefs for common character types are provided:

Template parameters

Nested types

Data members

Member functions

Non-member functions

Literals

Helper classes

Deduction guides (since C++17)

Iterator invalidation

References, pointers, and iterators referring to the elements of a basic_string may be invalidated by any standard library function taking a reference to non-const basic_string as an argument, such as std::getline, std::swap, or operator>>, and by calling non-const member functions, except operator[], at, data, front, back, begin, rbegin, end, and rend

Notes

Although it is required that customized construct or destroy is used when constructing or destroying elements of std::basic_string until C++23, all implementations only used the default mechanism. The requirement is corrected by P1072R10

Example

#include <iostream>
#include <string>
 
int main()
{
    using namespace std::literals;
 
    // Creating a string from const char*
    std::string str1 = "hello";
 
    // Creating a string using string literal
    auto str2 = "world"s;
 
    // Concatenating strings
    std::string str3 = str1 + " " + str2;
 
    // Print out the result
    std::cout << str3 << '\n';
 
    std::string::size_type pos = str3.find(" ");
    str1 = str3.substr(pos + 1); // the part after the space
    str2 = str3.substr(0, pos);  // the part till the space
 
    std::cout << str1 << ' ' << str2 << '\n';
 
    // Accessing an element using subscript operator[]
    std::cout << str1[0] << '\n';
    str1[0] = 'W';
    std::cout << str1 << '\n';
}

hello world
world hello
w
World

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

1. ↑ The Traits::char_type case is fixed in P1148R0.

See also

External links