std::basic_string

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

特性測試巨集 (C++20)

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

元編程函式庫 (C++11)

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (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*) 作業 (Operations) 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) 輸入/輸出 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 起)

 

定義於標頭檔 <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 不同，則程式格式錯誤 (ill-formed)。

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	-	字元型別
Traits	-	指定字元型別操作的 traits 類別
配置器 (Allocator)	-	用於分配內部儲存空間的 Allocator 型別

巢狀型別

類型	定義
traits_type	Traits
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	指向 value_type 的 LegacyRandomAccessIterator 與 LegacyContiguousIterator (直到 C++20) 指向 value_type 的 LegacyRandomAccessIterator、contiguous_iterator 與 ConstexprIterator (自 C++20 起)
const_iterator	指向 const value_type 的 LegacyRandomAccessIterator 與 LegacyContiguousIterator (直到 C++20) 指向 const value_type 的 LegacyRandomAccessIterator、contiguous_iterator 與 ConstexprIterator (自 C++20 起)
reverse_iterator	std::reverse_iterator<iterator>
const_reverse_iterator	std::reverse_iterator<const_iterator>

資料成員

constexpr size_type npos [靜態]

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

成員函式

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

非成員函式

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	從輸入/輸出流讀取資料到字串中 (函式樣板)
數值轉換
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)

對字串的雜湊 (hash) 支援 (類別樣板特化)

反覆器失效

指向 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)	用於字串型別的使用者定義字面量 (UDL)
__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++ 標準。

DR	應用於	出版時的行為	正確的行為
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 不同，其行為原為未定義	在此情況下程式現為 格式錯誤 (ill-formed)

參閱

basic_string_view (C++17)

唯讀字串檢視 (string view) (類別樣板)

外部連結

C++ 字串處理