5. append

最終更新日時(UTC):
が更新

履歴 編集

function
<string>

std::basic_string::append

basic_string& append(const basic_string& str);           // (1) C++03
constexpr basic_string& append(const basic_string& str); // (1) C++20

basic_string&
  append(const basic_string& str,
         size_type pos,
         size_type n);             // (2) C++03
basic_string&
  append(const basic_string& str,
         size_type pos,
         size_type n = npos);      // (2) C++14
constexpr basic_string&
  append(const basic_string& str,
         size_type pos,
         size_type n = npos);      // (2) C++20

basic_string& append(const charT* s, size_type n);           // (3) C++03
constexpr basic_string& append(const charT* s, size_type n); // (3) C++20

basic_string& append(const charT* s);           // (4) C++03
constexpr basic_string& append(const charT* s); // (4) C++20

basic_string& append(size_type n, charT c);           // (5) C++03
constexpr basic_string& append(size_type n, charT c); // (5) C++20

template <class InputIterator>
basic_string&
  append(InputIterator first,
         InputIterator last);  // (6) C++03
template <class InputIterator>
constexpr basic_string&
  append(InputIterator first,
         InputIterator last);  // (6) C++20

basic_string& append(initializer_list<charT> il);           // (7) C++11
constexpr basic_string& append(initializer_list<charT> il); // (7) C++20

// string_viewを引数に取るオーバーロード
template<class T>
basic_string&
  append(const T& t);        // (8) C++17
template<class T>
constexpr basic_string&
  append(const T& t);        // (8) C++20

template<class T>
basic_string&
  append(const T& t,
        size_type pos,
        size_type n = npos); // (9) C++17
template<class T>
constexpr basic_string&
  append(const T& t,
        size_type pos,
        size_type n = npos); // (9) C++20

概要

指定された文字列、文字、あるいは初期化リストを追加する。

テンプレートパラメータ制約

要件

  • (2) : pos <= size() であること。
  • (3) : s は少なくとも n の長さを持つ charT 型の配列を指していること。
  • (4) : s は少なくとも traits_type::length(s) + 1 の長さを持つ charT 型の配列を指していること。
  • (6) : [first, last) が有効なイテレータ範囲であること。

効果

  • (1) 対象オブジェクトの末尾に str の値が追加（コピー）される。

    • C++03 まで：append(str, 0, npos) と等価。
    • C++11 から：append(str.data(), str.size()) と等価。

  • (2) 対象オブジェクトの末尾に str の pos 以降の文字が追加される。 追加される文字列の長さ rlen は、n と str.size() - pos の小さい方である。 n == npos の場合は、 str.size() - pos が使用される。

    • C++03 まで：対象オブジェクトの末尾に str の pos 番目からの rlen 文字を追加（コピー）する。
    • C++11 から：append(str.data() + pos, rlen) と等価。

  • (3) 対象オブジェクトの末尾に s が指す長さ n の文字列が追加（コピー）される。

    • C++03 まで：append(basic_string<value_type, traits_type, allocator_type>(s, n)) と等価。
    • C++11 から：対象オブジェクトの末尾に s からの n 文字を追加（コピー）する。

  • (4) 対象オブジェクトの末尾に s が指す NULL 終端された文字列が追加（コピー）される。

    • C++03 まで：append(basic_string<value_type, traits_type, allocator_type>(s)) と等価。
    • C++11 から：append(s, traits_type::length(s)) と等価。

  • (5) 対象オブジェクトの末尾に、文字 c が n 文字追加（コピー）される。

    • append(basic_string<value_type, traits_type, allocator_type>(n, c)) と等価。

  • (6) 対象オブジェクトの末尾に、イテレータ範囲 [first, last) の文字列が追加（コピー）される。

    • append(basic_string<value_type, traits_type, allocator_type>(first, last)) と等価。

  • (7) 対象オブジェクトの末尾に初期化リスト il で表された文字列が追加される。

    • append(il.begin(), il.end()) と等価。

  • (8) 対象オブジェクトの末尾に、basic_string_view<charT, traits>に変換可能なtが参照する範囲の文字列が追加される。
    以下と等価。 

    basic_string_view<charT, traits> sv = t;
return append(sv.data(), sv.size());

  • (9) 対象オブジェクトの末尾に、basic_string_view<charT, traits>に変換可能なtの指定された範囲の文字列が追加される。

    • 文字列の長さ rlen は、n と sv.size()- pos の小さい方である。
      以下と等価。 
      basic_string_view<charT, traits> sv = t;
return append(sv.substr(pos, n));

戻り値

*this

例外

  • (1) C++03 まで：size() >= npos - str.size() の場合、length_error が送出される。
    C++11 から：size() + str.size() > max_size() の場合、length_error が送出される。

  • (2) pos > str.size() の場合、out_of_range が送出される。
    C++03 まで：size() >= npos - rlen の場合、length_error が送出される。
    C++11 から：size() + rlen > max_size() の場合、length_error が送出される。

  • (3) C++03 まで：size() >= npos - n の場合、length_error が送出される。
    C++11 から：size() + n > max_size() の場合、length_error が送出される。

  • (4) C++03 まで：size() >= npos - traits::length(s) の場合、length_error が送出される。
    C++11 から：size() + traits::length(s) > max_size() の場合、length_error が送出される。

  • (5) C++03 まで：size() >= npos - n の場合、length_error が送出される。
    C++11 から：size() + n > max_size() の場合、length_error が送出される。

  • (6) C++03 まで：size() >= npos - distance(first, last) の場合、length_error が送出される。
    C++11 から：size() + distance(first, last) > max_size() の場合、length_error が送出される。

  • (7) size() + il.size() > max_size() の場合、length_error が送出される。

備考

本メンバ関数の呼び出しによって、対象オブジェクトの要素への参照、ポインタ、および、イテレータは無効になる可能性がある。

例

#include <iostream>
#include <string>

int main()
{
  std::string s1("Hello");
  std::cout << s1 << '\n';

  // (2)
  std::string s2("Hell, world!");
  s1.append(s2, 4, 2);
  std::cout << s1 << '\n';

  // (2)
  s1.append("worldworldworld", 5);
  std::cout << s1 << '\n';

  // (5)
  s1.append(2, '!');
  std::cout << s1 << '\n';

  // (7)
  s1.append({ ' ', ':', ')' });
  std::cout << s1 << '\n';

  // (8)
  std::string s8 = "Hello";
  s8.append(std::string_view{"Hi, world"}.substr(2));
  std::cout << s8 << std::endl;
}

出力

Hello
Hello, 
Hello, world
Hello, world!!
Hello, world!! :)
Hello, world

関連項目

名前 説明
operator+= 文字／文字列を追加する
push_back 文字を追加する
insert 文字／文字列を挿入する
operator+ 文字列を連結する

参照