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

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

文字列に文字を挿入します。

1) 位置 count に文字 ch のコピーを index 個挿入します。

2) 位置 s に index が指すヌル終端文字列を挿入します。文字列の長さは、 Traits::length(s) を使用して最初のヌル文字によって決定されます。

3) 位置 [s, s + count) に範囲 index 内の文字を挿入します。範囲にはヌル文字を含めることができます。

4) 位置 str に文字列 index を挿入します。

5) 位置 str.substr(s_index, count) に、 index によって取得された部分文字列を挿入します。

6) ch が指す文字の前に文字 pos を挿入します。

7) count が指す要素（存在する場合）の前に、文字 ch のコピーを pos 個挿入します。

8) [first, last) が指す要素（存在する場合）の前に、範囲 pos からの文字を挿入します。あたかも insert(pos - begin(), basic_string(first, last, get_allocator())) によって挿入されたかのように動作します。

このオーバーロードは、 InputIt が LegacyInputIterator を満たさない場合、オーバーロード解決の候補から除外されます。

(C++11以降)

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

10) t を sv によって文字列ビュー std::basic_string_view<CharT, Traits> sv = t; に暗黙的に変換し、その後 sv が指す要素（存在する場合）の前に index からの要素を挿入します。あたかも 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 が指す要素（存在する場合）の前に、 [t_index, t_index + count) の部分ビュー sv からの文字を挿入します。

要求された部分ビューが 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 または first == last または ilist. size ( ) == 0 ）

10,11) * this

例外

1-4,10) std::out_of_range をスローする（ index > size ( ) の場合）。

5) std::out_of_range をスローする（ index > size ( ) の場合、または s_index > str. size ( ) の場合）。

11) std::out_of_range をスローする（ index > size ( ) の場合、または t_index > sv. size ( ) の場合）。

すべての場合において、 std::length_error をスローする（ size ( ) + ins_count > max_size ( ) の場合）。ここで ins_count は挿入される文字数である。

すべての場合において、 std:: allocator_traits < Allocator > :: allocate が例外をスローした場合、その例外は再スローされます。

(C++20以降)

何らかの理由で例外がスローされた場合、この関数は何も効果を持ちません（ strong exception safety guarantee ）。

例

このコードを実行

#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) が一部の場合に曖昧性を引き起こした	テンプレート化することで回避

コンパイラサポート
フリースタンディング及びホスト環境
言語
標準ライブラリ
標準ライブラリヘッダ
名前付き要件
機能テストマクロ (C++20)
言語サポートライブラリ
コンセプトライブラリ (C++20)
診断ライブラリ
メモリ管理ライブラリ
メタプログラミングライブラリ (C++11)
汎用ユーティリティライブラリ
コンテナライブラリ
イテレータライブラリ
範囲ライブラリ (C++20)
アルゴリズムライブラリ
文字列ライブラリ
テキスト処理ライブラリ
数値ライブラリ
日付と時刻のライブラリ
入出力ライブラリ
ファイルシステムライブラリ (C++17)
並行処理サポートライブラリ (C++11)
実行制御ライブラリ (C++26)
技術仕様書
シンボル索引
外部ライブラリ

クラス
basic_string
basic_string_view (C++17)
char_traits

insert_range (C++23)	文字の範囲を挿入する (公開メンバ関数)
append	末尾に文字を追加する (公開メンバ関数)
push_back	末尾に1文字を追加する (公開メンバ関数)

ja.cppreference.net

Namespaces

Variants

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

目次

パラメータ

戻り値

例外

例

不具合報告

関連項目