std::basic_string<CharT,Traits,Allocator>::basic_string

来自cppreference.com
< cpp‎ | string‎ | basic string
 
C++
 
字符串库
 
std::basic_string
成员函数
basic_string::basic_string
(C++23)
元素访问
(DR*)
(DR*)
(C++17)
迭代器
(C++11)
(C++11)
(C++11)
(C++11)
容量
(DR*)
修改器
(C++23)
(DR*)
(C++23)
(C++23)
(C++23)  
搜索
操作
(C++20)
(C++20)
(C++23)
常量
非成员函数
(C++20)(C++20)
I/O
比较
(C++20 前)(C++20 前)(C++20 前)(C++20 前)(C++20 前)(C++20)
数值转换
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
字面量
(C++14)
辅助类
(C++11)
推导指引 (C++17)

 
(1)
basic_string();
 (C++17 前)
basic_string() noexcept(noexcept(Allocator()))
    : basic_string( Allocator() ) {}
 (C++17 起)
(C++20 起为 constexpr)
explicit basic_string( const Allocator& alloc );
 (2) (C++17 起为 noexcept)
(C++20 起为 constexpr)
basic_string( size_type count, CharT ch,
              const Allocator& alloc = Allocator() );
 (3) (C++20 起为 constexpr)
basic_string( const basic_string& other, size_type pos,
              const Allocator& alloc = Allocator() );
 (4) (C++20 起为 constexpr)
constexpr basic_string( basic_string&& other, size_type pos,
                        const Allocator& alloc = Allocator() );
 (5) (C++23 起)
basic_string( const basic_string& other,

              size_type pos, size_type count,

              const Allocator& alloc = Allocator() );
 (6) (C++20 起为 constexpr)
constexpr basic_string( basic_string&& other,

                        size_type pos, size_type count,

                        const Allocator& alloc = Allocator() );
 (7) (C++23 起)
basic_string( const CharT* s, size_type count,
              const Allocator& alloc = Allocator() );
 (8) (C++20 起为 constexpr)
basic_string( const CharT* s, const Allocator& alloc = Allocator() );
 (9) (C++20 起为 constexpr)
template< class InputIt >

basic_string( InputIt first, InputIt last,

              const Allocator& alloc = Allocator() );
 (10) (C++20 起为 constexpr)
basic_string( const basic_string& other );
 (11) (C++20 起为 constexpr)
basic_string( const basic_string& other, const Allocator& alloc );
 (12) (C++11 起)
(C++20 起为 constexpr)
basic_string( basic_string&& other ) noexcept;
 (13) (C++11 起)
(C++20 起为 constexpr)
basic_string( basic_string&& other, const Allocator& alloc );
 (14) (C++11 起)
(C++20 起为 constexpr)
basic_string( std::initializer_list<CharT> ilist,
              const Allocator& alloc = Allocator() );
 (15) (C++11 起)
(C++20 起为 constexpr)
template< class StringViewLike >

explicit basic_string( const StringViewLike& t,

                       const Allocator& alloc = Allocator() );
 (16) (C++17 起)
(C++20 起为 constexpr)
template< class StringViewLike >

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

              const Allocator& alloc = Allocator() );
 (17) (C++17 起)
(C++20 起为 constexpr)
basic_string( std::nullptr_t ) = delete;
 (18) (C++23 起)
template< container-compatible-range<CharT> R >

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

                        const Allocator& = Allocator());
 (19) (C++23 起)

从各种数据源构造新字符串，可以使用用户提供的分配器 alloc。

1,2) 默认构造函数。构造空字符串（拥有零大小和未指定的容量）。如果不提供分配器，那么从默认构造的实例获得分配器。
3) 构造拥有字符 ch 的 count 个副本的字符串。如果推导出的 Allocator 类型不满足分配器要求，那么此构造函数不会用于类模板实参推导。 (C++17 起)
4-7) 以 other 的子串 [pos, pos + count) 构造字符串。如果 count == npos 或未指定 count，或请求的子串越过字符串的结尾，那么产生的子串是 [pos, other.size())。如果 other 是右值引用，它将处于合法但未指定的状态。 (C++23 起)
8) 以 s 所指向的字符串的首 count 个字符构造字符串。s 能包含空字符。构造的字符串的长度是 count。在 [s, s + count) 不是合法范围时行为未定义。
9) 以 s 所指向的空终止字符串的副本所初始化的内容构造字符串。以首个空字符确定字符串的长度。如果 [s, s + Traits::length(s)) 不是合法范围（例如 s 是空指针），那么行为未定义。如果推导出的 Allocator 类型不满足分配器要求，那么此构造函数不会用于类模板实参推导。 (C++17 起)
10) 构造拥有范围 [first, last) 内容的字符串。

如果 InputIt 是整数类型，那么等价于 (2)，如同 basic_string(static_cast<size_type>(first),
             static_cast<value_type>(last), alloc)。

(C++11 前)

此构造函数只有在 InputIt 满足老式输入迭代器 (LegacyInputIterator) 时才会参与重载决议。

(C++11 起)
11,12) 复制构造函数。构造拥有 other 内容副本的字符串。
13,14) 移动构造函数。用移动语义构造拥有 other 内容的字符串。将 other 留在有效但未指定的状态。
15) 构造拥有初始化式列表 ilist 内容的字符串。
16) 如同用 std::basic_string_view<CharT, Traits> sv = t; 将 t 隐式转换到字符串视图 sv ，然后如同用 basic_string(sv.data(), sv.size(), alloc)，以 sv 的内容初始化字符串。
此重载只有在 std::is_convertible_v<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> 是 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 是 false 时才会参与重载决议。
17) 如同用 std::basic_string_view<CharT, Traits> sv = t; 将 t 隐式转换到字符串视图 sv ，然后如同用 basic_string(sv.substr(pos, n), alloc)，以 sv 的子范围 [pos, pos + n) 初始化字符串。
此重载只有在 std::is_convertible_v<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> 是 true 时才会参与重载决议。
18) 不能从 nullptr 构造 std::basic_string。
19) 使用范围 rg 中包含的值构造字符串。

参数

alloc - 用于此字符串所有内存分配的分配器
count - 产生的字符串大小
ch - 初始化字符串所用的值
pos - 要包含的首字符位置
first, last - 复制字符的来源范围
s - 指向用作源初始化字符串的字符数组的指针
other - 用作源初始化字符串的另一字符串
ilist - 初始化字符串所用的 std::initializer_list
t - 初始化字符串所用的对象（可转换到 std::basic_string_view）

复杂度

1,2) 常数。
3-8) 与 count 成线性。
9) 与 s 的长度成线性。
10) 与 first 和 last 间的距离成线性。
11,12) 与 other 的大小成线性。
13) 常数。
14) 常数。在给出 alloc 且 alloc != other.get_allocator() 时成线性。
15) 与 ilist 的大小成线性。
16) 与 t 的大小成线性。
17) 与所赋值的子字符串的大小（即 std::min(std::size(t) - pos, n)）成线性。
19) 与 rg 的大小成线性。

异常

4-7) 在 pos > other.size() 时会抛出 std::out_of_range。
13) 无抛出。
14) 在 alloc == str.get_allocator() 时不抛出。
17) 在 pos 在范围外时会抛出 std::out_of_range。

如果构造的字符串长度会超出 max_size()（例如对于 (3)，如果 count > max_size()），那么就会抛出 std::length_error。调用 Allocator::allocate 可能会抛出。

如果因为任何原因抛出了异常，那么这些函数无效果（强异常安全保证）。

注解

以含内嵌 '\0' 字符的字符串字面量初始化字符串会使用重载 (9)，它会在首个空字符处停止。这可通过指定不同的构造函数，或通过使用 operator""s 予以避免： 

std::string s1 = "ab\0\0cd";   // s1 含 "ab"
std::string s2{"ab\0\0cd", 6}; // s2 含 "ab\0\0cd"
std::string s3 = "ab\0\0cd"s;  // s3 含 "ab\0\0cd"
功能特性测试宏 值 标准 功能特性
__cpp_lib_containers_ranges 202202L (C++23) 使用带标签的构造函数 (19) 从容器兼容范围构造

示例

运行此代码
#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'; // 未指定
 
    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"，即 [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"，即 [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"
 
    // 在 C++11 前，重载决议会选择 string(InputIt first, InputIt last)
    // [其中 InputIt = int]，它会表现*如同* string(size_type count, charT ch)
    // 在 C++11 后，对整数类型参数的构造函数调用会禁用使用 InputIt 的构造函数：
    std::cout << "b) string(size_type count, charT ch) 被调用: ";
    std::string sb(3, std::toupper('a'));
    std::cout << std::quoted(sb) << '\n'; // "AAA"
 
//  std::string sc{nullptr}; // C++23 前：抛出 std::logic_error
                             // C++23 后：不会编译，见重载 (18)
//  std::string sc(0); // 同上，因为字面量 0 是空指针常量
 
    auto const range = {0x43, 43, 43};
#ifdef __cpp_lib_containers_ranges
    std::string sc(std::from_range, range); // 带标签构造函数 (19)
    std::cout << "c) string(std::from_range, range) 被调用: ";
#else
    std::string sc(range.begin(), range.end()); // 后备调用重载 (12)
    std::cout << "c) string(range.begin(), range.end()) 被调用: ";
#endif
    std::cout << std::quoted(sc) << '\n'; // "C++"
}

可能的输出： 

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) 被调用: "AAA"
c) string(std::from_range, range) 被调用: "C++"

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告 应用于 出版时的行为 正确行为
LWG 301 C++98 重载 (10) 在 InputIt 是整数类型时不会使用形参 alloc 使用该形参
LWG 847 C++98 没有异常安全保证 添加强异常安全保证
LWG 2193 C++11 默认构造函数是显式的 改成非显式的
LWG 2583 C++98 无法向 basic_string(str, pos) 提供分配器 添加构造函数 basic_string(str, pos, alloc)
LWG 2946 C++17 重载 (16) 在一些情况下会导致歧义 通过改成模板来避免
LWG 3076 C++17 两个构造函数可能会在类模板实参推导中导致歧义 已制约

参阅

 赋值字符给字符串
(公开成员函数)
为字符串赋值
(公开成员函数)
(C++11)
 转换整数或浮点值为 string
(函数)
(C++11)
 转换整数或浮点值为 wstring
(函数)
构造 basic_string_view
(std::basic_string_view<CharT,Traits> 的公开成员函数)
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/basic_string&oldid=92407”