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

 

C++

编译器支持

自立实现与有宿主实现

语言

标准库

标准库标头

具名要求

功能特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

 

字符串库

类

basic_string

basic_string_view (C++17)

char_traits

 

std::basic_string

成员函数 basic_string::basic_string basic_string::~basic_string basic_string::operator= basic_string::assign basic_string::assign_range (C++23)   basic_string::get_allocator 元素访问 basic_string::at basic_string::operator[] basic_string::front (DR*) basic_string::back (DR*) basic_string::data basic_string::c_str basic_string::operator  basic_string_view (C++17) 迭代器 basic_string::beginbasic_string::cbegin (C++11) basic_string::endbasic_string::cend (C++11) basic_string::rbeginbasic_string::crbegin (C++11) basic_string::rendbasic_string::crend (C++11) 搜索 basic_string::find basic_string::rfind basic_string::find_first_of basic_string::find_first_not_of basic_string::find_last_of basic_string::find_last_not_of

修改器 basic_string::clear basic_string::insert basic_string::insert_range (C++23) basic_string::erase basic_string::push_back basic_string::pop_back (DR*) basic_string::append basic_string::append_range (C++23) basic_string::operator+= basic_string::replace basic_string::replace_with_range (C++23) basic_string::copy basic_string::resize basic_string::resize_and_overwrite (C++23)  basic_string::swap 容量 basic_string::empty basic_string::sizebasic_string::length basic_string::max_size basic_string::reserve basic_string::capacity basic_string::shrink_to_fit (DR*) 操作 basic_string::compare basic_string::starts_with (C++20) basic_string::ends_with (C++20) basic_string::contains (C++23) basic_string::substr

常量 basic_string::npos 非成员函数 operator+ swap(std::basic_string) erase(std::basic_string)erase_if(std::basic_string) (C++20)(C++20) I/O operator<<operator>> getline 比较 operator==operator!=operator<operator>operator<=operator>=operator<=> (C++20 前)(C++20 前)(C++20 前)(C++20 前)(C++20 前)(C++20) 数值转换 stoistolstoll (C++11)(C++11)(C++11) stoulstoull (C++11)(C++11)  stofstodstold (C++11)(C++11)(C++11) to_string (C++11) to_wstring (C++11) 字面量 operator""s (C++14) 辅助类 hash<std::basic_string> (C++11) 推导指引 (C++17)

 

<tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody>

	(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_ranges	202202L	(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 301	C++98	重载 (4) 在 InputIt 是整数类型时不会使用形参 alloc	使用该形参
LWG 438	C++98	重载 (4) 只有在 InputIt 是整数类型时才会调用重载 (3)	会在 InputIt 不是 老式输入迭代器 (LegacyInputIterator) 时调用
LWG 847	C++98	没有异常安全保证	添加强异常安全保证
LWG 2193	C++11	默认构造函数是显式的	改成非显式的
LWG 2235	C++98	s 可以是空指针值	此时行为未定义
LWG 2250	C++98	pos > other.size() 是 true 时重载 (17) 的行为未定义	此时始终会抛出异常
LWG 2583	C++98	无法为重载 (17) 提供分配器	添加重载 (15)
LWG 2946	C++17	重载 (9) 在一些情况下会导致歧义	通过改成模板来避免
LWG 3076	C++17	重载 (3,7) 可能会在类模板实参推导中导致歧义	添加约束
LWG 3111 (P1148R0)	C++98	LWG 问题 2235 的解决方案导致 basic_string(nullptr, 0) 的行为未定义	此时行为具有良好定义

参阅

assign	赋值字符给字符串 (公开成员函数)
operator=	为字符串赋值 (公开成员函数)
to_string (C++11)	转换整数或浮点数为 string (函数)
to_wstring (C++11)	转换整数或浮点数为 wstring (函数)
(构造函数)	构造 basic_string_view (std::basic_string_view<CharT,Traits> 的公开成员函数)