std::basic_string

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (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<=> (until C++20)(until C++20)(until C++20)(until C++20)(until 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)

 

定義於標頭檔案 <string>
template<     class CharT,     class Traits = std::char_traits<CharT>,     class Allocator = std::allocator<CharT> > class basic_string;	(1)
namespace pmr { template<     class CharT,     class Traits = std::char_traits<CharT> > using basic_string =     std::basic_string<CharT, Traits, std::pmr::polymorphic_allocator<CharT>>; }	(2)	(C++17 起)

類模板 basic_string 儲存和操作字元類物件序列，這些物件是非陣列的 字元型別，為 TrivialType 和 StandardLayoutType。此型別不依賴於字元型別，也不依賴於該型別上的操作性質。操作的定義由 `Traits` 模板引數提供——一個 `std::char_traits` 的特化或相容的 traits 類。

basic_string 的元素是連續儲存的，也就是說，對於 basic_string s，對於 [0, s.size()) 範圍內的任何 n，都有 &*(s.begin() + n) == &*s.begin() + n，並且 *(s.begin() + s.size()) 的值為 CharT() (空終止符)(C++11 起)；或者，等效地，指向 s[0] 的指標可以傳遞給期望指向 CharT 陣列(直至 C++11)空終止陣列(C++11 起) 首個元素的函式。

std::basic_string 滿足 AllocatorAwareContainer 的要求（除了自定義的 construct/destroy 不用於元素的構造/析構），SequenceContainer 和 ContiguousContainer(C++17 起) 的要求。

如果 `Traits::char_type` 和 `Allocator::char_type` 中的任何一個與 `CharT` 不同，則程式是非良構的。

`std::basic_string` 的所有成員函式都是 constexpr：可以在常量表達式求值中建立和使用 `std::basic_string` 物件。 然而，`std::basic_string` 物件通常不能是 constexpr，因為任何動態分配的儲存都必須在同一常量表達式的求值中釋放。

(C++20 起)

提供了用於常見字元型別的幾個 typedef

定義於標頭檔案 <string>
型別	定義
std::string	std::basic_string<char>
std::wstring	std::basic_string<wchar_t>
std::u8string (C++20)	std::basic_string<char8_t>
std::u16string (C++11)	std::basic_string<char16_t>
std::u32string (C++11)	std::basic_string<char32_t>
std::pmr::string (C++17)	std::pmr::basic_string<char>
std::pmr::wstring (C++17)	std::pmr::basic_string<wchar_t>
std::pmr::u8string (C++20)	std::pmr::basic_string<char8_t>
std::pmr::u16string (C++17)	std::pmr::basic_string<char16_t>
std::pmr::u32string (C++17)	std::pmr::basic_string<char32_t>

模板引數

CharT	-	字元型別
特性	-	指定字元型別操作的 trait 類
Allocator	-	用於分配內部儲存的 Allocator 型別

巢狀型別

型別	定義
traits_type	特性
value_type	CharT
allocator_type	Allocator
size_type	Allocator::size_type (C++11 前) std::allocator_traits<Allocator>::size_type (C++11 起)
difference_type	Allocator::difference_type (C++11 前) std::allocator_traits<Allocator>::difference_type (C++11 起)
reference	value_type&
const_reference	const value_type&
pointer	Allocator::pointer (C++11 前) std::allocator_traits<Allocator>::pointer (C++11 起)
const_pointer	Allocator::const_pointer (C++11 前) std::allocator_traits<Allocator>::const_pointer (C++11 起)
iterator	LegacyRandomAccessIterator 和 LegacyContiguousIterator 到 value_type (C++20 前) LegacyRandomAccessIterator、contiguous_iterator 和 ConstexprIterator 到 value_type (C++20 起)
const_iterator	LegacyRandomAccessIterator 和 LegacyContiguousIterator 到 const value_type (C++20 前) LegacyRandomAccessIterator、contiguous_iterator 和 ConstexprIterator 到 const value_type (C++20 起)
reverse_iterator	std::reverse_iterator<iterator>
const_reverse_iterator	std::reverse_iterator<const_iterator>

資料成員

constexpr size_type npos [static]

特殊值 size_type(-1)，其確切含義取決於上下文

成員函式

(建構函式)	構造一個 basic_string (public 成員函式)
(解構函式)	銷燬字串，如果使用了內部儲存則釋放它 (public 成員函式)
operator=	給字串賦值 (public 成員函式)
assign	給字串賦值字元 (public 成員函式)
assign_range (C++23)	給字串賦值一個字元範圍 (public 成員函式)
get_allocator	返回關聯的分配器 (public 成員函式)
元素訪問
at	帶邊界檢查訪問指定字元 (public 成員函式)
operator[]	訪問指定的字元 (public 成員函式)
front (DR*)	訪問第一個字元 (public 成員函式)
back (DR*)	訪問最後一個字元 (public 成員函式)
data	返回指向字串第一個字元的指標 (public 成員函式)
c_str	返回字串的不可修改的標準C字元陣列版本 (public 成員函式)
operator basic_string_view (C++17)	返回一個指向整個字串的不可修改的 basic_string_view (public 成員函式)
迭代器
begincbegin (C++11)	返回指向起始的迭代器 (public 成員函式)
endcend (C++11)	返回指向末尾的迭代器 (public 成員函式)
rbegincrbegin (C++11)	返回指向起始的逆向迭代器 (public 成員函式)
rendcrend (C++11)	返回指向末尾的逆向迭代器 (public 成員函式)
容量
empty	檢查字串是否為空 (public 成員函式)
sizelength	返回字元數 (public 成員函式)
max_size	返回字元的最大數量 (public 成員函式)
reserve	預留儲存空間 (public 成員函式)
capacity	返回當前分配儲存中可容納的字元數 (public 成員函式)
shrink_to_fit (DR*)	透過釋放未使用的記憶體來減少記憶體使用 (public 成員函式)
修改器
clear	清除內容 (public 成員函式)
insert	插入字元 (public 成員函式)
insert_range (C++23)	插入一個字元範圍 (public 成員函式)
erase	移除字元 (public 成員函式)
push_back	在末尾新增字元 (public 成員函式)
pop_back (DR*)	移除最後一個字元 (public 成員函式)
append	將字元追加到末尾 (public 成員函式)
append_range (C++23)	在末尾追加一個字元範圍 (public 成員函式)
operator+=	將字元追加到末尾 (public 成員函式)
replace	替換字串的指定部分 (public 成員函式)
replace_with_range (C++23)	用一個字元範圍替換字串的指定部分 (public 成員函式)
copy	複製字元 (public 成員函式)
resize	更改儲存的字元數 (public 成員函式)
resize_and_overwrite (C++23)	改變儲存的字元數量，並可能透過使用者提供的操作覆蓋不確定的內容 (public 成員函式)
swap	交換內容 (public 成員函式)
搜尋
find	查詢給定子字串的第一次出現 (public 成員函式)
rfind	查詢子串的最後一次出現 (public 成員函式)
find_first_of	查詢字元的首次出現 (public 成員函式)
find_first_not_of	查詢字元的首次缺席 (public 成員函式)
find_last_of	查詢字元的最後一次出現 (public 成員函式)
find_last_not_of	查詢字元的最後一次缺席 (public 成員函式)
操作
compare	比較兩個字串 (public 成員函式)
starts_with (C++20)	檢查字串是否以給定字首開頭 (public 成員函式)
ends_with (C++20)	檢查字串是否以給定字尾結尾 (public 成員函式)
contains (C++23)	檢查字串是否包含給定子字串或字元 (public 成員函式)
substr	返回子字串 (public 成員函式)

非成員函式

operator+	連線兩個字串，一個字串和一個 char，或者一個字串和一個 string_view (函式模板)
operator==operator!=operator<operator>operator<=operator>=operator<=> (C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 起)	按字典序比較兩個字串 (函式模板)
std::swap(std::basic_string)	特化 std::swap 演算法 (函式模板)
erase(std::basic_string)erase_if(std::basic_string) (C++20)	擦除所有滿足特定標準的元素 (函式模板)
輸入/輸出
operator<<operator>>	對字串執行流輸入和輸出 (函式模板)
getline	從 I/O 流讀取資料到字串 (函式模板)
數值轉換
stoistolstoll (C++11)(C++11)(C++11)	將字串轉換為有符號整數 (函式)
stoulstoull (C++11 起)(C++11 起)	將字串轉換為無符號整數 (函式)
stofstodstold (C++11)(C++11)(C++11)	將字串轉換為浮點值 (函式)
to_string (C++11)	將整數或浮點值轉換為 string (函式)
to_wstring (C++11)	將整數或浮點值轉換為 wstring (函式)

字面量

在內聯名稱空間 std::literals::string_literals 中定義
operator""s (C++14)	將字元陣列字面量轉換為 basic_string (函式)

輔助類

std::hash<std::basic_string> (C++11)

字串的雜湊支援 (類模板特化)

迭代器失效

引用、指標和迭代器指向 basic_string 元素的有效性可能會因任何接受非 const basic_string 引用作為引數的標準庫函式而失效，例如 std::getline、std::swap 或 operator>>，以及呼叫非 const 成員函式，除了 operator[]、at、data、front、back、begin、rbegin、end 和 rend。

注

儘管在 C++23 之前，構造或銷燬 `std::basic_string` 的元素時需要使用自定義的 `construct` 或 `destroy`，但所有實現都只使用了預設機制。此要求已透過 P1072R10 糾正，以符合現有實踐。

特性測試宏	值	標準	特性
__cpp_lib_string_udls	201304L	(C++14)	字串型別的使用者定義字面量
__cpp_lib_starts_ends_with	201711L	(C++20)	starts_with, ends_with
__cpp_lib_constexpr_string	201907L	(C++20)	std::basic_string 的 Constexpr
__cpp_lib_char8_t	201907L	(C++20)	std::u8string
__cpp_lib_erase_if	202002L	(C++20)	erase, erase_if
__cpp_lib_string_contains	202011L	(C++23)	contains
__cpp_lib_string_resize_and_overwrite	202110L	(C++23)	resize_and_overwrite
__cpp_lib_containers_ranges	202202L	(C++23)	接受容器兼容範圍的構造、插入和替換成員函式

示例

執行此程式碼

#include <iostream>
#include <string>
 
int main()
{
    using namespace std::literals;
 
    // Creating a string from const char*
    std::string str1 = "hello";
 
    // Creating a string using string literal
    auto str2 = "world"s;
 
    // Concatenating strings
    std::string str3 = str1 + " " + str2;
 
    // Print out the result
    std::cout << str3 << '\n';
 
    std::string::size_type pos = str3.find(" ");
    str1 = str3.substr(pos + 1); // the part after the space
    str2 = str3.substr(0, pos);  // the part till the space
 
    std::cout << str1 << ' ' << str2 << '\n';
 
    // Accessing an element using subscript operator[]
    std::cout << str1[0] << '\n';
    str1[0] = 'W';
    std::cout << str1 << '\n';
}

輸出

hello world
world hello
w
World

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 530	C++98	basic_string 元素儲存的連續性 意外地被 LWG259 設定為非必需	再次要求
LWG 2861	C++98	value_type 是 Traits::char_type	改為 CharT
LWG 2994 (P1148R0)	C++98	如果 Traits::char_type 中的任何一個 和 Allocator::char_type 與 CharT 不同，則行為未定義	程式是 非良構的

另請參閱

basic_string_view (C++17)

只讀字串檢視 (類模板)

外部連結

C++ 字串處理