最終更新日時: 2025年08月31日 19時06分36秒 (JST)
Raclamusi が更新

履歴 編集

function
<string>

# std::basic_string::operator+=

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

    basic_string& operator+=(const charT* s);           // (2) C++03
    constexpr basic_string& operator+=(const charT* s); // (2) C++20

    basic_string& operator+=(charT c);           // (3) C++03
    constexpr basic_string& operator+=(charT c); // (3) C++20

    basic_string& operator+=(initializer_list<charT> il);           // (4) C++11
    constexpr basic_string& operator+=(initializer_list<charT> il); // (4) C++20

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

## 概要

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

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

- (5) : 以下の両方を満たしていること
  - `is_convertible_v<const T&, basic_string_view<charT, traits>> == true`
  - `is_convertible_v<const T&, const charT*> == false`

## 要件

- (3) : `s` は少なくとも `traits_type::length(s) + 1` の長さを持つ `charT` 型の配列を指していること。

## 効果

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

- (2) 対象オブジェクトの末尾に `s` から始まる NULL で終端された文字列が追加される。
  `append(basic_string<value_type, traits_type, allocator_type>(s))`（C++03 まで）、あるいは、`append(s)`（C++11 から）と等価。
  なお、`s` から始まる NULL 終端された文字列の長さは、`traits_type::length(s)` で求められる。

- (3) 対象オブジェクトの末尾に文字 `c` が追加される。
  `append(basic_string<value_type, traits_type, allocator_type>(1, c))` と等価。

- (4) 対象オブジェクトの末尾に初期化リスト `il` で表された文字列が追加される。
  `append(il)` と等価。

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

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

## 戻り値

`*this`

## 例外

- (1) `size() + str.size() > max_size()` の場合、`length_error` が送出される。

- (2) `size() + traits_type::length(s) > max_size()` の場合、`length_error` が送出される。

- (3) `size() + 1 > max_size()` の場合、`length_error` が送出される。

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

- (5) `size() + sv.size() > max_size()` の場合、`length_error` が送出される。

## 備考

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

## 例

    #include <iostream>
    #include <string>
    #include <string_view>

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

      std::string s2(", ");
      s1 += s2;
      std::cout << s1 << '\n';

      s1 += "world";
      std::cout << s1 << '\n';

      s1 += '!';
      std::cout << s1 << '\n';

      s1 += { ' ', ':', ')' };
      std::cout << s1 << '\n';

      using namespace std::string_view_literals;

      s1 += " :)"sv;
      std::cout << s1 << '\n';
    }

### 出力

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

## 関連項目

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

## 参照

- N2679 Initializer Lists for Standard Containers(Revision 1)
  - (4)の経緯となる提案文書
- P0254R2 Integrating `std::string_view` and `std::string`
- LWG Issue 2758. `std::string{}.assign("ABCDE", 0, 1)` is ambiguous
- LWG Issue 2946. LWG 2758's resolution missed further corrections
  - 意図しない暗黙変換防止のために`string_view`を受けるオーバーロード(5)の引数型を`const T&`に変更
- P0980R1 Making `std::string` constexpr