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

来自cppreference.com
< cpp‎ | string‎ | basic string
 
C++
 
字符串库
 
std::basic_string
 
(1)
basic_string() : basic_string(Allocator()) {}
(C++11 起)
(C++17 前)
basic_string() noexcept(noexcept(Allocator()))
    : basic_string(Allocator()) {}
(C++17 起)
(C++20 起为 constexpr)
(2)
explicit basic_string( const Allocator& alloc = Allocator() );
(C++11 前)
explicit basic_string( const Allocator& alloc );
(C++17 起为 noexcept)
(C++20 起为 constexpr)
basic_string( size_type count, CharT ch,
              const Allocator& alloc = Allocator() );
(3)(C++20 起为 constexpr)
template< class InputIt >

basic_string( InputIt first, InputIt last,

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

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

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

explicit basic_string( const StringViewLike& t,

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

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

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

              size_type pos, size_type count,

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

                        size_type pos, size_type count,

                        const Allocator& alloc = Allocator() );
(18)(C++23 起)
basic_string( std::initializer_list<CharT> ilist,
              const Allocator& alloc = Allocator() );
(19)(C++11 起)
(C++20 起为 constexpr)

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

1) C++11 起的默认构造函数。构造拥有默认构造的分配器的空字符串。
如果 Allocator 不可默认构造 (DefaultConstructible) ，那么行为未定义。
2) C++11 前的默认构造函数。构造拥有给定分配器 alloc 的空字符串。
3) 构造拥有 count 个字符 ch 的副本的字符串。

如果 CharT 不可复制插入 (CopyInsertable) 到 std::basic_string<CharT> 中，那么行为未定义。

(C++11 起)

此重载只有在 Allocator 满足分配器 (Allocator) 时才会参与重载决议。

(C++17 起)
4) 以范围 [first, last) 的内容构造字符串。[first, last) 中的每个迭代器都只会解引用一次。

如果 InputIt 不满足老式输入迭代器 (LegacyInputIterator) ，那么就会改为以实参 static_cast<size_type>(first)、last 和 alloc 调用重载 (3)。

(C++11 前)

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

如果 CharT 从 *first 不可就位构造 (EmplaceConstructible) 到 std::basic_string<CharT> 中，那么行为未定义。

(C++11 起)
5) 以范围 rg 的内容构造字符串。rg 中的每个迭代器都只会解引用一次。
如果 CharT 从 *ranges::begin(rg) 不可就位构造 (EmplaceConstructible) 到 std::basic_string<CharT> 中，那么行为未定义。
6) 以范围 [s, s + count) 的内容构造字符串。
如果 [s, s + count) 不是有效范围，那么行为未定义。
7) 等价于 basic_string(s, Traits::length(s), alloc)。

此重载只有在 Allocator 满足分配器 (Allocator) 时才会参与重载决议。

(C++17 起)
8) 不能从 nullptr 构造 std::basic_string。
9) 如同用 std::basic_string_view<CharT, Traits> sv = t; 将 t 隐式转换到字符串视图 sv ，然后如同以 basic_string(sv.data(), sv.size(), alloc) 构造字符串。
此重载只有在 std::is_convertible_v<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> 是 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 是 false 时才会参与重载决议。
10) 如同用 std::basic_string_view<CharT, Traits> sv = t; 将 t 隐式转换到字符串视图 sv ，然后如同以 basic_string(sv.substr(pos, count), alloc) 构造字符串。
此重载只有在 std::is_convertible_v<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> 是 true 时才会参与重载决议。
11-18) 以 other 的（部分）内容构造字符串。如果 other 的类型是 basic_string&&，那么在构造完成时，other 会处于某个未指定的有效状态。
11) 复制构造函数

如同通过调用 std::allocator_traits<Allocator>::
    select_on_container_copy_construction
        (other.get_allocator()) 获得分配器。

(C++11 起)
12) 移动构造函数。如同通过从 other.get_allocator() 移动构造获得分配器。
13) 与构造函数相同，但是会将 alloc 用作分配器。
如果 CharT 不可复制插入 (CopyInsertable) 到 std::basic_string<CharT> 中，那么行为未定义。
14) 与移动函数相同，但是会将 alloc 用作分配器。
如果 CharT 不可移动插入 (MoveInsertable) 到 std::basic_string<CharT> 中，那么行为未定义。
15,16) 以范围 [other.data() + pos, other.data() + other.size()) 的内容构造字符串。
17,18) 以范围 [other.data() + pos, other.data() + (pos + std::min(count, other.size() - pos))) 的内容构造字符串。
19) 等价于 basic_string(ilist.begin(), ilist.end())。

参数

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

复杂度

1,2) 常数。
3-7) 与字符串的大小成线性。
9-11) 与字符串的大小成线性。
12) 常数。
13) 与字符串的大小成线性。
14) 在 alloc != other.get_allocator() 是 true 时成线性，否则是常数。
15-19) 与字符串的大小成线性。

异常

10) 在 pos 在范围外时会抛出 std::out_of_range。
14) 在 alloc == str.get_allocator() 是 true 时不会抛出。
15-18) 在 pos > other.size() 是 true 时会抛出 std::out_of_range。

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

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

注解

以含内嵌 '\0' 字符的字符串字面量初始化字符串会使用重载 (7)，它会在首个空字符处停止。这可通过指定不同的构造函数，或通过使用 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_ranges202202L(C++23)使用带标签的构造函数 (5) 从容器兼容范围构造

示例

运行此代码
#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 << "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"，即 [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"，即 [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"
}

可能的输出：

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"

缺陷报告

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

缺陷报告应用于出版时的行为正确行为
LWG 301C++98重载 (4) 在 InputIt 是整数类型时不会使用形参 alloc使用该形参
LWG 438C++98重载 (4) 只有在 InputIt 是整数类型时才会调用重载 (3)会在 InputIt 不是
老式输入迭代器 (LegacyInputIterator) 时调用
LWG 847C++98没有异常安全保证添加强异常安全保证
LWG 2193C++11默认构造函数是显式的改成非显式的
LWG 2235C++98s 可以是空指针值此时行为未定义
LWG 2250C++98pos > other.size() 是 true 时重载 (17) 的行为未定义此时始终会抛出异常
LWG 2583C++98无法为重载 (17) 提供分配器添加重载 (15)
LWG 2946C++17重载 (9) 在一些情况下会导致歧义通过改成模板来避免
LWG 3076C++17重载 (3,7) 可能会在类模板实参推导中导致歧义添加约束
LWG 3111
(P1148R0)		C++98LWG 问题 2235 的解决方案导致
basic_string(nullptr, 0) 的行为未定义		此时行为具有良好定义[1]
  1. ↑ [nullptr, nullptr + 0) 是有效的空范围，因为给空指针值加上零也具有良好定义（结果仍然是空指针值）。

参阅

赋值字符给字符串
(公开成员函数)
为字符串赋值
(公开成员函数)
(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=96585”