basic_string():basic_string(Allocator()){} (1)(since C++11)
(until C++17)basic_string()noexcept(noexcept(Allocator())):basic_string(Allocator()){}(since C++17)
(constexpr since C++20)explicitbasic_string(constAllocator&alloc=Allocator()); (2)(until C++11)explicitbasic_string(constAllocator&alloc);(since C++11)
(noexcept since C++17)
(constexpr since C++20)basic_string(size_typecount,CharTch,constAllocator&alloc=Allocator()); (3)(constexpr since C++20)template<classInputIt>basic_string(InputItfirst,InputItlast,constAllocator&alloc=Allocator()); (4)(constexpr since C++20)template<container-compatible-range<CharT>R>constexprbasic_string(std::from_range_t,R&&rg,constAllocator&=Allocator()); (5)(since C++23)basic_string(constCharT*s,size_typecount,constAllocator&alloc=Allocator()); (6)(constexpr since C++20)basic_string(constCharT*s,constAllocator&alloc=Allocator()); (7)(constexpr since C++20)basic_string(std::nullptr_t)=delete; (8) (since C++23)template<classStringViewLike>explicitbasic_string(constStringViewLike&t,constAllocator&alloc=Allocator()); (9)(since C++17)
(constexpr since C++20)template<classStringViewLike>basic_string(constStringViewLike&t,size_typepos,size_typecount,constAllocator&alloc=Allocator()); (10) (since C++17)basic_string(constbasic_string&other); (11)(constexpr since C++20)basic_string(basic_string&&other)noexcept; (12)(since C++11)
(constexpr since C++20)basic_string(constbasic_string&other,constAllocator&alloc); (13)(since C++11)
(constexpr since C++20)basic_string(basic_string&&other,constAllocator&alloc); (14)(since C++11)
(constexpr since C++20)basic_string(constbasic_string&other,size_typepos,constAllocator&alloc=Allocator()); (15)(constexpr since C++20)constexprbasic_string(basic_string&&other,size_typepos,constAllocator&alloc=Allocator()); (16) (since C++23)basic_string(constbasic_string&other,size_typepos,size_typecount,constAllocator&alloc=Allocator()); (17)(constexpr since C++20)constexprbasic_string(basic_string&&other,size_typepos,size_typecount,constAllocator&alloc=Allocator()); (18) (since C++23)basic_string(std::initializer_list<CharT>ilist,constAllocator&alloc=Allocator()); (19)(since C++11)
(constexpr since C++20)Constructs new string from a variety of data sources and optionally using user supplied allocator alloc.
1) The default constructor since C++11. Constructs an empty string with a default-constructed allocator.
2) The default constructor until C++11. Constructs an empty string with the given allocator alloc.
3) Constructs a string with count copies of character ch.
If CharT is not
into std::basic_string<CharT>, the behavior is undefined.
(since C++11)This overload participates in overload resolution only if Allocator satisfies the requirements of
.
(since C++17)4) Constructs a string with the contents of the range [first, last). Each iterator in [first, last) is dereferenced exactly once.
If InputIt does not satisfy the requirements of
, overload (3) is called instead with arguments static_cast<size_type>(first), last and alloc.
(until C++11)This overload participates in overload resolution only if InputIt satisfies the requirements of
.
If CharT is not
into std::basic_string<CharT> from *first, the behavior is undefined.
(since C++11)5) Constructs a string with the contents of the range rg. Each iterator in rg is dereferenced exactly once.
If CharT is not
into std::basic_string<CharT> from *ranges::begin(rg), the behavior is undefined.
6) Constructs a string with the contents of the range [s, s+count).
If [s, s+count) is not a valid range, the behavior is undefined.
7) Equivalent to basic_string(s,Traits::length(s),alloc).
This overload participates in overload resolution only if Allocator satisfies the requirements of
.
(since C++17)8)std::basic_string cannot be constructed from nullptr.
9) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT,Traits>sv=t;, then constructs a string as if by basic_string(sv.data(),sv.size(),alloc).
This overload participates in overload resolution only if std::is_convertible_v<constStringViewLike&,std::basic_string_view<CharT,Traits>> is true and std::is_convertible_v<constStringViewLike&,constCharT*> is false.
10) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT,Traits>sv=t;, then constructs a string as if by basic_string(sv.substr(pos,n),alloc).
This overload participates in overload resolution only if std::is_convertible_v<constStringViewLike&,std::basic_string_view<CharT,Traits>> is true.
11-18) Constructs a string with (part of) the contents of other. If the type of other is basic_string&&, when the construction finishes, other is in a valid but unspecified state.
11) The copy constructor.
The allocator is obtained as if by calling
std::allocator_traits<Allocator>::select_on_container_copy_construction(other.get_allocator())(since C++11)12) The move constructor. The allocator is obtained by move construction from other.get_allocator().
13) Same as the copy constructor, except that alloc is used as the allocator.
If CharT is not
into std::basic_string<CharT>, the behavior is undefined.
14) Same as the move constructor, except that alloc is used as the allocator.
If CharT is not
into std::basic_string<CharT>, the behavior is undefined.
15,16) Constructs a string with the contents of the range [other.data()+pos, other.data()+other.size()).
17,18) Constructs a string with the contents of the range [other.data()+pos, other.data()+(pos+std::min(count,other.size()-pos))).
19) Equivalent to basic_string(ilist.begin(),ilist.end()).
Parameters
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 -
to initialize the string with t - object (convertible to
) to initialize the string with rg - a container compatible range Complexity
1,2) Constant.
3-7) Linear in the size of the string.
9-11) Linear in the size of the string.
12) Constant.
13) Linear in the size of the string.
14) Linear in the size of the string if alloc!=other.get_allocator() is true, otherwise constant.
15-19) Linear in the size of the string.
Exceptions
14) Throws nothing if alloc==str.get_allocator() is true.
Throws
if the length of the constructed string would exceed
(for example, if count>max_size() for (
)). Calls to Allocator::allocate may throw.
If an exception is thrown for any reason, these functions have no effect (
strong exception safety guarantee
).
Notes
Initialization with a
that contains embedded '\0' characters uses the overload (
), which stops at the first null character. This can be avoided by specifying a different constructor or by using
:
std::strings1="ab\0\0cd";// s1 contains "ab"std::strings2{"ab\0\0cd",6};// s2 contains "ab\0\0cd"std::strings3="ab\0\0cd"s;// s3 contains "ab\0\0cd"
macroValueStdFeature
(C++23)Tagged constructor (
) to construct from
Example
Run this code
#include<cassert>#include<cctype>#include<iomanip>#include<iostream>#include<iterator>#include<string>intmain(){std::cout<<"1) string(); ";std::strings1;assert(s1.empty()&&(s1.length()==0)&&(s1.size()==0));std::cout<<"s1.capacity(): "<<s1.capacity()<<'\n';// unspecifiedstd::cout<<"3) string(size_type count, CharT ch): ";std::strings2(4,'=');std::cout<<std::quoted(s2)<<'\n';// "===="std::cout<<"4) string(InputIt first, InputIt last): ";charmutable_c_str[]="another C-style string";std::strings4(std::begin(mutable_c_str)+8,std::end(mutable_c_str)-1);std::cout<<std::quoted(s4)<<'\n';// "C-style string"std::cout<<"6) string(CharT const* s, size_type count): ";std::strings6("C-style string",7);std::cout<<std::quoted(s6)<<'\n';// "C-style", i.e. [0, 7)std::cout<<"7) string(CharT const* s): ";std::strings7("C-style\0string");std::cout<<std::quoted(s7)<<'\n';// "C-style"std::cout<<"11) string(string&): ";std::stringconstother11("Exemplar");std::strings11(other11);std::cout<<std::quoted(s11)<<'\n';// "Exemplar"std::cout<<"12) string(string&&): ";std::strings12(std::string("C++ by ")+std::string("example"));std::cout<<std::quoted(s12)<<'\n';// "C++ by example"std::cout<<"15) string(const string& other, size_type pos): ";std::stringconstother15("Mutatis Mutandis");std::strings15(other15,8);std::cout<<std::quoted(s15)<<'\n';// "Mutandis", i.e. [8, 16)std::cout<<"17) string(const string& other, size_type pos, size_type count): ";std::stringconstother17("Exemplary");std::strings17(other17,0,other17.length()-1);std::cout<<std::quoted(s17)<<'\n';// "Exemplar"std::cout<<"19) string(std::initializer_list<CharT>): ";std::strings19({'C','-','s','t','y','l','e'});std::cout<<std::quoted(s19)<<'\n';// "C-style"}Possible output:
1) string(); s1.capacity(): 15 3) string(size_type count, CharT ch): "====" 4) string(InputIt first, InputIt last): "C-style string" 6) string(CharT const* s, size_type count): "C-style" 7) string(CharT const* s): "C-style" 11) string(string&): "Exemplar" 12) string(string&&): "C++ by example" 15) string(const string& other, size_type pos): "Mutandis" 17) string(const string& other, size_type pos, size_type count): "Exemplar" 19) string(std::initializer_list<CharT>): "C-style" 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 overload (
) did not use the parameter
alloc if InputIt is an integral type use that parameter
C++98 overload (
) would only call overload (
)
if InputIt is an integral type calls overload (
) if InputIt
is not an
C++98 there was no exception safety guarantee added strong exception safety guarantee
C++11 the default constructor is explicit made non-explicit
C++98 s could be a null pointer value the behavior is undefined in this case
C++98 the behavior of overload (
) was undefined
if pos>other.size() is truealways throws an
exception in this case
C++98 there was no way to supply an allocator for overload (
)added overload (
)
C++17 overload (
) causes ambiguity in some cases avoided by making it a template
C++17 overloads (
)and (
) might cause ambiguities
in class template argument deduction constrained
(
) C++98 the resolution of
made the
behavior of basic_string(nullptr,0) undefined the behavior is well-
defined in this case
[nullptr, nullptr+0) is a valid empty range, because adding zero to a null pointer value is also
(the result is still a null pointer value).
See also
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)
constructs a basic_string_view
(public member function of std::basic_string_view<CharT,Traits>)