Defined in header
template<classCharT,classTraits=std::char_traits<CharT>,classAllocator=std::allocator<CharT>>classbasic_string; (1) namespacepmr{template<classCharT,classTraits=std::char_traits<CharT>>usingbasic_string=std::basic_string<CharT,Traits,std::pmr::polymorphic_allocator<CharT>>;} (2) (since C++17)The class template basic_string stores and manipulates sequences of
-like objects, which are non-array objects of
and
. 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
or a compatible traits class.
The elements of a basic_string are stored contiguously, that is, for a basic_strings, &*(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
(except that customized construct/destroy are not used for construction/destruction of elements),
and
(since C++17).
The program is ill-formed if Traits::char_type is not CharT or Allocator::value_type is not CharT.
All member functions of std::basic_string are constexpr: it is possible to create and use std::basic_string objects in the evaluation of a constant expression.
However, defining a constexprstd::basic_string variable is generally an error, because constant evaluation requires any dynamically allocated storage to be released in the same evaluation, which is usually not the case with std::basic_string's initializer.
(since C++20)Several typedefs for common character types are provided:
Defined in header
Type Definition std::stringstd::basic_string<char>std::wstringstd::basic_string<wchar_t>std::u8string(C++20)std::basic_string<char8_t>std::u16string(C++11)std::basic_string<char16_t>std::u32string(C++11)std::basic_string<char32_t>std::pmr::string(C++17)std::pmr::basic_string<char>std::pmr::wstring(C++17)std::pmr::basic_string<wchar_t>std::pmr::u8string(C++20)std::pmr::basic_string<char8_t>std::pmr::u16string(C++17)std::pmr::basic_string<char16_t>std::pmr::u32string(C++17)std::pmr::basic_string<char32_t>Template parameters
CharT - character type Traits - traits class specifying the operations on the character type Allocator -
type used to allocate internal storage 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
,
, or
, and by calling non-const member functions, except
,
,
,
,
,
,
,
, and
.
Nested types
Type Definition traits_typeTraitsvalue_typeCharTallocator_typeAllocator
size_typeAllocator::size_type(until C++11)std::allocator_traits<Allocator>::size_type(since C++11)
difference_typeAllocator::difference_type(until C++11)std::allocator_traits<Allocator>::difference_type(since C++11)
referencevalue_type&
const_referenceconstvalue_type&
pointerAllocator::pointer
(until C++11)std::allocator_traits<Allocator>::pointer
(since C++11)
const_pointerAllocator::const_pointer
(until C++11)std::allocator_traits<Allocator>::const_pointer
(since C++11)
iterator
const_iterator
reverse_iteratorstd::reverse_iterator<iterator>
const_reverse_iteratorstd::reverse_iterator<const_iterator>
Data members
constexprsize_typenpos[static]the special value size_type(-1), its exact meaning depends on the context Member functions
constructs a basic_string
(public member function)
destroys the string, deallocating internal storage if used
(public member function)
assigns values to the string
(public member function)
assign characters to a string
(public member function)
(C++23)
assign a range of characters to a string
(public member function)
returns the associated allocator
(public member function)
Element access
accesses the specified character with bounds checking
(public member function)
accesses the specified character
(public member function)
(DR*)
accesses the first character
(public member function)
(DR*)
accesses the last character
(public member function)
returns a pointer to the first character of a string
(public member function)
returns a non-modifiable standard C character array version of the string
(public member function)
(C++17)
returns a non-modifiable basic_string_view into the entire string
(public member function)
Iterators
(C++11)
returns an iterator to the beginning
(public member function)
(C++11)
returns an iterator to the end
(public member function)
(C++11)
returns a reverse iterator to the beginning
(public member function)
(C++11)
returns a reverse iterator to the end
(public member function)
Capacity
checks whether the string is empty
(public member function)
returns the number of characters
(public member function)
returns the maximum number of characters
(public member function)
reserves storage
(public member function)
returns the number of characters that can be held in currently allocated storage
(public member function)
(DR*)
reduces memory usage by freeing unused memory
(public member function)
Modifiers
clears the contents
(public member function)
inserts characters
(public member function)
(C++23)
inserts a range of characters
(public member function)
removes characters
(public member function)
appends a character to the end
(public member function)
(DR*)
removes the last character
(public member function)
appends characters to the end
(public member function)
(C++23)
appends a range of characters to the end
(public member function)
appends characters to the end
(public member function)
replaces specified portion of a string
(public member function)
(C++23)
replaces specified portion of a string with a range of characters
(public member function)
copies characters
(public member function)
changes the number of characters stored
(public member function)
(C++23)
changes the number of characters stored and possibly overwrites indeterminate contents via user-provided operation
(public member function)
swaps the contents
(public member function)
Search
finds the first occurrence of the given substring
(public member function)
find the last occurrence of a substring
(public member function)
find first occurrence of characters
(public member function)
find first absence of characters
(public member function)
find last occurrence of characters
(public member function)
find last absence of characters
(public member function)
Operations
compares two strings
(public member function)
(C++20)
checks if the string starts with the given prefix
(public member function)
(C++20)
checks if the string ends with the given suffix
(public member function)
(C++23)
checks if the string contains the given substring or character
(public member function)
returns a substring
(public member function)
(C++26)
returns a sub-view
(public member function)
Non-member functions
concatenates two strings, a string and a char, or a string and
(function template)
operator==operator!=operator<operator>operator<=operator>=operator<=>
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20)
lexicographically compares two strings
(function template)
specializes the
algorithm
(function template)
erase(std::basic_string)erase_if(std::basic_string)
(C++20)
erases all elements satisfying specific criteria
(function template)
Input/output
performs stream input and output on strings
(function template)
read data from an I/O stream into a string
(function template)
Numeric conversions
(C++11)(C++11)(C++11)
converts a string to a signed integer
(function)
(C++11)(C++11)
converts a string to an unsigned integer
(function)
(C++11)(C++11)(C++11)
converts a string to a floating point value
(function)
(C++11)
converts an integral or floating-point value to string
(function)
(C++11)
converts an integral or floating-point value to wstring
(function)
Literals
Defined in inline namespace std::literals::string_literals
(C++14)
converts a character array literal to basic_string
(function)
Helper classes
(since C++17)
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
to match existing practice.
macro ValueStdFeature
(C++14)
User-defined literals for string types
(C++20)
,
(C++20)Constexpr for std::basic_string
(C++20)std::u8string
(C++20)
,
(C++23)
__cpp_lib_string_resize_and_overwrite
(C++23)
(C++23)Member functions for construction, insertion, and replacement that accept
Example
Run this code
#include<iostream>#include<string>intmain(){usingnamespacestd::literals;// Creating a string from const char*std::stringstr1="hello";// Creating a string using string literalautostr2="world"s;// Concatenating stringsstd::stringstr3=str1+" "+str2;// Print out the resultstd::cout<<str3<<'\n';std::string::size_typepos=str3.find(" ");str1=str3.substr(pos+1);// the part after the spacestr2=str3.substr(0,pos);// the part till the spacestd::cout<<str1<<' '<<str2<<'\n';// Accessing an element using subscript operator[]std::cout<<str1[0]<<'\n';str1[0]='W';std::cout<<str1<<'\n';}Output:
hello world world hello w World Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 contiguity of the storage for elements of basic_string
was accidently made not required by
required again
C++98 value_type was Traits::char_typechanged to CharT
(
) C++98 the behavior is undefined if any of Traits::char_type
and Allocator::char_type is different from CharTthe program is
ill-formed in this case
The Traits::char_type case is fixed in
.
See also
External links