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

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

文字列ライブラリ

クラス

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)

 

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` に文字 `ch` を `count` 個挿入します。

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` が指す要素（存在する場合）の前に、文字 `ch` を `count` 個挿入します。

8) `pos` が指す要素（存在する場合）の前に、範囲 `[first, last)` の文字を挿入します。これは、`insert(pos - begin(), basic_string(first, last, get_allocator()))` と同様に行われます。

`InputIt` が LegacyInputIterator を満たさない場合、このオーバーロードはオーバーロード解決に参加しません。

(C++11以降)

9) `pos` が指す要素（存在する場合）の前に、初期化子リスト `ilist` の要素を挿入します。

10) `t` を、`std::basic_string_view sv = t;` のように文字列ビューに暗黙的に変換してから、`index` が指す要素（存在する場合）の前に `sv` の要素を挿入します。これは、`insert(index, sv.data(), sv.size())` と同様に行われます。

このオーバーロードは、`std::is_convertible_v>` が `true` であり、`std::is_convertible_v` が `false` である場合にのみ、オーバーロード解決に参加します。

11) `t` を、`std::basic_string_view 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>` が `true` であり、`std::is_convertible_v` が `false` である場合にのみ、オーバーロード解決に参加します。

`pos` が `*this` の有効なイテレータでない場合、動作は未定義です。

パラメータ

index	-	挿入するコンテンツの位置
pos	-	文字を挿入する前のイテレータ
文字	-	挿入する文字
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::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++標準に遡って適用されました。

DR	適用対象	公開された動作	正しい動作
LWG 7	C++98	オーバーロード (8) は、存在しないオーバーロードを参照していました。	正しくオーバーロード (4) を参照します。
LWG 847	C++98	例外安全性保証がなかった	強力な例外安全性保証を追加
LWG 2946	C++17	オーバーロード (10) は、一部のケースで曖昧さを引き起こしました。	テンプレートにすることで回避されました。

関連項目

insert_range (C++23)	文字の範囲を挿入します (public member function)
append	末尾に文字を追加する (public member function)
push_back	末尾に文字を追加する (public member function)