|
|
| Line 1: |
Line 1: |
| − | {{cpp/title|basic_string}}
| + | #REDIRECT [[enwiki:Rust_(programming_language)]] |
| − | {{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 [[cpp/named req/TrivialType|trivial]] [[cpp/named req/StandardLayoutType|standard-layout]] type. 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. {{tt|Traits::char_type}} and {{tt|CharT}} must name the same type; otherwise the program is ill-formed. {{mark unreviewed dr|LWG|P1148}}
| + | |
| − | | + | |
| − | 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}}}}.
| + | |
| − | | + | |
| − | {{rrev|since=c++20|
| + | |
| − | Member functions of {{tt|std::basic_string}} are {{c/core|constexpr}}: it is possible to create and use {{tt|std::string}} objects in the evaluation of a constant expression.
| + | |
| − | | + | |
| − | However, {{tt|std::string}} objects generally cannot be {{c/core|constexpr}}, because any dynamically allocated storage must be released in the same evaluation of constant expression.
| + | |
| − | }}
| + | |
| − | | + | |
| − | Several typedefs for common character types are provided:
| + | |
| − | {{dsc begin}}
| + | |
| − | {{dsc header|string}}
| + | |
| − | {{dsc hitem|Type|Definition}}
| + | |
| − | {{dsc|{{lc|std::string}}|{{c/core|std::basic_string<char>}}}}
| + | |
| − | {{dsc|{{lc|std::wstring}}|{{c/core|std::basic_string<wchar_t>}}}}
| + | |
| − | {{dsc|{{lc|std::u8string}} {{mark c++20}}|{{c/core|std::basic_string<char8_t>}}}}
| + | |
| − | {{dsc|{{lc|std::u16string}} {{mark c++11}}|{{c/core|std::basic_string<char16_t>}}}}
| + | |
| − | {{dsc|{{lc|std::u32string}} {{mark c++11}}|{{c/core|std::basic_string<char32_t>}}}}
| + | |
| − | {{dsc|{{lc|std::pmr::string}} {{mark c++17}}|{{c/core|std::pmr::basic_string<char>}}}}
| + | |
| − | {{dsc|{{lc|std::pmr::wstring}} {{mark c++17}}|{{c/core|std::pmr::basic_string<wchar_t>}}}}
| + | |
| − | {{dsc|{{lc|std::pmr::u8string}} {{mark c++20}}|{{c/core|std::pmr::basic_string<char8_t>}}}}
| + | |
| − | {{dsc|{{lc|std::pmr::u16string}} {{mark c++17}}|{{c/core|std::pmr::basic_string<char16_t>}}}}
| + | |
| − | {{dsc|{{lc|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}}
| + | |
| − | | + | |
| − | ===Member types===
| + | |
| − | {{dsc begin}}
| + | |
| − | {{dsc hitem|Member type|Definition}}
| + | |
| − | {{dsc|{{tt|traits_type}}|{{tt|Traits}}}}
| + | |
| − | {{dsc|{{tt|value_type}}|{{tt|CharT}}{{mark unreviewed dr|LWG|2861}}}}
| + | |
| − | {{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}}
| + | |
| − | | + | |
| − | ===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|Operations}}
| + | |
| − | {{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 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 replace}}
| + | |
| − | {{dsc inc|cpp/string/basic_string/dsc replace_with_range}}
| + | |
| − | {{dsc inc|cpp/string/basic_string/dsc substr}}
| + | |
| − | {{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 h1|Constants}}
| + | |
| − | {{dsc inc|cpp/string/basic_string/dsc npos}}
| + | |
| − | {{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}}===
| + | |
| − | | + | |
| − | ===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++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|__cpp_lib_containers_ranges|value=202202L|std=C++23|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}} was not required|after=required}}
| + | |
| − | {{dr list end}}
| + | |
| − | | + | |
| − | ===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}}
| + | |
