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

出自cppreference.com
< cpp‎ | string‎ | basic string
 
C++
 
字元串庫
 
std::basic_string
 
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 );
(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 所指向的空終止字元串。字元串的長度由首個空字元，通過 Traits::length(s) 確定。
3) 在位置 index 插入範圍 [s, s + count) 中的字元。範圍可以包含空字元。
4) 在位置 index 插入字元串 str。
5) 在位置 index 插入由 str.substr(s_index, count) 獲得的字元串。
6) 在 pos 所指向的字元前插入字元 ch。
7) 在 pos 所指向的元素（如果存在）前插入 count 個字元 ch 的副本。
8) 如同用 insert(pos - begin(), basic_string(first, last, get_allocator())) 在 pos 所指向的元素（如果存在）前插入來自範圍 [first, last) 的元素。

如果 InputIt 不滿足老式輸入迭代器 (LegacyInputIterator) ，那麼此重載不參與重載決議。

(C++11 起)
9) 在 pos 所指向的元素（如果存在）前插入來自初始化式列表 ilist 的字元。
10) 如同用 std::basic_string_view<CharT, Traits> sv = t; 將 t 隱式轉換到字元串視圖 sv ，然後如同用 insert(pos, sv.data(), sv.size()) 在 pos 所指向的元素（如果存在）前插入來自 sv 的元素。
此重載只有在 std::is_convertible_v<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> 是 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 是 false 時才會參與重載決議。
11) 如同用 std::basic_string_view<CharT, Traits> sv = t; 將 t 隱式轉換到字元串視圖 sv ，然後在 pos 所指向的元素（如果存在）前插入來自 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) 指代首個被插入字元的迭代器，或者在未插入字元時就是 pos（count == 0，ilist.size() == 0 或 first == last）
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() 時拋出 std::length_error，其中 ins_count 是將要插入的字元數。

在所有情況下，如果 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 7C++98重載 (8) 的效果錯誤地涉及了實際不存在的重載修正為正確地涉及重載 (4)
LWG 847C++98沒有異常安全保證添加強異常安全保證
LWG 2946C++17重載 (10) 在某些情況下會導致歧義通過使之為模板來避免

[編輯] 參閱

(C++23)
插入範圍內的字元
(公開成員函數) [編輯]
後附字元到結尾
(公開成員函數) [編輯]
後附字元到結尾
(公開成員函數) [編輯]
取自「https://zh.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/insert&oldid=90648」