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 or a compatible traits class.

The elements of a basic_string are stored contiguously, that is, for a basic_string s , & * ( s. begin ( ) + n ) == & * s. begin ( ) + n for any n in [ ​ 0 ​ , s. size ( ) ) , and * ( s. begin ( ) + s. size ( ) ) has value CharT ( ) (a null terminator) (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 to match existing practice.

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