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

From cppreference.net

HTMLタグ、属性、


        タグ内のテキスト、C++固有の用語は翻訳せず、元のフォーマットを保持しました。

basic_string & insert ( size_type index, size_type count, CharT ch ) ;	(1)	(constexpr since C++20)
basic_string & insert ( size_type index, const CharT * s ) ;	(2)	(constexpr since C++20)
basic_string & insert ( size_type index, const CharT * s, size_type count ) ;	(3)	(constexpr since C++20)
basic_string & insert ( size_type index, const basic_string & str ) ;	(4)	(constexpr since C++20)
	(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以降) (constexprはC++20以降)
		(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 が指すnull終端文字列を挿入します。文字列の長さは、最初のnull文字を使用して Traits :: length ( s ) によって決定されます。

3) 位置 index に範囲

s + count

の文字を挿入します。この範囲にはナル文字を含めることができます。

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

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

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

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

8) 要素 pos が指す要素（存在する場合）の前に範囲

first

last

からの文字を挿入します。挿入は 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 が指す要素（存在する場合）の前に、 sv の部分ビュー

t_index

t_index + count

から文字を挿入します。

要求された部分ビューが sv の終端を超える場合、または count == npos の場合、結果の部分ビューは [ t_index , sv. size ( ) ) となります。
t_index > sv. size ( ) の場合、または index > size ( ) の場合、 std::out_of_range がスローされます。

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

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
Memory management library
Metaprogramming library (C++11)
General utilities library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Technical specifications
Symbols index
External libraries

Classes
basic_string
basic_string_view (C++17)
char_traits

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

cppreference.net

Namespaces

Variants

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

目次

パラメータ

戻り値

例外

例

不具合報告

関連項目