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

basic_string& insert( size_type index, size_type count, CharT ch );	(1)	(C++20 起為 constexpr)
basic_string& insert( size_type index, const CharT* s );	(2)	(C++20 起為 constexpr)
basic_string& insert( size_type index, const CharT* s, size_type count );	(3)	(C++20 起為 constexpr)
basic_string& insert( size_type index, const basic_string& str );	(4)	(C++20 起為 constexpr)
	(5)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count );			(until C++14)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count = npos );			(C++14 起) (C++20 起為 constexpr)
		(6)
iterator insert( iterator pos, CharT ch );				(C++11 前)
iterator insert( const_iterator pos, CharT ch );				(C++11 起) (C++20 起為 constexpr)
			(7)
void insert( iterator pos, size_type count, CharT ch );					(C++11 前)
iterator insert( const_iterator pos, size_type count, CharT ch );					(C++11 起) (C++20 起為 constexpr)
				(8)
template< class InputIt > void insert( iterator pos, InputIt first, InputIt last );						(C++11 前)
template< class InputIt > iterator insert( const_iterator pos, InputIt first, InputIt last );						(C++11 起) (C++20 起為 constexpr)
iterator insert( const_iterator pos, std::initializer_list<CharT> ilist );					(9)	(C++11 起) (C++20 起為 constexpr)
template< class StringViewLike > basic_string& insert( size_type index, const StringViewLike& t );					(10)	(C++17 起) (C++20 起為 constexpr)
template< class StringViewLike > basic_string& insert( size_type index, const StringViewLike& t, size_type t_index, size_type count = npos );					(11)	(C++17 起) (C++20 起為 constexpr)

在字串中插入字元。

1) 在位置 index 插入 count 個字元 ch 的副本。

2) 在位置 index 插入 s 指向的以 null 結尾的字元字串。字串的長度由使用 Traits::length(s) 的第一個 null 字元決定。

3) 在位置 index 插入範圍 [s, s + count) 中的字元。該範圍可以包含 null 字元。

4) 在位置 index 插入字串 str。

5) 在位置 index 插入透過 str.substr(s_index, count) 獲得的字串。

6) 在 pos 指向的字元之前插入字元 ch。

7) 在 pos 指向的元素（如果存在）之前插入 count 個字元 ch 的副本。

8) 在 pos 指向的元素（如果存在）之前插入範圍 [first, last) 中的字元，如同透過 insert(pos - begin(), basic_string(first, last, get_allocator()))。

如果 `InputIt` 不滿足 LegacyInputIterator，則此過載不參與過載決議。

(C++11 起)

9) 在 pos 指向的元素（如果存在）之前插入初始化列表 ilist 中的元素。

10) 隱式地將 t 轉換為字串檢視 sv，如同透過 std::basic_string_view<CharT, Traits> sv = t;，然後在 index 指向的元素（如果存在）之前插入 sv 中的元素，如同透過 insert(index, sv.data(), sv.size())。

僅當 std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> 為 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 為 false 時，此過載才參與過載決議。

11) 隱式地將 t 轉換為字串檢視 sv，如同透過 std::basic_string_view<CharT, Traits> sv = t;，然後在 index 指向的元素（如果存在）之前插入 sv 的子檢視 [t_index, t_index + count) 中的字元。

如果請求的子檢視超出了 sv 的末尾，或者如果 count == npos，則生成的子檢視為 [t_index, sv.size())。
如果 t_index > sv.size()，或者如果 index > size()，則丟擲 std::out_of_range。

僅當 std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> 為 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 為 false 時，此過載才參與過載決議。

如果 pos 不是 *this 上的有效迭代器，則行為未定義。

index	-	插入內容的位置
pos	-	插入字元之前的迭代器
ch	-	要插入的字元
count	-	要插入的字元數
s	-	指向要插入的字元字串的指標
str	-	要插入的字串
first, last	-	定義要插入字元的範圍
s_index	-	要插入的 str 中第一個字元的位置
ilist	-	要從中插入字元的 std::initializer_list
t	-	要從中插入字元的物件（可轉換為 std::basic_string_view）
t_index	-	要插入的 t 中第一個字元的位置
型別要求
- `InputIt` 必須滿足 LegacyInputIterator 的要求。

[編輯] 返回值

1-5) *this

6-9) 指向第一個插入字元副本的迭代器，如果未插入字元（count == 0 或 first == last 或 ilist.size() == 0），則為 pos

10,11) *this

[編輯] 異常

1-4,10) 如果 index > size()，則丟擲 std::out_of_range。

5) 如果 index > size() 或 s_index > str.size()，則丟擲 std::out_of_range。

11) 如果 index > size() 或 t_index > sv.size()，則丟擲 std::out_of_range。

在所有情況下，如果 size() + ins_count > max_size()（其中 ins_count 是將要插入的字元數），則丟擲 std::length_error。

在所有情況下，如果 std::allocator_traits<Allocator>::allocate 丟擲異常，則重新丟擲。

(C++20 起)

如果由於任何原因丟擲異常，此函式無效果（強異常安全保證）。

[編輯] 示例

執行此程式碼

#include <cassert>
#include <iterator>
#include <string>
 
using namespace std::string_literals;
 
int main()
{
    std::string s = "xmplr";
 
    // insert(size_type index, size_type count, char ch)
    s.insert(0, 1, 'E');
    assert("Exmplr" == s);
 
    // insert(size_type index, const char* s)
    s.insert(2, "e");
    assert("Exemplr" == s);
 
    // insert(size_type index, string const& str)
    s.insert(6, "a"s);
    assert("Exemplar" == s);
 
    // insert(size_type index, string const& str,
    //        size_type s_index, size_type count)
    s.insert(8, " is an example string."s, 0, 14);
    assert("Exemplar is an example" == s);
 
    // insert(const_iterator pos, char ch)
    s.insert(s.cbegin() + s.find_first_of('n') + 1, ':');
    assert("Exemplar is an: example" == s);
 
    // insert(const_iterator pos, size_type count, char ch)
    s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '=');
    assert("Exemplar is an:== example" == s);
 
    // insert(const_iterator pos, InputIt first, InputIt last)
    {
        std::string seq = " string";
        s.insert(s.begin() + s.find_last_of('e') + 1,
            std::begin(seq), std::end(seq));
        assert("Exemplar is an:== example string" == s);
    }
 
    // insert(const_iterator pos, std::initializer_list<char>)
    s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'});
    assert("Exemplar is an:== example string." == s);
}

[編輯] 缺陷報告

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

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 7	C++98	過載 (8) 引用了不存在的過載	正確引用過載 (4)
LWG 847	C++98	沒有異常安全保證	添加了強異常安全保證
LWG 2946	C++17	過載 (10) 在某些情況下導致歧義	透過使其成為模板來避免

[編輯] 另請參閱

insert_range (C++23)	插入字元範圍 (公共成員函式) [編輯]
append	將字元追加到末尾 (公共成員函式) [編輯]
push_back	在末尾新增字元 (公共成員函式) [編輯]

編譯器支援
自由（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

cppreference.com

名稱空間

變體

檢視

操作