View source for cpp/string/basic string

You do not have permission to edit this page, for the following reasons:

The action you have requested is limited to users in one of the groups: Users, Administrators.

Due to recent vandalism, editing of this page is temporarily disabled for new users.If you want to suggest a change, please leave a message on the suggestions page for new users instead (don't be surprised if that page appears vandalized!).

You can view and copy the source of this page.

{{cpp/title|basic_string}}
{{cpp/string/basic_string/navbar}}
{{dcl begin}}
{{dcl header|string}}
{{dcl|num=1|1=
template<
    class CharT,
    class Traits = std::char_traits<CharT>,
    class Allocator = std::allocator<CharT>
> class basic_string;
}}
{{dcl|since=c++17|num=2|1=
namespace pmr {
template<
    class CharT,
    class Traits = std::char_traits<CharT>
> using basic_string =
    std::basic_string<CharT, Traits, std::pmr::polymorphic_allocator<CharT>>;
}
}}
{{dcl end}}

The class template {{tt|basic_string}} stores and manipulates sequences of [[cpp/language/types#Character types|character]]-like objects, which are non-array objects of {{named req|TrivialType}} and {{named req|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 {{tt|Traits}} template parameter - a specialization of {{lc|std::char_traits}} or a compatible traits class.

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

{{tt|std::basic_string}} satisfies the requirements of {{named req|AllocatorAwareContainer}} (except that customized {{tt|construct}}/{{tt|destroy}} are not used for construction/destruction of elements), {{named req|SequenceContainer}}{{rev inl|since=c++17| and {{named req|ContiguousContainer}}}}.

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

{{cpp/is_constexpr|since=c++20|transient=yes}}

Several typedefs for common character types are provided:
{{dsc begin}}
{{dsc header|string}}
{{dsc hitem|Type|Definition}}
{{dsc|{{tt|std::string}}|{{c/core|std::basic_string<char>}}}}
{{dsc|{{tt|std::wstring}}|{{c/core|std::basic_string<wchar_t>}}}}
{{dsc|{{tt|std::u8string}} {{mark c++20}}|{{c/core|std::basic_string<char8_t>}}}}
{{dsc|{{tt|std::u16string}} {{mark c++11}}|{{c/core|std::basic_string<char16_t>}}}}
{{dsc|{{tt|std::u32string}} {{mark c++11}}|{{c/core|std::basic_string<char32_t>}}}}
{{dsc|{{tt|std::pmr::string}} {{mark c++17}}|{{c/core|std::pmr::basic_string<char>}}}}
{{dsc|{{tt|std::pmr::wstring}} {{mark c++17}}|{{c/core|std::pmr::basic_string<wchar_t>}}}}
{{dsc|{{tt|std::pmr::u8string}} {{mark c++20}}|{{c/core|std::pmr::basic_string<char8_t>}}}}
{{dsc|{{tt|std::pmr::u16string}} {{mark c++17}}|{{c/core|std::pmr::basic_string<char16_t>}}}}
{{dsc|{{tt|std::pmr::u32string}} {{mark c++17}}|{{c/core|std::pmr::basic_string<char32_t>}}}}
{{dsc end}}

===Template parameters===
{{par begin}}
{{par|CharT|character type}}
{{par|Traits|traits class specifying the operations on the character type}}
{{par|Allocator|{{named req|Allocator}} type used to allocate internal storage}}
{{par end}}

===Nested types===
{{dsc begin}}
{{dsc hitem|Type|Definition}}
{{dsc|{{tt|traits_type}}|{{tt|Traits}}}}
{{dsc|{{tt|value_type}}|{{tt|CharT}}}}
{{dsc inc|cpp/container/dsc allocator_type|basic_string}}
{{dsc inc|cpp/container/dsc size_type|basic_string}}
{{dsc inc|cpp/container/dsc difference_type|basic_string}}
{{dsc inc|cpp/container/dsc reference|basic_string}}
{{dsc inc|cpp/container/dsc const_reference|basic_string}}
{{dsc inc|cpp/container/dsc pointer|basic_string}}
{{dsc inc|cpp/container/dsc const_pointer|basic_string}}
{{dsc inc|cpp/container/dsc iterator|basic_string}}
{{dsc inc|cpp/container/dsc const_iterator|basic_string}}
{{dsc inc|cpp/container/dsc reverse_iterator|basic_string}}
{{dsc inc|cpp/container/dsc const_reverse_iterator|basic_string}}
{{dsc end}}

===Data members===
{{dsc begin}}
{{cpp/string/basic string/dsc npos}}
{{dsc end}}

===Member functions===
{{dsc begin}}
{{dsc inc|cpp/string/basic_string/dsc constructor}}
{{dsc inc|cpp/string/basic_string/dsc destructor}}
{{dsc inc|cpp/string/basic_string/dsc operator{{=}}}}
{{dsc inc|cpp/string/basic_string/dsc assign}}
{{dsc inc|cpp/string/basic_string/dsc assign_range}}
{{dsc inc|cpp/string/basic_string/dsc get_allocator}}

{{dsc h2|Element access}}
{{dsc inc|cpp/string/basic_string/dsc at}}
{{dsc inc|cpp/string/basic_string/dsc operator_at}}
{{dsc inc|cpp/string/basic_string/dsc front}}
{{dsc inc|cpp/string/basic_string/dsc back}}
{{dsc inc|cpp/string/basic_string/dsc data}}
{{dsc inc|cpp/string/basic_string/dsc c_str}}
{{dsc inc|cpp/string/basic_string/dsc operator_string_view}}

{{dsc h2|Iterators}}
{{dsc inc|cpp/string/basic_string/dsc begin}}
{{dsc inc|cpp/string/basic_string/dsc end}}
{{dsc inc|cpp/string/basic_string/dsc rbegin}}
{{dsc inc|cpp/string/basic_string/dsc rend}}

{{dsc h2|Capacity}}
{{dsc inc|cpp/string/basic_string/dsc empty}}
{{dsc inc|cpp/string/basic_string/dsc size}}
{{dsc inc|cpp/string/basic_string/dsc max_size}}
{{dsc inc|cpp/string/basic_string/dsc reserve}}
{{dsc inc|cpp/string/basic_string/dsc capacity}}
{{dsc inc|cpp/string/basic_string/dsc shrink_to_fit}}

{{dsc h2|Modifiers}}
{{dsc inc|cpp/string/basic_string/dsc clear}}
{{dsc inc|cpp/string/basic_string/dsc insert}}
{{dsc inc|cpp/string/basic_string/dsc insert_range}}
{{dsc inc|cpp/string/basic_string/dsc erase}}
{{dsc inc|cpp/string/basic_string/dsc push_back}}
{{dsc inc|cpp/string/basic_string/dsc pop_back}}
{{dsc inc|cpp/string/basic_string/dsc append}}
{{dsc inc|cpp/string/basic_string/dsc append_range}}
{{dsc inc|cpp/string/basic_string/dsc operator+{{=}}}}
{{dsc inc|cpp/string/basic_string/dsc replace}}
{{dsc inc|cpp/string/basic_string/dsc replace_with_range}}
{{dsc inc|cpp/string/basic_string/dsc copy}}
{{dsc inc|cpp/string/basic_string/dsc resize}}
{{dsc inc|cpp/string/basic_string/dsc resize_and_overwrite}}
{{dsc inc|cpp/string/basic_string/dsc swap}}

{{dsc h2|Search}}
{{dsc inc|cpp/string/basic_string/dsc find}}
{{dsc inc|cpp/string/basic_string/dsc rfind}}
{{dsc inc|cpp/string/basic_string/dsc find_first_of}}
{{dsc inc|cpp/string/basic_string/dsc find_first_not_of}}
{{dsc inc|cpp/string/basic_string/dsc find_last_of}}
{{dsc inc|cpp/string/basic_string/dsc find_last_not_of}}

{{dsc h2|Operations}}
{{dsc inc|cpp/string/basic_string/dsc compare}}
{{dsc inc|cpp/string/basic_string/dsc starts_with}}
{{dsc inc|cpp/string/basic_string/dsc ends_with}}
{{dsc inc|cpp/string/basic_string/dsc contains}}
{{dsc inc|cpp/string/basic_string/dsc substr}}
{{dsc end}}

===Non-member functions===
{{dsc begin}}
{{dsc inc|cpp/string/basic_string/dsc operator+}}
{{dsc inc|cpp/string/basic_string/dsc operator_cmp}}
{{dsc inc|cpp/string/basic_string/dsc swap2}}
{{dsc inc|cpp/container/dsc erase seq|basic_string}}
{{dsc h2|Input/output}}
{{dsc inc|cpp/string/basic_string/dsc operator_ltltgtgt}}
{{dsc inc|cpp/string/basic_string/dsc getline}}

{{dsc h2|Numeric conversions}}
{{dsc inc|cpp/string/basic_string/dsc stol}}
{{dsc inc|cpp/string/basic_string/dsc stoul}}
{{dsc inc|cpp/string/basic_string/dsc stof}}
{{dsc inc|cpp/string/basic_string/dsc to_string}}
{{dsc inc|cpp/string/basic_string/dsc to_wstring}}
{{dsc end}}

===Literals===
{{dsc begin}}
{{dsc namespace|std::literals::string_literals|inline=true}}
{{dsc inc|cpp/string/basic_string/dsc operator""s}}
{{dsc end}}

===Helper classes===
{{dsc begin}}
{{dsc inc|cpp/string/basic_string/dsc hash}}
{{dsc end}}

===[[cpp/string/basic_string/deduction_guides|Deduction guides]] {{mark since c++17}}===

===Iterator invalidation===
References, pointers, and iterators referring to the elements of a {{tt|basic_string}} may be invalidated by any standard library function taking a reference to non-const {{tt|basic_string}} as an argument, such as {{lc|std::getline}}, {{lc|std::swap}}, or {{ltt|cpp/string/basic_string/operator_ltltgtgt|operator>>}}, and by calling non-const member functions, except {{ltt|cpp/string/basic_string/operator_at|operator[]}}, {{rlt|at}}, {{rlt|data}}, {{rlt|front}}, {{rlt|back}}, {{rlt|begin}}, {{rlt|rbegin}}, {{rlt|end}}, and {{rlt|rend}}.

===Notes===
Although it is required that customized {{tt|construct}} or {{tt|destroy}} is used when constructing or destroying elements of {{tt|std::basic_string}} until C++23, all implementations only used the default mechanism. The requirement is corrected by {{wg21|P1072R10}} to match existing practice.

{{ftm begin|std=1|value=1|comment=1|sort=1}}
{{ftm|std=C++14|value=201304L|__cpp_lib_string_udls|[[#Literals|User-defined literals for string types]]}}
{{ftm|std=C++20|value=201711L|__cpp_lib_starts_ends_with|{{rlt|starts_with}}, {{rlt|ends_with}}}}
{{ftm|std=C++20|value=201907L|__cpp_lib_constexpr_string|Constexpr for {{tt|std::basic_string}}}}
{{ftm|std=C++20|value=201907L|__cpp_lib_char8_t|{{tt|std::u8string}}}}
{{ftm|std=C++20|value=202002L|__cpp_lib_erase_if|{{rlt|erase2|erase}}, {{rlt|erase2|erase_if}}}}
{{ftm|std=C++23|value=202011L|__cpp_lib_string_contains|{{rlt|contains}}}}
{{ftm|std=C++23|value=202110L|__cpp_lib_string_resize_and_overwrite|{{rlt|resize_and_overwrite}}}}
{{ftm|std=C++23|value=202202L|__cpp_lib_containers_ranges|Member functions for construction, insertion, and replacement that accept {{ls|cpp/ranges/to#container compatible range}}}}
{{ftm end}}

===Example===
{{example
|code=
#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';
}
|output=
hello world
world hello
w
World
}}

===Defect reports===
{{dr list begin}}
{{dr list item|wg=lwg|dr=530|std=C++98|before=contiguity of the storage for elements of {{tt|basic_string}}<br>was accidently made not required by {{wg21|LWG259}}|after=required again}}
{{dr list item|wg=lwg|dr=2861|std=C++98|before={{tt|value_type}} was {{tt|Traits::char_type}}|after=changed to {{tt|CharT}}}}
{{dr list item|wg=lwg|dr=2994|paper=P1148R0|std=C++98|before=the behavior is undefined if any of {{tt|Traits::char_type}}<ref>The {{tt|Traits::char_type}} case is fixed in {{stddoc|P1148R0}}.</ref><br>and {{tt|Allocator::char_type}} is different from {{tt|CharT}}|after=the program is<br>ill-formed in this case}}
{{dr list end}}
<references/>

===See also===
{{dsc begin}}
{{dsc inc|cpp/string/dsc basic_string_view}}
{{dsc end}}

===External links===
{{eli|{{enwiki|C%2B%2B_string_handling|C++ string handling}}}}

{{langlinks|de|es|fr|it|ja|pl|pt|ru|tr|zh}}

Templates used on this page:

Template:!! (view source)
Template:== (view source)
Template:anchor (view source)
Template:box/core (view source)
Template:c (view source) (protected)
Template:c/core (view source) (protected)
Template:cmark (view source) (protected)
Template:cmark static (view source) (protected)
Template:cpp/container/dsc allocator type (view source)
Template:cpp/container/dsc const iterator (view source)
Template:cpp/container/dsc const pointer (view source)
Template:cpp/container/dsc const reference (view source)
Template:cpp/container/dsc const reverse iterator (view source)
Template:cpp/container/dsc difference type (view source)
Template:cpp/container/dsc erase seq (view source)
Template:cpp/container/dsc iterator (view source)
Template:cpp/container/dsc pointer (view source)
Template:cpp/container/dsc reference (view source)
Template:cpp/container/dsc reverse iterator (view source)
Template:cpp/container/dsc size type (view source)
Template:cpp/is constexpr (view source)
Template:cpp/navbar content (view source)
Template:cpp/navbar heading (view source)
Template:cpp/string/basic string/dsc append (view source)
Template:cpp/string/basic string/dsc append range (view source)
Template:cpp/string/basic string/dsc assign (view source)
Template:cpp/string/basic string/dsc assign range (view source)
Template:cpp/string/basic string/dsc at (view source)
Template:cpp/string/basic string/dsc back (view source)
Template:cpp/string/basic string/dsc begin (view source)
Template:cpp/string/basic string/dsc c str (view source)
Template:cpp/string/basic string/dsc capacity (view source)
Template:cpp/string/basic string/dsc clear (view source)
Template:cpp/string/basic string/dsc compare (view source)
Template:cpp/string/basic string/dsc constructor (view source)
Template:cpp/string/basic string/dsc contains (view source)
Template:cpp/string/basic string/dsc copy (view source)
Template:cpp/string/basic string/dsc data (view source)
Template:cpp/string/basic string/dsc destructor (view source)
Template:cpp/string/basic string/dsc empty (view source)
Template:cpp/string/basic string/dsc end (view source)
Template:cpp/string/basic string/dsc ends with (view source)
Template:cpp/string/basic string/dsc erase (view source)
Template:cpp/string/basic string/dsc find (view source)
Template:cpp/string/basic string/dsc find first not of (view source)
Template:cpp/string/basic string/dsc find first of (view source)
Template:cpp/string/basic string/dsc find last not of (view source)
Template:cpp/string/basic string/dsc find last of (view source)
Template:cpp/string/basic string/dsc front (view source)
Template:cpp/string/basic string/dsc get allocator (view source)
Template:cpp/string/basic string/dsc getline (view source)
Template:cpp/string/basic string/dsc hash (view source)
Template:cpp/string/basic string/dsc insert (view source)
Template:cpp/string/basic string/dsc insert range (view source)
Template:cpp/string/basic string/dsc max size (view source)
Template:cpp/string/basic string/dsc npos (view source)
Template:cpp/string/basic string/dsc operator""s (view source)
Template:cpp/string/basic string/dsc operator+ (view source)
Template:cpp/string/basic string/dsc operator+= (view source)
Template:cpp/string/basic string/dsc operator= (view source)
Template:cpp/string/basic string/dsc operator at (view source)
Template:cpp/string/basic string/dsc operator cmp (view source)
Template:cpp/string/basic string/dsc operator ltltgtgt (view source)
Template:cpp/string/basic string/dsc operator string view (view source)
Template:cpp/string/basic string/dsc pop back (view source)
Template:cpp/string/basic string/dsc push back (view source)
Template:cpp/string/basic string/dsc rbegin (view source)
Template:cpp/string/basic string/dsc rend (view source)
Template:cpp/string/basic string/dsc replace (view source)
Template:cpp/string/basic string/dsc replace with range (view source)
Template:cpp/string/basic string/dsc reserve (view source)
Template:cpp/string/basic string/dsc resize (view source)
Template:cpp/string/basic string/dsc resize and overwrite (view source)
Template:cpp/string/basic string/dsc rfind (view source)
Template:cpp/string/basic string/dsc shrink to fit (view source)
Template:cpp/string/basic string/dsc size (view source)
Template:cpp/string/basic string/dsc starts with (view source)
Template:cpp/string/basic string/dsc stof (view source)
Template:cpp/string/basic string/dsc stol (view source)
Template:cpp/string/basic string/dsc stoul (view source)
Template:cpp/string/basic string/dsc substr (view source)
Template:cpp/string/basic string/dsc swap (view source)
Template:cpp/string/basic string/dsc swap2 (view source)
Template:cpp/string/basic string/dsc to string (view source)
Template:cpp/string/basic string/dsc to wstring (view source)
Template:cpp/string/basic string/navbar (view source)
Template:cpp/string/basic string/navbar content (view source)
Template:cpp/string/basic string/navbar heading (view source)
Template:cpp/string/dsc basic string view (view source)
Template:cpp/string/navbar content (view source)
Template:cpp/string/navbar heading (view source)
Template:cpp/title (view source) (protected)
Template:ctitle (view source) (protected)
Template:dcl (view source) (protected)
Template:dcl/std (view source) (semi-protected)
Template:dcl begin (view source) (protected)
Template:dcl end (view source) (protected)
Template:dcl header (view source) (protected)
Template:dcl list header/link (view source)
Template:dcl sep (view source) (protected)
Template:dr list begin (view source)
Template:dr list end (view source)
Template:dr list item (view source)
Template:dsc (view source) (protected)
Template:dsc begin (view source) (protected)
Template:dsc editlink (view source)
Template:dsc end (view source) (protected)
Template:dsc fun (view source) (protected)
Template:dsc guard (view source) (protected)
Template:dsc h2 (view source) (protected)
Template:dsc header (view source) (protected)
Template:dsc header/link (view source)
Template:dsc hitem (view source) (protected)
Template:dsc inc (view source) (protected)
Template:dsc mark mem (view source) (protected)
Template:dsc mem ctor (view source) (protected)
Template:dsc mem dtor (view source) (protected)
Template:dsc mem fun (view source) (protected)
Template:dsc member (view source) (protected)
Template:dsc namespace (view source) (protected)
Template:dsc ptclass (view source) (protected)
Template:dsc small (view source)
Template:dsc tclass (view source) (protected)
Template:dsc tfun (view source) (protected)
Template:eli (view source)
Template:enwiki (view source)
Template:example (view source) (protected)
Template:ftm (view source)
Template:ftm begin (view source)
Template:ftm end (view source)
Template:ftm link (view source)
Template:get lang (view source) (protected)
Template:get lang formal (view source)
Template:l2tt/core (view source) (protected)
Template:langlinks (view source) (protected)
Template:langlinks/one (view source) (protected)
Template:lc (view source) (protected)
Template:lconcept (view source)
Template:lconcept/cat (view source)
Template:lconcept/pg (view source)
Template:lconcept/title (view source)
Template:lines (view source) (protected)
Template:ls (view source)
Template:ltt (view source) (protected)
Template:ltt/core (view source) (protected)
Template:mark (view source) (protected)
Template:mark c++11 (view source) (protected)
Template:mark c++14 (view source) (protected)
Template:mark c++17 (view source) (protected)
Template:mark c++20 (view source)
Template:mark c++23 (view source) (protected)
Template:mark c++26 (view source)
Template:mark fun (view source) (protected)
Template:mark mem fun (view source) (protected)
Template:mark ptclass (view source) (protected)
Template:mark rev (view source) (protected)
Template:mark since c++11 (view source) (protected)
Template:mark since c++17 (view source)
Template:mark since c++20 (view source)
Template:mark tclass (view source)
Template:mark tfun (view source) (protected)
Template:mark tooltip (view source)
Template:mark until c++11 (view source) (protected)
Template:mark until c++20 (view source)
Template:named req (view source)
Template:named req/core (view source)
Template:navbar (view source)
Template:navbar editlink (view source) (protected)
Template:nbsp (view source) (protected)
Template:nbspt (view source)
Template:nv (view source) (protected)
Template:nv begin (view source) (protected)
Template:nv col begin (view source) (protected)
Template:nv col end (view source) (protected)
Template:nv col next (view source) (protected)
Template:nv end (view source) (protected)
Template:nv h1 (view source) (protected)
Template:nv h2 (view source) (protected)
Template:nv ln (view source) (protected)
Template:nv mem ln (view source) (protected)
Template:par (view source) (protected)
Template:par begin (view source) (protected)
Template:par end (view source) (protected)
Template:range (view source)
Template:range/core (view source)
Template:rev (view source) (protected)
Template:rev begin (view source)
Template:rev end (view source)
Template:rev inl (view source)
Template:rlt (view source) (protected)
Template:rrev (view source)
Template:rrev multi (view source)
Template:small (view source) (protected)
Template:source (view source) (protected)
Template:stddoc (view source)
Template:title (view source) (protected)
Template:tooltip (view source)
Template:trim (view source) (protected)
Template:tt (view source) (protected)
Template:wg21 (view source)

Return to cpp/string/basic string.

cppreference.com

Search

Namespaces

Variants

Views

Actions

View source for cpp/string/basic string

Navigation

Tools