Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/string/basic string/basic string"

From cppreference.com
< cpp‎ | string‎ | basic string
m (@10@ fix (2) => (3).)
(Overhauled the description: 1. Rearranged the overloads (including the example). 2. Merged preconditions from the container requirements. 3. Added LWG438 DR.)
 
Line 2: Line 2:
 
{{cpp/string/basic_string/navbar}}
 
{{cpp/string/basic_string/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl rev multi|num=1|until1=c++17|dcl1=
+
{{dcl rev begin|num=1}}
−
basic_string();
+
{{dcla|since=c++11|until=c++17|
−
|notes2={{mark constexpr since c++20}}|dcl2=
+
basic_string() : basic_string(Allocator()) {}
 +
}}
 +
{{dcla|since=c++17|constexpr=c++20|
 
basic_string() noexcept(noexcept(Allocator()))
 
basic_string() noexcept(noexcept(Allocator()))
−
     : basic_string( Allocator() ) {}
+
     : basic_string(Allocator()) {}
 
}}
 
}}
−
{{dcl|num=2|notes={{mark noexcept since c++17}}<br>{{mark constexpr since c++20}}|
+
{{dcl rev end}}
 +
{{dcl rev begin|num=2}}
 +
{{dcla|until=c++11|1=
 +
explicit basic_string( const Allocator& alloc = Allocator() );
 +
}}
 +
{{dcla|noexcept=c++17|constexpr=c++20|
 
explicit basic_string( const Allocator& alloc );
 
explicit basic_string( const Allocator& alloc );
 
}}
 
}}
−
{{dcla|num=3|notes={{mark constexpr since c++20}}|1=
+
{{dcl rev end}}
 +
{{dcla|num=3|constexpr=c++20|1=
 
basic_string( size_type count, CharT ch,
 
basic_string( size_type count, CharT ch,
 
               const Allocator& alloc = Allocator() );
 
               const Allocator& alloc = Allocator() );
 
}}
 
}}
−
{{dcl|num=4|notes={{mark constexpr since c++20}}|1=
+
{{dcla|num=4|constexpr=c++20|1=
−
basic_string( const basic_string& other, size_type pos,
+
template< class InputIt >
 +
basic_string( InputIt first, InputIt last,
 
               const Allocator& alloc = Allocator() );
 
               const Allocator& alloc = Allocator() );
 
}}
 
}}
 
{{dcl|num=5|since=c++23|1=
 
{{dcl|num=5|since=c++23|1=
−
constexpr basic_string( basic_string&& other, size_type pos,
+
template< container-compatible-range<CharT> R >
−
                         const Allocator& alloc = Allocator() );
+
constexpr basic_string( std::from_range_t, R&& rg,
 +
                         const Allocator& = Allocator());
 
}}
 
}}
−
{{dcl|num=6|since=c++23|1=
+
{{dcla|num=6|constexpr=c++20|1=
−
basic_string( const basic_string& other,
+
−
              size_type pos, size_type count,
+
−
              const Allocator& alloc = Allocator() );
+
−
}}
+
−
{{dcl|num=7|since=c++23|1=
+
−
constexpr basic_string( basic_string&& other,
+
−
                        size_type pos, size_type count,
+
−
                        const Allocator& alloc = Allocator() );
+
−
}}
+
−
{{dcl|num=8|notes={{mark constexpr since c++20}}|1=
+
 
basic_string( const CharT* s, size_type count,
 
basic_string( const CharT* s, size_type count,
 
               const Allocator& alloc = Allocator() );
 
               const Allocator& alloc = Allocator() );
 
}}
 
}}
−
{{dcla|num=9|notes={{mark constexpr since c++20}}|1=
+
{{dcla|num=7|constexpr=c++20|1=
 
basic_string( const CharT* s, const Allocator& alloc = Allocator() );
 
basic_string( const CharT* s, const Allocator& alloc = Allocator() );
 
}}
 
}}
−
{{dcla|num=10|notes={{mark constexpr since c++20}}|1=
+
{{dcl|num=8|since=c++23|1=
−
template< class InputIt >
+
basic_string( std::nullptr_t ) = delete;
−
basic_string( InputIt first, InputIt last,
+
}}
 +
{{dcla|num=9|since=c++17|constexpr=c++20|1=
 +
template< class StringViewLike >
 +
explicit basic_string( const StringViewLike& t,
 +
                      const Allocator& alloc = Allocator() );
 +
}}
 +
{{dcl|num=10|since=c++17|constexpr=c++20|1=
 +
template< class StringViewLike >
 +
basic_string( const StringViewLike& t,
 +
              size_type pos, size_type count,
 
               const Allocator& alloc = Allocator() );
 
               const Allocator& alloc = Allocator() );
 
}}
 
}}
−
{{dcl|num=11|notes={{mark constexpr since c++20}}|
+
{{dcla|num=11|constexpr=c++20|
 
basic_string( const basic_string& other );
 
basic_string( const basic_string& other );
 
}}
 
}}
−
{{dcl|num=12|since=c++11|notes={{mark constexpr since c++20}}|
+
{{dcla|num=12|since=c++11|constexpr=c++20|
 +
basic_string( basic_string&& other ) noexcept;
 +
}}
 +
{{dcla|num=13|since=c++11|constexpr=c++20|
 
basic_string( const basic_string& other, const Allocator& alloc );
 
basic_string( const basic_string& other, const Allocator& alloc );
 
}}
 
}}
−
{{dcl|num=13|since=c++11|notes={{mark constexpr since c++20}}|
+
{{dcla|num=14|since=c++11|constexpr=c++20|
−
basic_string( basic_string&& other ) noexcept;
+
−
}}
+
−
{{dcl|num=14|since=c++11|notes={{mark constexpr since c++20}}|
+
 
basic_string( basic_string&& other, const Allocator& alloc );
 
basic_string( basic_string&& other, const Allocator& alloc );
 
}}
 
}}
−
{{dcl|num=15|since=c++11|notes={{mark constexpr since c++20}}|1=
+
{{dcla|num=15|constexpr=c++20|1=
−
basic_string( std::initializer_list<CharT> ilist,
+
basic_string( const basic_string& other, size_type pos,
 
               const Allocator& alloc = Allocator() );
 
               const Allocator& alloc = Allocator() );
 
}}
 
}}
−
{{dcla|num=16|since=c++17|notes={{mark constexpr since c++20}}|1=
+
{{dcl|num=16|since=c++23|1=
−
template< class StringViewLike >
+
constexpr basic_string( basic_string&& other, size_type pos,
−
explicit basic_string( const StringViewLike& t,
+
                        const Allocator& alloc = Allocator() );
−
                      const Allocator& alloc = Allocator() );
+
 
}}
 
}}
−
{{dcl|num=17|since=c++17|notes={{mark constexpr since c++20}}|1=
+
{{dcla|num=17|constexpr=c++20|1=
−
template< class StringViewLike >
+
basic_string( const basic_string& other,
−
basic_string( const StringViewLike& t, size_type pos, size_type n,
+
              size_type pos, size_type count,
 
               const Allocator& alloc = Allocator() );
 
               const Allocator& alloc = Allocator() );
 
}}
 
}}
 
{{dcl|num=18|since=c++23|1=
 
{{dcl|num=18|since=c++23|1=
−
basic_string( std::nullptr_t ) = delete;
+
constexpr basic_string( basic_string&& other,
 +
                        size_type pos, size_type count,
 +
                        const Allocator& alloc = Allocator() );
 
}}
 
}}
−
{{dcla|num=19|since=c++23|1=
+
{{dcla|num=19|since=c++11|constexpr=c++20|1=
−
template< container-compatible-range<CharT> R >
+
basic_string( std::initializer_list<CharT> ilist,
−
constexpr basic_string( std::from_range_t, R&& rg,
+
              const Allocator& alloc = Allocator() );
−
                        const Allocator& = Allocator());
+
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
Line 83: Line 92:
 
Constructs new string from a variety of data sources and optionally using user supplied allocator {{c|alloc}}.
 
Constructs new string from a variety of data sources and optionally using user supplied allocator {{c|alloc}}.
  
−
@1,2@ Default constructor. Constructs empty string (of zero size and unspecified capacity). If no allocator is supplied, allocator is obtained from a default-constructed instance.
+
@1@ The default constructor since C++11. Constructs an empty string with a default-constructed allocator.
−
@3@ Constructs the string with {{c|count}} copies of character {{c|ch}}. {{rev inl|since=c++17|This constructor is not used for [[cpp/language/class template argument deduction|class template argument deduction]] if the {{tt|Allocator}} type that would be deduced does not qualify as an allocator. <!-- LWG 3076 -->}}
+
@@ If Allocator is not {{named req|DefaultConstructible}}, the behavior is undefined.
−
@4-7@ Constructs the string with a substring {{range|pos|pos + count}} of {{c|other}}. If {{c|1=count == npos}}, if {{c|count}} is not specified, or if the requested substring lasts past the end of the string, the resulting substring is {{range|pos|other.size()}}. {{rev inl|since=c++23|If {{c|other}} is an rvalue reference, it is left in a valid but unspecified state.}}
+
 
−
@8@ Constructs the string with the first {{c|count}} characters of character string pointed to by {{c|s}}. {{c|s}} can contain null characters. The length of the string is {{c|count}}. The behavior is undefined if {{range|s|s + count}} is not a valid range.
+
@2@ The default constructor until C++11. Constructs an empty string with the given allocator {{c|alloc}}.
−
@9@ Constructs the string with the contents initialized with a copy of the null-terminated character string pointed to by {{c|s}}. The length of the string is determined by the first null character. The behavior is undefined if {{range|s|s + Traits::length(s)}} is not a [[cpp/iterator#Ranges|valid range]] (for example, if {{c|s}} is a null pointer). {{rev inl|since=c++17|This constructor is not used for [[cpp/language/class template argument deduction|class template argument deduction]] if the {{tt|Allocator}} type that would be deduced does not qualify as an allocator. <!-- LWG 3076 -->}}
+
 
−
@10@ Constructs the string  with the contents of the range {{range|first|last}}.
+
@3@ Constructs a string with {{c|count}} copies of character {{c|ch}}.
−
{{rrev multi|until1=c++11|rev1=If {{tt|InputIt}} is an integral type, equivalent to overload {{vl|3}}, as if by {{c multi|basic_string(static_cast<size_type>(first),|
+
{{rev begin}}
−
            static_cast<value_type>(last), alloc)}}.
+
{{rev|since=c++11|
−
|rev2=This constructor only participates in overload resolution if {{tt|InputIt}} satisfies {{named req|InputIterator}}.}}
+
If {{tt|CharT}} is not {{named req|CopyInsertable}} into {{c/core|std::basic_string<CharT>}}, the behavior is undefined.
−
@11,12@ Copy constructor. Constructs the string with a copy of the contents of {{c|other}}.
+
}}
−
@13,14@ Move constructor. Constructs the string with the contents of {{c|other}} using move semantics. {{c|other}} is left in valid, but unspecified state.
+
{{rev|since=c++17|
−
@15@ Constructs the string with the contents of the initializer list {{c|ilist}}.
+
{{cpp/enable if|{{tt|Allocator}} satisfies the requirements of {{named req|Allocator}}}}.
−
@16@ {{cpp/string/sv hack|initializes the string with the contents of {{c|sv}}, as if by {{c|basic_string(sv.data(), sv.size(), alloc)}}}}
+
}}
−
@17@ {{cpp/string/sv hack|checkptr=no|initializes the string with the subrange {{range|pos|pos + n}} of {{c|sv}} as if by {{c|basic_string(sv.substr(pos, n), alloc)}}}}
+
{{rev end}}
−
@18@ {{tt|std::basic_string}} cannot be constructed from {{c|nullptr}}.
+
 
−
@19@ Constructs the string with the values contained in the range {{c|rg}}.
+
@4@ Constructs a string with the contents of the range {{range|first|last}}. Each iterator in {{range|first|last}} is dereferenced exactly once.
 +
{{rev begin}}
 +
{{rev|until=c++11|
 +
If {{tt|InputIt}} does not satisfy the requirements of {{named req|InputIterator}}, overload {{v|3}} is called instead with arguments {{c|static_cast<size_type>(first)}}, {{c|last}} and {{c|alloc}}.
 +
}}
 +
{{rev|since=c++11|
 +
{{cpp/enable if|{{tt|InputIt}} satisfies the requirements of {{named req|InputIterator}}}}.
 +
 
 +
If {{tt|CharT}} is not {{named req|EmplaceConstructible}} into {{c/core|std::basic_string<CharT>}} from {{c|*first}}, the behavior is undefined.
 +
}}
 +
{{rev end}}
 +
 
 +
@5@ Constructs a string with the contents of the range {{c|rg}}. Each iterator in {{c|rg}} is dereferenced exactly once.
 +
@@ If {{tt|CharT}} is not {{named req|EmplaceConstructible}} into {{c/core|std::basic_string<CharT>}} from {{c|*ranges::begin(rg)}}, the behavior is undefined.
 +
 
 +
@6@ Constructs a string with the contents of the range {{range|s|s + count}}.
 +
@@ If {{range|s|s + count}} is not a valid range, the behavior is undefined.
 +
 
 +
@7@ Equivalent to {{c|basic_string(s, Traits::length(s), alloc)}}.
 +
{{rrev|since=c++17|
 +
{{cpp/enable if|{{tt|Allocator}} satisfies the requirements of {{named req|Allocator}}}}.
 +
}}
 +
 
 +
@8@ {{tt|std::basic_string}} cannot be constructed from {{c|nullptr}}.
 +
 
 +
@9@ {{cpp/string/sv hack|constructs a string as if by {{c|basic_string(sv.data(), sv.size(), alloc)}}}}
 +
 
 +
@10@ {{cpp/string/sv hack|checkptr=no|constructs a string as if by {{c|basic_string(sv.substr(pos, n), alloc)}}}}
 +
 
 +
@11-18@ Constructs a string with (part of) the contents of {{c|other}}. If the type of {{c|other}} is {{tt|basic_string&&}}, when the construction finishes, {{c|other}} is in a valid but unspecified state.
 +
 
 +
:@11@ The copy constructor.
 +
{{rrev|since=c++11|
 +
The allocator is obtained as if by calling {{c multi|std::allocator_traits<Allocator>::|    select_on_container_copy_construction|        (other.get_allocator())}}.
 +
}}
 +
 
 +
:@12@ The move constructor. The allocator is obtained by move construction from {{c|other.get_allocator()}}.
 +
 
 +
:@13@ Same as the copy constructor, except that {{c|alloc}} is used as the allocator.
 +
:@@ If {{tt|CharT}} is not {{named req|CopyInsertable}} into {{c/core|std::basic_string<CharT>}}, the behavior is undefined.
 +
 
 +
:@14@ Same as the move constructor, except that {{c|alloc}} is used as the allocator.
 +
:@@ If {{tt|CharT}} is not {{named req|MoveInsertable}} into {{c/core|std::basic_string<CharT>}}, the behavior is undefined.
 +
 
 +
:@15,16@ Constructs a string with the contents of the range {{range|other.data() + pos|other.data() + other.size()}}.
 +
 
 +
:@17,18@ Constructs a string with the contents of the range {{range|other.data() + pos|other.data() + (pos + std::min(count, other.size() - pos))}}.
 +
 
 +
@19@ Equivalent to {{c|basic_string(ilist.begin(), ilist.end())}}.
  
 
===Parameters===
 
===Parameters===
Line 111: Line 168:
 
{{par|ilist|{{lc|std::initializer_list}} to initialize the string with}}
 
{{par|ilist|{{lc|std::initializer_list}} to initialize the string with}}
 
{{par|t|object (convertible to {{lc|std::basic_string_view}}) to initialize the string with}}
 
{{par|t|object (convertible to {{lc|std::basic_string_view}}) to initialize the string with}}
−
{{par|rg|a {{ls|cpp/ranges/to#container compatible range}}}}
+
{{par|rg|a container compatible range}}
 
{{par end}}
 
{{par end}}
  
 
===Complexity===
 
===Complexity===
 
@1,2@ Constant.
 
@1,2@ Constant.
−
@3-8@ Linear in {{c|count}}.
+
 
−
@9@ Linear in length of {{c|s}}.
+
@3-7@ Linear in the size of the string.
−
@10@ Linear in distance between {{c|first}} and {{c|last}}.
+
 
−
@11,12@ Linear in size of {{c|other}}.
+
@9-11@ Linear in the size of the string.
−
@13@ Constant.
+
 
−
@14@ Constant. If {{c|alloc}} is given and {{c|1=alloc != other.get_allocator()}}, then linear.
+
@12@ Constant.
−
@15@ Linear in size of {{c|ilist}}.
+
 
−
@16@ Linear in size of {{c|t}}.
+
@13@ Linear in the size of the string.
−
@17@ Linear in size of assigned substring, i.e. {{c|std::min(std::size(t) - pos, n)}}.
+
 
−
@19@ Linear in size of {{c|rg}}.
+
@14@ Linear in the size of the string if {{c|1=alloc != other.get_allocator()}} is {{c|true}}, otherwise constant.
 +
 
 +
@15-19@ Linear in the size of the string.
  
 
===Exceptions===
 
===Exceptions===
−
@4-7@ {{lc|std::out_of_range}} if {{c|pos > other.size()}}.
+
@10@ {{lc|std::out_of_range}} if {{c|pos}} is out of range.
−
@13@ Throws nothing.
+
 
−
@14@ Throws nothing if {{c|1=alloc == str.get_allocator()}}.
+
@14@ Throws nothing if {{c|1=alloc == str.get_allocator()}} is {{c|true}}.
−
@17@ {{lc|std::out_of_range}} if {{c|pos}} is out of range.
+
 
 +
@15-18@ {{lc|std::out_of_range}} if {{c|pos > other.size()}}.
  
−
Throws {{lc|std::length_error}} if the length of the constructed string would exceed {{lc|max_size()}} (for example, if {{c|count > max_size()}} for {{vl|3}}). Calls to {{tt|Allocator::allocate}} may throw.
+
Throws {{lc|std::length_error}} if the length of the constructed string would exceed {{lc|max_size()}} (for example, if {{c|count > max_size()}} for {{v|3}}). Calls to {{tt|Allocator::allocate}} may throw.
  
 
{{cpp/strong exception safety guarantee|plural=yes}}
 
{{cpp/strong exception safety guarantee|plural=yes}}
  
 
===Notes===
 
===Notes===
−
Initialization with a [[cpp/language/string literal|string literal]] that contains embedded {{c|'\0'}} characters uses the overload {{vl|9}}, which stops at the first null character. This can be avoided by specifying a different constructor or by using {{rlpt|operator""s}}:
+
Initialization with a {{lt|cpp/language/string literal}} that contains embedded {{c|'\0'}} characters uses the overload {{v|7}}, which stops at the first null character. This can be avoided by specifying a different constructor or by using {{rlpt|operator""s}}:
 
{{source|1=
 
{{source|1=
 
std::string s1 = "ab\0\0cd";  // s1 contains "ab"
 
std::string s1 = "ab\0\0cd";  // s1 contains "ab"
Line 145: Line 205:
 
}}
 
}}
  
−
{{feature test macro|__cpp_lib_containers_ranges|value=202202L|std=C++23|Tagged constructor {{vl|19}} to construct from {{ls|cpp/ranges/to#container compatible range}}}}
+
{{feature test macro|__cpp_lib_containers_ranges|value=202202L|std=C++23|Tagged constructor {{v|5}} to construct from {{ls|cpp/ranges/to#container compatible range}}}}
  
 
===Example===
 
===Example===
Line 159: Line 219:
 
int main()
 
int main()
 
{
 
{
−
     std::cout << "1) string(); ";
+
     std::cout << "1) string(); ";
 
     std::string s1;
 
     std::string s1;
 
     assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0));
 
     assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0));
 
     std::cout << "s1.capacity(): " << s1.capacity() << '\n'; // unspecified
 
     std::cout << "s1.capacity(): " << s1.capacity() << '\n'; // unspecified
−
 
+
   
−
     std::cout << "2) string(size_type count, CharT ch): ";
+
     std::cout << "3) string(size_type count, CharT ch): ";
 
     std::string s2(4, '=');
 
     std::string s2(4, '=');
 
     std::cout << std::quoted(s2) << '\n'; // "===="
 
     std::cout << std::quoted(s2) << '\n'; // "===="
−
 
+
      
−
     std::cout << "3) string(const string& other, size_type pos, size_type count): ";
+
     std::cout << "4) string(InputIt first, InputIt last): ";
−
    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";
 
     char mutable_c_str[] = "another C-style string";
−
     std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1);
+
     std::string s4(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1);
−
     std::cout << std::quoted(s7) << '\n'; // "C-style string"
+
     std::cout << std::quoted(s4) << '\n'; // "C-style string"
−
 
+
   
−
     std::cout << "8) string(string&): ";
+
     std::cout << "6) string(CharT const* s, size_type count): ";
−
     std::string const other8("Exemplar");
+
     std::string s6("C-style string", 7);
−
    std::string s8(other8);
+
     std::cout << std::quoted(s6) << '\n'; // "C-style", i.e. [0, 7)
−
     std::cout << std::quoted(s8) << '\n'; // "Exemplar"
+
   
−
 
+
     std::cout << "7) string(CharT const* s): ";
−
     std::cout << "9) string(string&&): ";
+
     std::string s7("C-style\0string");
−
     std::string s9(std::string("C++ by ") + std::string("example"));
+
     std::cout << std::quoted(s7) << '\n'; // "C-style"
−
     std::cout << std::quoted(s9) << '\n'; // "C++ by example"
+
   
−
 
+
     std::cout << "11) string(string&): ";
−
     std::cout << "a) string(std::initializer_list<CharT>): ";
+
    std::string const other11("Exemplar");
−
     std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'});
+
     std::string s11(other11);
−
     std::cout << std::quoted(sa) << '\n'; // "C-style"
+
     std::cout << std::quoted(s11) << '\n'; // "Exemplar"
−
 
+
      
−
     // before C++11, overload resolution selects string(InputIt first, InputIt last)
+
     std::cout << "12) string(string&&): ";
−
    // [with InputIt = int] which behaves *as if* string(size_type count, CharT ch)
+
     std::string s12(std::string("C++ by ") + std::string("example"));
−
    // after C++11 the InputIt constructor is disabled for integral types and calls:
+
     std::cout << std::quoted(s12) << '\n'; // "C++ by example"
−
     std::cout << "b) string(size_type count, CharT ch) is called: ";
+
   
−
     std::string sb(3, std::toupper('a'));
+
    std::cout << "15) string(const string& other, size_type pos): ";
−
     std::cout << std::quoted(sb) << '\n'; // "AAA"
+
    std::string const other15("Mutatis Mutandis");
−
 
+
    std::string s15(other15, 8);
−
//  std::string sc(nullptr); // Before C++23: throws std::logic_error
+
     std::cout << std::quoted(s15) << '\n'; // "Mutandis", i.e. [8, 16)
−
                            // Since C++23: won't compile, see overload (18)
+
   
−
//  std::string sc(0); // Same as above, as literal 0 is a null pointer constant
+
     std::cout << "17) string(const string& other, size_type pos, size_type count): ";
−
 
+
     std::string const other17("Exemplary");
−
    auto const range = {0x43, 43, 43};
+
    std::string s17(other17, 0, other17.length() - 1);
−
#ifdef __cpp_lib_containers_ranges
+
    std::cout << std::quoted(s17) << '\n'; // "Exemplar"
−
     std::string sc(std::from_range, range); // tagged constructor (19)
+
   
−
     std::cout << "c) string(std::from_range, range) is called: ";
+
     std::cout << "19) string(std::initializer_list<CharT>): ";
−
#else
+
    std::string s19({'C', '-', 's', 't', 'y', 'l', 'e'});
−
     std::string sc(range.begin(), range.end()); // fallback to overload (12)
+
     std::cout << std::quoted(s19) << '\n'; // "C-style"
−
     std::cout << "c) string(range.begin(), range.end()) is called: ";
+
−
#endif
+
−
     std::cout << std::quoted(sc) << '\n'; // "C++"
+
 
}
 
}
 
|p=true<!-- due to .capacity() -->
 
|p=true<!-- due to .capacity() -->
 
|output=
 
|output=
−
1) string(); s1.capacity(): 15
+
1) string(); s1.capacity(): 15
−
2) string(size_type count, CharT ch): "===="
+
3) string(size_type count, CharT ch): "===="
−
3) string(const string& other, size_type pos, size_type count): "Exemplar"
+
4) string(InputIt first, InputIt last): "C-style string"
−
4) string(const string& other, size_type pos): "Mutandis"
+
6) string(CharT const* s, size_type count): "C-style"
−
5) string(CharT const* s, size_type count): "C-style"
+
7) string(CharT const* s): "C-style"
−
6) string(CharT const* s): "C-style"
+
11) string(string&): "Exemplar"
−
7) string(InputIt first, InputIt last): "C-style string"
+
12) string(string&&): "C++ by example"
−
8) string(string&): "Exemplar"
+
15) string(const string& other, size_type pos): "Mutandis"
−
9) string(string&&): "C++ by example"
+
17) string(const string& other, size_type pos, size_type count): "Exemplar"
−
a) string(std::initializer_list<CharT>): "C-style"
+
19) string(std::initializer_list<CharT>): "C-style"
−
b) string(size_type count, CharT ch) is called: "AAA"
+
−
c) string(std::from_range, range) is called: "C++"
+
 
}}
 
}}
  
 
===Defect reports===
 
===Defect reports===
 
{{dr list begin}}
 
{{dr list begin}}
−
{{dr list item|wg=lwg|dr=301|std=C++98|before=overload {{vl|10}} did not use the parameter<br>{{c|alloc}} if {{tt|InputIt}} is an integral type|after=use that parameter}}
+
{{dr list item|wg=lwg|dr=301|std=C++98|before=overload {{v|4}} did not use the parameter<br>{{c|alloc}} if {{tt|InputIt}} is an integral type|after=use that parameter}}
 +
{{dr list item|wg=lwg|dr=438|std=C++98|before=overload {{v|4}} would only call overload {{v|3}}<br>if {{tt|InputIt}} is an integral type|after=calls overload {{v|3}} if {{tt|InputIt}}<br>is not an {{named req|InputIterator}}}}
 
{{dr list item|wg=lwg|dr=847|std=C++98|before=there was no exception safety guarantee|after=added strong exception safety guarantee}}
 
{{dr list item|wg=lwg|dr=847|std=C++98|before=there was no exception safety guarantee|after=added strong exception safety guarantee}}
 
{{dr list item|wg=lwg|dr=2193|std=C++11|before=the default constructor is explicit|after=made non-explicit}}
 
{{dr list item|wg=lwg|dr=2193|std=C++11|before=the default constructor is explicit|after=made non-explicit}}
−
{{dr list item|wg=lwg|dr=2583|std=C++98|before=there is no way to supply an allocator<br>for {{tt|basic_string(str, pos)}}|after=there is a constructor for<br>{{tt|basic_string(str, pos, alloc)}}}}
+
{{dr list item|wg=lwg|dr=2583|std=C++98|before=there was no way to supply an allocator for overload {{v|17}}|after=added overload {{v|15}}}}
−
{{dr list item|wg=lwg|dr=2946|std=C++17|before=overload {{vl|16}} causes ambiguity in some cases|after=avoided by making it a template}}
+
{{dr list item|wg=lwg|dr=2946|std=C++17|before=overload {{v|9}} causes ambiguity in some cases|after=avoided by making it a template}}
−
{{dr list item|wg=lwg|dr=3076|std=C++17|before=two constructors may cause ambiguities<br>in class template argument deduction|after=constrained}}
+
{{dr list item|wg=lwg|dr=3076|std=C++17|before=overloads {{v|3,7}} might cause ambiguities<br>in class template argument deduction|after=constrained}}
 
{{dr list end}}
 
{{dr list end}}
  

Latest revision as of 00:07, 12 November 2024

 
C++
 
Strings library
 
std::basic_string
Member functions
basic_string::basic_string
(C++23)
Element access
(DR*)
(DR*)
(C++17)
Iterators
(C++11)
(C++11)
(C++11)
(C++11)
Capacity
(DR*)
Modifiers
(C++23)
(DR*)
(C++23)
(C++23)
(C++23)  
Search
Operations
(C++20)
(C++20)
(C++23)
Constants
Non-member functions
(C++20)(C++20)
I/O
Comparison
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Numeric conversions
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Literals
(C++14)
Helper classes
(C++11)
Deduction guides (C++17)

 
(1)
basic_string() : basic_string(Allocator()) {}
 (since C++11)
(until C++17)
basic_string() noexcept(noexcept(Allocator()))
    : basic_string(Allocator()) {}
 (since C++17)
(constexpr since C++20)
(2)
explicit basic_string( const Allocator& alloc = Allocator() );
 (until C++11)
explicit basic_string( const Allocator& alloc );
 (noexcept since C++17)
(constexpr since C++20)
basic_string( size_type count, CharT ch,
              const Allocator& alloc = Allocator() );
 (3) (constexpr since C++20)
template< class InputIt >

basic_string( InputIt first, InputIt last,

              const Allocator& alloc = Allocator() );
 (4) (constexpr since C++20)
template< container-compatible-range<CharT> R >

constexpr basic_string( std::from_range_t, R&& rg,

                        const Allocator& = Allocator());
 (5) (since C++23)
basic_string( const CharT* s, size_type count,
              const Allocator& alloc = Allocator() );
 (6) (constexpr since C++20)
basic_string( const CharT* s, const Allocator& alloc = Allocator() );
 (7) (constexpr since C++20)
basic_string( std::nullptr_t ) = delete;
 (8) (since C++23)
template< class StringViewLike >

explicit basic_string( const StringViewLike& t,

                       const Allocator& alloc = Allocator() );
 (9) (since C++17)
(constexpr since C++20)
template< class StringViewLike >

basic_string( const StringViewLike& t,
              size_type pos, size_type count,

              const Allocator& alloc = Allocator() );
 (10) (since C++17)
basic_string( const basic_string& other );
 (11) (constexpr since C++20)
basic_string( basic_string&& other ) noexcept;
 (12) (since C++11)
(constexpr since C++20)
basic_string( const basic_string& other, const Allocator& alloc );
 (13) (since C++11)
(constexpr since C++20)
basic_string( basic_string&& other, const Allocator& alloc );
 (14) (since C++11)
(constexpr since C++20)
basic_string( const basic_string& other, size_type pos,
              const Allocator& alloc = Allocator() );
 (15) (constexpr since C++20)
constexpr basic_string( basic_string&& other, size_type pos,
                        const Allocator& alloc = Allocator() );
 (16) (since C++23)
basic_string( const basic_string& other,

              size_type pos, size_type count,

              const Allocator& alloc = Allocator() );
 (17) (constexpr since C++20)
constexpr basic_string( basic_string&& other,

                        size_type pos, size_type count,

                        const Allocator& alloc = Allocator() );
 (18) (since C++23)
basic_string( std::initializer_list<CharT> ilist,
              const Allocator& 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.
If Allocator is not DefaultConstructible, the behavior is undefined.
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 CopyInsertable 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 Allocator.

(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 LegacyInputIterator, 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 LegacyInputIterator.

If CharT is not EmplaceConstructible 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 EmplaceConstructible 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 Allocator.

(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<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const StringViewLike&, const CharT*> 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<const StringViewLike&,
                      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 CopyInsertable 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 MoveInsertable 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()).

Contents

[edit] 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 - 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

[edit] 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.

[edit] Exceptions

10) std::out_of_range if pos is out of range.
14) Throws nothing if alloc == str.get_allocator() is true.
15-18) std::out_of_range if pos > other.size().

Throws std::length_error if the length of the constructed string would exceed max_size() (for example, if count > max_size() for (3)). Calls to Allocator::allocate may throw.

If an exception is thrown for any reason, these functions have no effect (strong exception safety guarantee).

[edit] Notes

Initialization with a string literal that contains embedded '\0' characters uses the overload (7), 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 Feature
__cpp_lib_containers_ranges 202202L (C++23) Tagged constructor (5) to construct from container compatible range

[edit] Example

Run this code
#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 << "3)  string(size_type count, CharT ch): ";
    std::string s2(4, '=');
    std::cout << std::quoted(s2) << '\n'; // "===="
 
    std::cout << "4)  string(InputIt first, InputIt last): ";
    char mutable_c_str[] = "another C-style string";
    std::string s4(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::string s6("C-style string", 7);
    std::cout << std::quoted(s6) << '\n'; // "C-style", i.e. [0, 7)
 
    std::cout << "7)  string(CharT const* s): ";
    std::string s7("C-style\0string");
    std::cout << std::quoted(s7) << '\n'; // "C-style"
 
    std::cout << "11) string(string&): ";
    std::string const other11("Exemplar");
    std::string s11(other11);
    std::cout << std::quoted(s11) << '\n'; // "Exemplar"
 
    std::cout << "12) string(string&&): ";
    std::string s12(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::string const other15("Mutatis Mutandis");
    std::string s15(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::string const other17("Exemplary");
    std::string s17(other17, 0, other17.length() - 1);
    std::cout << std::quoted(s17) << '\n'; // "Exemplar"
 
    std::cout << "19) string(std::initializer_list<CharT>): ";
    std::string s19({'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"

[edit] Defect reports

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 (4) did not use the parameter
alloc if InputIt is an integral type 		use that parameter
LWG 438 C++98 overload (4) would only call overload (3)
if InputIt is an integral type 		calls overload (3) if InputIt
is not an LegacyInputIterator
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 was no way to supply an allocator for overload (17) added overload (15)
LWG 2946 C++17 overload (9) causes ambiguity in some cases avoided by making it a template
LWG 3076 C++17 overloads (3,7) might cause ambiguities
in class template argument deduction 		constrained

[edit] See also

 assign characters to a string
(public member function) [edit]
assigns values to the string
(public member function) [edit]
(C++11)
 converts an integral or floating-point value to string
(function) [edit]
(C++11)
 converts an integral or floating-point value to wstring
(function) [edit]
constructs a basic_string_view
(public member function of std::basic_string_view<CharT,Traits>) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/basic_string&oldid=177613"