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

basic_string& append( size_type count, CharT ch );	(1)	(C++20 から constexpr)
basic_string& append( const CharT* s, size_type count );	(2)	(C++20 から constexpr)
basic_string& append( const CharT* s );	(3)	(C++20 から constexpr)
template< class SV > basic_string& append( const SV& t );	(4)	(C++17 から) (C++20 から constexpr)
template< class SV > basic_string& append( const SV& t, size_type pos, size_type count = npos );	(5)	(C++17 から) (C++20 から constexpr)
basic_string& append( const basic_string& str );	(6)	(C++20 から constexpr)
basic_string& append( const basic_string& str, size_type pos, size_type count );	(7)	(C++14 まで)
basic_string& append( const basic_string& str, size_type pos, size_type count = npos );	(7)		(C++14 から) (C++20 から constexpr)
template< class InputIt > basic_string& append( InputIt first, InputIt last );	(8)	(C++20 から constexpr)
basic_string& append( std::initializer_list<CharT> ilist );	(9)	(C++11 から) (C++20 から constexpr)

文字列に追加の文字を追加します。

1) 文字 count のコピー ch 個を追加します。

2) 範囲 [s, s + count) 内の文字を追加します。

[s, s + count) が有効な範囲でない場合、動作は未定義です。

3) return append(s, Traits::length(s)); と同等です。

4,5) sv から構築された文字列ビュー t 内の文字を追加します。

t のみが指定された場合、sv 内のすべての文字が追加されます。
pos も指定された場合:
- count が npos の場合、sv 内の pos 以降のすべての文字が追加されます。
- それ以外の場合、std::min(count, sv.size() - pos) 内の sv から始まる pos 文字が追加されます。

これらのオーバーロードは、以下の条件がすべて満たされる場合にのみオーバーロード解決に参加します:

std::is_convertible_v<const SV&, std::basic_string_view<CharT, Traits>> は true である。
std::is_convertible_v<const SV&, const CharT*> は false である。

4) std::basic_string_view<CharT, Traits> sv = t;
return append(sv.data(), sv.size()); と同等です。

5) std::basic_string_view<CharT, Traits> sv = t;
return append(sv.substr(pos, count)); と同等です。

6,7) 別の文字列 str 内の文字を追加します。

str のみが指定された場合、その中のすべての文字が追加されます。
pos も指定された場合:
- count が npos の場合、str 内の pos 以降のすべての文字が追加されます。
- それ以外の場合、std::min(count, str.size() - pos) 内の str から始まる pos 文字が追加されます。

6) return append(str.data(), str.size()); と同等です。

7) return append(std::basic_string_view<CharT, Traits>
(str).substr(pos, count)); と同等です。

(C++20 から)

8) return append(basic_string(first, last, get_allocator())); と同等です。

このオーバーロードは、が整数型である場合、オーバーロード (1)`InputIt` と同じ効果を持ちます。	(C++11 まで)
このオーバーロードは、`InputIt` が LegacyInputIterator の要件を満たす場合にのみオーバーロード解決に参加します。 (C++11 から)	9)

と同等です。return append(ilist.begin(), ilist.size());

パラメータ

count	-	追加する文字数
ch	-	追加する文字値
s	-	追加する文字列へのポインタ
t	-	std::basic_string_view に変換可能なオブジェクト（追加する文字を含む）
pos	-	追加する最初の文字のインデックス
str	-	追加する文字列
first, last	-	追加する文字の範囲
ilist	-	追加する文字を含む初期化子リスト

戻り値

* this

計算量

標準的な計算量の保証はありません。一般的な実装は std::vector::insert() と同様の動作をします。

例外

操作によって size() が max_size() を超える場合、 std::length_error を送出する。

5) もし pos > sv. size ( ) が true の場合、 std::out_of_range をスローする。

7) pos > str. size ( ) が true の場合、 std::out_of_range をスローする。

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

例

このコードを実行

#include <cassert>
#include <string>
int main()
{
    std::string str = "std::string";
    const char* cptr = "C-string";
    const char carr[] = "range";
    std::string result;
    // 1) 文字を3回追加
    // 注: これは「CharT」を受け入れる唯一のオーバーロードです
    result.append(3, '*');
    assert(result == "***");
    // 2) 固定長C文字列を追加
    result.append(cptr, 5);
    assert(result == "***C-str");
    // 3) ヌル終端C文字列を追加
    // 注: 「append」は*thisを返すため、呼び出しを連鎖できます
    result.append(1, ' ').append(cptr);
    assert(result == "***C-str C-string");
    // 6) 文字列全体を追加
    result.append(1, ' ').append(str);
    assert(result == "***C-str C-string std::string");
    // 7) 文字列の一部を追加
    result.append(str, 3, 2);
    assert(result == "***C-str C-string std::string::");
    // 8) 範囲を追加
    result.append(&carr[2], &carr[3]);
    assert(result == "***C-str C-string std::string::n");
    // 9) 初期化子リストを追加
    result.append({'p', 'o', 's'});
    assert(result == "***C-str C-string std::string::npos");
}

不具合報告

以下の動作変更の欠陥報告書は、以前に公開されたC++規格に対して遡及的に適用されました。

DR	適用対象	公開時の動作	正しい動作
LWG 847	C++98	例外安全性保証がなかった	強い例外安全性保証を追加
LWG 2250	C++98	オーバーロード (7) の動作は pos > str. size ( ) の場合 true なら未定義	この場合常に例外をスロー
LWG 2788	C++98	オーバーロード (8) は一時文字列の構築にデフォルト構築されたアロケータを使用	アロケータを get_allocator() から取得
LWG 2946	C++17	オーバーロード (4) は一部の場合に曖昧性を引き起こす	テンプレート化することで回避

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

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

append_range (C++23)	範囲の文字を末尾に追加する (公開メンバ関数)
operator+=	文字を末尾に追加する (公開メンバ関数)
strcat	2つの文字列を連結する (関数)
strncat	2つの文字列の特定の量の文字を連結する (関数)
wcscat	ワイド文字列のコピーを別のワイド文字列に追加する (関数)
wcsncat	1つのワイド文字列から別のワイド文字列へ特定の量のワイド文字を追加する (関数)

ja.cppreference.net

Namespaces

Variants

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

目次

パラメータ

戻り値

計算量

例外

例

不具合報告

関連項目