On this page
std::basic_string<CharT,Traits,Allocator>::basic_string
(1) | ||
|
(until C++17) | |
|
(since C++17) (until C++20) |
|
|
(since C++20) | |
(2) | ||
|
(until C++20) | |
|
(since C++20) | |
(3) | ||
|
(until C++20) | |
|
(since C++20) | |
|
(3) | (since C++23) |
(3) | ||
|
(until C++20) | |
|
(since C++20) | |
|
(3) | (since C++23) |
(4) | ||
|
(until C++20) | |
|
(since C++20) | |
(5) | ||
|
(until C++20) | |
|
(since C++20) | |
(6) | ||
|
(until C++20) | |
|
(since C++20) | |
(7) | ||
|
(until C++20) | |
|
(since C++20) | |
(7) | ||
|
(since C++11) (until C++20) |
|
|
(since C++20) | |
(8) | ||
|
(since C++11) (until C++20) |
|
|
(since C++20) | |
(8) | ||
|
(since C++11) (until C++20) |
|
|
(since C++20) | |
(9) | ||
|
(since C++11) (until C++20) |
|
|
(since C++20) | |
(10) | ||
|
(since C++17) (until C++20) |
|
|
(since C++20) | |
(11) | ||
|
(since C++17) (until C++20) |
|
|
(since C++20) | |
|
(12) | (since C++23) |
|
(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
.
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 |
Complexity
count
.
s
.
first
and last
.
other
.
alloc
is given and alloc != other.get_allocator()
, then linear.
ilist
.
rg
.
Exceptions
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).
Notes
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 | Feature |
---|---|---|---|
__cpp_lib_containers_ranges |
202202L | (C++23) | Tagged constructor (13) to construct from container compatible range |
Example
#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"
// std::string sc(nullptr); // Before C++23: throws std::logic_error
// Since C++23: won't compile, see overload (12)
// std::string sc(0); // Same as above, as literal 0 is a null pointer constant
auto const range = {0x43, 43, 43};
#ifdef __cpp_lib_containers_ranges
std::string sc(std::from_range, range); // tagged constructor (13)
std::cout << "c) string(std::from_range, range) is called: ";
#else
std::string sc(range.begin(), range.end()); // fallback to overload (7)
std::cout << "c) string(range.begin(), range.end()) is called: ";
#endif
std::cout << std::quoted(sc) << '\n'; // "C++"
}
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"
c) string(std::from_range, range) is called: "C++"
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 (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 |
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> ) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/string/basic_string/basic_string