(1) | ||
basic_string(); explicit basic_string( const Allocator& alloc ); | (until C++17) | |
basic_string() noexcept(noexcept( Allocator() )) : basic_string( Allocator() ) {} explicit basic_string( const Allocator& alloc ) noexcept; | (since C++17) (until C++20) | |
constexpr basic_string() noexcept(noexcept( Allocator() )) : basic_string( Allocator() ) {} constexpr explicit basic_string( const Allocator& alloc ) noexcept; | (since C++20) | |
(2) | ||
basic_string( size_type count, CharT ch, const Allocator& alloc = Allocator() ); | (until C++20) | |
constexpr basic_string( size_type count, CharT ch, const Allocator& alloc = Allocator() ); | (since C++20) | |
(3) | ||
basic_string( const basic_string& other, size_type pos, const Allocator& alloc = Allocator() ); | (until C++20) | |
constexpr basic_string( const basic_string& other, size_type pos, const Allocator& alloc = Allocator() ); | (since C++20) | |
constexpr basic_string( basic_string&& other, size_type pos, const Allocator& alloc = Allocator() ); | (3) | (since C++23) |
(3) | ||
basic_string( const basic_string& other, size_type pos, size_type count, const Allocator& alloc = Allocator() ); | (until C++20) | |
constexpr basic_string( const basic_string& other, size_type pos, size_type count, const Allocator& alloc = Allocator() ); | (since C++20) | |
constexpr basic_string( basic_string&& other, size_type pos, size_type count, const Allocator& alloc = Allocator() ); | (3) | (since C++23) |
(4) | ||
basic_string( const CharT* s, size_type count, const Allocator& alloc = Allocator() ); | (until C++20) | |
constexpr basic_string( const CharT* s, size_type count, const Allocator& alloc = Allocator() ); | (since C++20) | |
(5) | ||
basic_string( const CharT* s, const Allocator& alloc = Allocator() ); | (until C++20) | |
constexpr basic_string( const CharT* s, const Allocator& alloc = Allocator() ); | (since C++20) | |
(6) | ||
template< class InputIt > basic_string( InputIt first, InputIt last, const Allocator& alloc = Allocator() ); | (until C++20) | |
template< class InputIt > constexpr basic_string( InputIt first, InputIt last, const Allocator& alloc = Allocator() ); | (since C++20) | |
(7) | ||
basic_string( const basic_string& other ); | (until C++20) | |
constexpr basic_string( const basic_string& other ); | (since C++20) | |
(7) | ||
basic_string( const basic_string& other, const Allocator& alloc ); | (since C++11) (until C++20) | |
constexpr basic_string( const basic_string& other, const Allocator& alloc ); | (since C++20) | |
(8) | ||
basic_string( basic_string&& other ) noexcept; | (since C++11) (until C++20) | |
constexpr basic_string( basic_string&& other ) noexcept; | (since C++20) | |
(8) | ||
basic_string( basic_string&& other, const Allocator& alloc ); | (since C++11) (until C++20) | |
constexpr basic_string( basic_string&& other, const Allocator& alloc ); | (since C++20) | |
(9) | ||
basic_string( std::initializer_list<CharT> ilist, const Allocator& alloc = Allocator() ); | (since C++11) (until C++20) | |
constexpr basic_string( std::initializer_list<CharT> ilist, const Allocator& alloc = Allocator() ); | (since C++20) | |
(10) | ||
template< class StringViewLike > explicit basic_string( const StringViewLike& t, const Allocator& alloc = Allocator() ); | (since C++17) (until C++20) | |
template< class StringViewLike > constexpr explicit basic_string( const StringViewLike& t, const Allocator& alloc = Allocator() ); | (since C++20) | |
(11) | ||
template< class StringViewLike > basic_string( const StringViewLike& t, size_type pos, size_type n, const Allocator& alloc = Allocator() ); | (since C++17) (until C++20) | |
template< class StringViewLike > constexpr basic_string( const StringViewLike& t, size_type pos, size_type n, const Allocator& alloc = Allocator() ); | (since C++20) | |
basic_string( std::nullptr_t ) = delete; | (12) | (since C++23) |
template< container-compatible-range<CharT> R > constexpr basic_string( std::from_range_t, R&& rg, const Allocator& = Allocator()); | (13) | (since C++23) |
Constructs new string from a variety of data sources and optionally using user supplied allocator alloc
.
count
copies of character ch
. This constructor is not used for class template argument deduction if the Allocator
type that would be deduced does not qualify as an allocator. (since C++17)
[
pos
,
pos + count
)
of other
. If count == npos
, if count
is not specified, or if the requested substring lasts past the end of the string, the resulting substring is [
pos
,
other.size()
)
. If other
is an rvalue reference, it is left in a valid but unspecified state. (since C++23)
count
characters of character string pointed to by s
. s
can contain null characters. The length of the string is count
. The behavior is undefined if [
s
,
s + count
)
is not a valid range.s
. The length of the string is determined by the first null character. The behavior is undefined if [
s
,
s + Traits::length(s)
)
is not a valid range (for example, if s
is a null pointer). This constructor is not used for class template argument deduction if the Allocator
type that would be deduced does not qualify as an allocator. (since C++17)
[
first
,
last
)
. If | (until C++11) |
This constructor only participates in overload resolution if | (since C++11) |
other
.other
using move semantics. other
is left in valid, but unspecified state.ilist
. t
to a string view sv
as if by std::basic_string_view<CharT, Traits> sv = t;
, then initializes the string with the contents of sv
, as if by basic_string(sv.data(), sv.size(), alloc)
.std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>>
is true
and std::is_convertible_v<const StringViewLike&, const CharT*>
is false
. t
to a string view sv
as if by std::basic_string_view<CharT, Traits> sv = t;
, then initializes the string with the subrange [
pos
,
pos + n
)
of sv
as if by basic_string(sv.substr(pos, n), alloc)
.std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>>
is true
.std::basic_string
cannot be constructed from nullptr
.rg
.alloc | - | allocator to use for all memory allocations of this string |
count | - | size of the resulting string |
ch | - | value to initialize the string with |
pos | - | position of the first character to include |
first, last | - | range to copy the characters from |
s | - | pointer to an array of characters to use as source to initialize the string with |
other | - | another string to use as source to initialize the string with |
ilist | - | std::initializer_list to initialize the string with |
t | - | object (convertible to std::basic_string_view ) to initialize the string with |
rg | - | a container compatible range |
count
.s
.first
and last
.other
.alloc
is given and alloc != other.get_allocator()
, then linear.ilist
.rg
.alloc == str.get_allocator()
.Throws std::length_error
if the length of the constructed string would exceed max_size()
(for example, if count > max_size()
for (2)). Calls to Allocator::allocate
may throw.
If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).
Initialization with a string literal that contains embedded '\0'
characters uses the overload (5), which stops at the first null character. This can be avoided by specifying a different constructor or by using operator""s
:
std::string s1 = "ab\0\0cd"; // s1 contains "ab" std::string s2{"ab\0\0cd", 6}; // s2 contains "ab\0\0cd" std::string s3 = "ab\0\0cd"s; // s3 contains "ab\0\0cd"
Feature-test macro | Value | Std | Comment |
---|---|---|---|
__cpp_lib_containers_ranges | 202202L | (C++23) | Tagged constructor (13) to construct from container compatible range |
#include <cassert> #include <cctype> #include <iomanip> #include <iostream> #include <iterator> #include <string> int main() { std::cout << "1) string(); "; std::string s1; assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0)); std::cout << "s1.capacity(): " << s1.capacity() << '\n'; // unspecified std::cout << "2) string(size_type count, CharT ch): "; std::string s2(4, '='); std::cout << std::quoted(s2) << '\n'; // "====" std::cout << "3) string(const string& other, size_type pos, size_type count): "; std::string const other3("Exemplary"); std::string s3(other3, 0, other3.length() - 1); std::cout << std::quoted(s3) << '\n'; // "Exemplar" std::cout << "4) string(const string& other, size_type pos): "; std::string const other4("Mutatis Mutandis"); std::string s4(other4, 8); std::cout << std::quoted(s4) << '\n'; // "Mutandis", i.e. [8, 16) std::cout << "5) string(CharT const* s, size_type count): "; std::string s5("C-style string", 7); std::cout << std::quoted(s5) << '\n'; // "C-style", i.e. [0, 7) std::cout << "6) string(CharT const* s): "; std::string s6("C-style\0string"); std::cout << std::quoted(s6) << '\n'; // "C-style" std::cout << "7) string(InputIt first, InputIt last): "; char mutable_c_str[] = "another C-style string"; std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1); std::cout << std::quoted(s7) << '\n'; // "C-style string" std::cout << "8) string(string&): "; std::string const other8("Exemplar"); std::string s8(other8); std::cout << std::quoted(s8) << '\n'; // "Exemplar" std::cout << "9) string(string&&): "; std::string s9(std::string("C++ by ") + std::string("example")); std::cout << std::quoted(s9) << '\n'; // "C++ by example" std::cout << "a) string(std::initializer_list<CharT>): "; std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'}); std::cout << std::quoted(sa) << '\n'; // "C-style" // before C++11, overload resolution selects string(InputIt first, InputIt last) // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch) // after C++11 the InputIt constructor is disabled for integral types and calls: std::cout << "b) string(size_type count, CharT ch) is called: "; std::string sb(3, std::toupper('a')); std::cout << std::quoted(sb) << '\n'; // "AAA" [[maybe_unused]] auto zero = [] { /* ... */ return nullptr; }; // std::string sc{zero()}; // Before C++23: throws std::logic_error // Since C++23: won't compile, see overload (12) // TODO: overload (13) - range-aware construction }
Possible output:
1) string(); s1.capacity(): 15 2) string(size_type count, CharT ch): "====" 3) string(const string& other, size_type pos, size_type count): "Exemplar" 4) string(const string& other, size_type pos): "Mutandis" 5) string(CharT const* s, size_type count): "C-style" 6) string(CharT const* s): "C-style" 7) string(InputIt first, InputIt last): "C-style string" 8) string(string&): "Exemplar" 9) string(string&&): "C++ by example" a) string(std::initializer_list<CharT>): "C-style" b) string(size_type count, CharT ch) is called: "AAA"
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 301 | C++98 | overload (6) did not use the parameteralloc if InputIt is an integral type | use that parameter |
LWG 847 | C++98 | there was no exception safety guarantee | added strong exception safety guarantee |
LWG 2193 | C++11 | the default constructor is explicit | made non-explicit |
LWG 2583 | C++98 | there is no way to supply an allocator for basic_string(str, pos) | there is a constructor forbasic_string(str, pos, alloc) |
LWG 2946 | C++17 | overload (10) causes ambiguity in some cases | avoided by making it a template |
LWG 3076 | C++17 | two constructors may cause ambiguities in class template argument deduction | constrained |
assign characters to a string (public member function) |
|
assigns values to the string (public member 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) |
(C++17) | constructs a basic_string_view (public member function of std::basic_string_view<CharT,Traits> ) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/string/basic_string/basic_string