path : operator/=, append, operator/を追加 #513

faithandbrave · faithandbrave · commit 4da501fb980f · 2018-02-02T15:28:26.000+09:00
diff --git a/editors_doc/page_names.md b/editors_doc/page_names.md
@@ -27,6 +27,7 @@ cpprefjpサイトでは、ページファイル名の付け方について、い
 | `operator-=`  | 減算の複合代入 | `op_minus_assign` | |
 | `operator*=`  | 乗算の複合代入 | `op_multiply_assign` | |
 | `operator/=`  | 除算の複合代入 | `op_divide_assign` | |
+| `operator/=`  | パス要素加算の複合代入 | `op_append_assign` | この演算子はファイルシステムの文脈で特殊な意味を持つ。<br/> 対応するメンバ関数`append()`と合わせた命名 |
 | `operator%=`  | 剰余の複合代入 | `op_modulo_assign` | |
 | `operator<<=` | 左ビットシフトの複合代入 | `op_left_shift_assign` | |
 | `operator>>=` | 右ビットシフトの複合代入 | `op_right_shift_assign` | |
@@ -49,6 +50,7 @@ cpprefjpサイトでは、ページファイル名の付け方について、い
 | `operator-` (二項) | 減算演算子  | `op_minus`         | |
 | `operator*` (二項) | 乗算演算子  | `op_multiply`      | |
 | `operator/` (二項) | 除算演算子  | `op_divide`        | |
+| `operator/` (二項) | パス要素加算の演算子  | `op_append` | この演算子はファイルシステムの文脈で特殊な意味を持つ |
 | `operator%` (二項) | 剰余演算子  | `op_modulo`        | |
 | `operator&` | ビット論理積演算子 | `op_and` | |
 | `operator`<code>&#x7C;</code> | ビット論理和演算子 | `op_or` | |
diff --git a/reference/filesystem/path.md b/reference/filesystem/path.md
@@ -37,8 +37,8 @@ namespace std::filesystem {
 
 | 名前 | 説明 | 対応バージョン |
 |------|------|----------------|
-| `operator/=` | パス要素を加算する | C++17 |
-| `append`     | パス要素を加算する | C++17 |
+| [`operator/=`](path/op_append_assign.md) | パス要素を加算する | C++17 |
+| [`append`](path/append.md) | パス要素を加算する | C++17 |
 | `operator+=` | パス文字列を加算する | C++17 |
 | `concat`     | パス文字列を加算する | C++17 |
 
@@ -171,7 +171,7 @@ namespace std::filesystem {
 
 | 名前 | 説明 | 対応バージョン |
 |------|------|----------------|
-| `operator/` | 2つのパスを連結する | C++17 |
+| [`operator/`](path/op_append.md) | 2つのパスを連結する | C++17 |
 
 ### 入出力
 
diff --git a/reference/filesystem/path/append.md b/reference/filesystem/path/append.md
@@ -0,0 +1,188 @@
+# operator/=
+* filesystem[meta header]
+* std::filesystem[meta namespace]
+* path[meta class]
+* function[meta id-type]
+* cpp17[meta cpp]
+
+```cpp
+template <class Source>
+path& append(const Source& source);                    // (1)
+
+template <class InputIterator>
+path& append(InputIterator first, InputIterator last); // (2)
+```
+
+## 概要
+パス要素を加算する。
+
+
+## 効果
+- (1) : `return operator/=(path(source))`と同等
+- (2) : `return operator/=(path(first, last))`と同等
+
+
+## 戻り値
+`*this`
+
+
+## 例
+### POSIXベースシステムでの例
+```cpp example
+#include <iostream>
+#include <filesystem>
+
+namespace fs = std::filesystem;
+
+int main()
+{
+  // 通常のユースケース
+  // 後ろにディレクトリを加算する
+  {
+    fs::path p = "foo";
+    p.append("bar");
+    std::cout << "a : " << p << std::endl;
+  }
+
+  // 左辺の末尾にディレクトリ区切り文字が付いていてもよい
+  {
+    fs::path p = "foo/";
+    p.append("bar");
+    std::cout << "b : " << p << std::endl;
+  }
+
+  // 右辺が空のパスだった場合、ディレクトリ区切り文字だけ追加される
+  {
+    fs::path p = "foo";
+    p.append("");
+    std::cout << "c : " << p << std::endl;
+  }
+
+  // 右辺にルートディレクトリを含むパスを指定した場合、
+  // 右辺を代入する動作となる
+  {
+    fs::path p = "foo";
+    p.append("/bar");
+    std::cout << "d : " << p << std::endl;
+  }
+}
+```
+
+#### 出力
+```
+a : "foo/bar"
+b : "foo/bar"
+c : "foo/"
+d : "/bar"
+```
+
+### Windowsでの例
+```cpp
+#include <iostream>
+#include <filesystem>
+
+namespace fs = std::filesystem;
+
+int main()
+{
+  // 通常のユースケース
+  // 後ろにディレクトリを加算する
+  {
+    fs::path p = "foo";
+    p.append("bar");
+    std::cout << "a : " << p << std::endl;
+  }
+
+  // 左辺の末尾にディレクトリ区切り文字が付いていてもよい
+  {
+    fs::path p = "C:/foo/";
+    p.append("bar");
+    std::cout << "b : " << p << std::endl;
+  }
+
+  // 右辺が空のパスだった場合、ディレクトリ区切り文字だけ追加される
+  {
+    fs::path p = "foo";
+    p.append("");
+    std::cout << "c : " << p << std::endl;
+  }
+
+  // 左辺がルート名を持っていて、ルートディレクトリを持たず、
+  // 右辺が空の場合、ディレクトリ区切り文字は追加されない
+  {
+    fs::path p = "C:";
+    p.append("");
+    std::cout << "d : " << p << std::endl;
+  }
+
+  // 右辺にルートディレクトリを含むパスを指定した場合、
+  // 右辺を代入する動作となる
+  {
+    fs::path p = "foo";
+    p.append("C:/bar");
+    std::cout << "d : " << p << std::endl;
+  }
+
+  // 左辺と右辺のディレクトリ区切り文字の有無に関わらず連結される
+  // (POSIXと違って、ルートディレクトリが`/`ではないため、
+  //  右辺の開始をディレクトリ区切り文字にできる)
+  {
+    fs::path p = "foo";
+    p.append("/bar");
+    std::cout << "e : " << p << std::endl;
+  }
+
+  // 左辺がルート名を持ち、ルートディレクトリを持たないパスで、
+  // 右辺に空のパスを指定した場合、ディレクトリ区切り文字は追加されない
+  {
+    fs::path p = "C:";
+    p.append("");
+    std::cout << "f : " << p << std::endl;
+  }
+
+  // 左辺がカレントディレクトリに依存した絶対パスの場合、
+  // 相対パスを追加するとカレントディレクトリに依存したパス部分が右辺で上書きされる
+  {
+    fs::path p = "C:foo";
+    p.append("/bar");
+    std::cout << "g : " << p << std::endl;
+  }
+
+  // 左辺がカレントディレクトリに依存した絶対パスで、
+  // 右辺もカレントディレクトリに依存した絶対パスの場合、
+  // 左辺のパスに、右辺のカレントディレクトリに依存した部分が加算される
+  {
+    fs::path p = "C:foo";
+    p.append("C:bar");
+    std::cout << "h : " << p << std::endl;
+  }
+}
+```
+
+#### 出力
+```
+a : "foo\bar"
+b : "C:\foo"
+c : "foo\"
+d : "C:\bar"
+e : "foo\bar"
+f : "C:"
+g : "C:\bar"
+h : "C:foo\bar"
+```
+
+Windowsでの例は、Visual C++が正式にファイルシステムライブラリをサポートしていないことから、未検証のサンプルコード・出力となっている。
+
+## バージョン
+### 言語
+- C++17
+
+### 処理系
+- [Clang](/implementation.md#clang):
+- [GCC, C++17 mode](/implementation.md#gcc): 8.1
+- [Visual C++](/implementation.md#visual_cpp):
+
+### 備考
+- GCC 8.1 (SVN) の`operator/=`では、ルートディレクトリを持つパスを加算すると、左辺が削除されないバグがある
+    - [Bug 84159 - `filesystem::path::operator/=` with has root directory path](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=84159)
+
diff --git a/reference/filesystem/path/op_append.md b/reference/filesystem/path/op_append.md
@@ -0,0 +1,167 @@
+# operator/
+* filesystem[meta header]
+* std::filesystem[meta namespace]
+* function[meta id-type]
+* cpp17[meta cpp]
+
+```cpp
+namespace std::filesystem {
+  path operator/(const path& x, const path& y);
+}
+```
+
+## 概要
+2つのパス要素を連結する。
+
+
+## 効果
+以下と同等の効果を持つ：
+
+```cpp
+return path(lhs) /= rhs;
+```
+* /=[link op_append_assign.md]
+
+
+## 例
+### POSIXベースシステムでの例
+```cpp example
+#include <iostream>
+#include <filesystem>
+
+namespace fs = std::filesystem;
+
+int main()
+{
+  // 通常のユースケース
+  // 後ろにディレクトリを加算する
+  {
+    fs::path p = fs::path("foo") / "bar";
+    std::cout << "a : " << p << std::endl;
+  }
+
+  // 左辺の末尾にディレクトリ区切り文字が付いていてもよい
+  {
+    fs::path p = fs::path("foo/") / "bar";
+    std::cout << "b : " << p << std::endl;
+  }
+
+  // 右辺が空のパスだった場合、ディレクトリ区切り文字だけ追加される
+  {
+    fs::path p = fs::path("foo") / "";
+    std::cout << "c : " << p << std::endl;
+  }
+
+  // 右辺にルートディレクトリを含むパスを指定した場合、
+  // 右辺を代入する動作となる
+  {
+    fs::path p = fs::path("foo") / "/bar";
+    std::cout << "d : " << p << std::endl;
+  }
+}
+```
+
+#### 出力
+```
+a : "foo/bar"
+b : "foo/bar"
+c : "foo/"
+d : "/bar"
+```
+
+### Windowsでの例
+```cpp
+#include <iostream>
+#include <filesystem>
+
+namespace fs = std::filesystem;
+
+int main()
+{
+  // 通常のユースケース
+  // 後ろにディレクトリを加算する
+  {
+    fs::path p = fs::path("foo") / "bar";
+    std::cout << "a : " << p << std::endl;
+  }
+
+  // 左辺の末尾にディレクトリ区切り文字が付いていてもよい
+  {
+    fs::path p = fs::path("C:/foo/") / "bar";
+    std::cout << "b : " << p << std::endl;
+  }
+
+  // 右辺が空のパスだった場合、ディレクトリ区切り文字だけ追加される
+  {
+    fs::path p = fs::path("foo") / "";
+    std::cout << "c : " << p << std::endl;
+  }
+
+  // 左辺がルート名を持っていて、ルートディレクトリを持たず、
+  // 右辺が空の場合、ディレクトリ区切り文字は追加されない
+  {
+    fs::path p = fs::path("C:") / "";
+    std::cout << "d : " << p << std::endl;
+  }
+
+  // 右辺にルートディレクトリを含むパスを指定した場合、
+  // 右辺を代入する動作となる
+  {
+    fs::path p = fs::path("foo") / "C:/bar";
+    std::cout << "d : " << p << std::endl;
+  }
+
+  // 左辺と右辺のディレクトリ区切り文字の有無に関わらず連結される
+  // (POSIXと違って、ルートディレクトリが`/`ではないため、
+  //  右辺の開始をディレクトリ区切り文字にできる)
+  {
+    fs::path p = fs::path("foo") / "/bar";
+    std::cout << "e : " << p << std::endl;
+  }
+
+  // 左辺がルート名を持ち、ルートディレクトリを持たないパスで、
+  // 右辺に空のパスを指定した場合、ディレクトリ区切り文字は追加されない
+  {
+    fs::path p = fs::path("C:") / "";
+    std::cout << "f : " << p << std::endl;
+  }
+
+  // 左辺がカレントディレクトリに依存した絶対パスの場合、
+  // 相対パスを追加するとカレントディレクトリに依存したパス部分が右辺で上書きされる
+  {
+    fs::path p = fs::path("C:foo") / "/bar";
+    std::cout << "g : " << p << std::endl;
+  }
+
+  // 左辺がカレントディレクトリに依存した絶対パスで、
+  // 右辺もカレントディレクトリに依存した絶対パスの場合、
+  // 左辺のパスに、右辺のカレントディレクトリに依存した部分が加算される
+  {
+    fs::path p = fs::path("C:foo") / "C:bar";
+    std::cout << "h : " << p << std::endl;
+  }
+}
+```
+
+#### 出力
+```
+a : "foo\bar"
+b : "C:\foo"
+c : "foo\"
+d : "C:\bar"
+e : "foo\bar"
+f : "C:"
+g : "C:\bar"
+h : "C:foo\bar"
+```
+
+Windowsでの例は、Visual C++が正式にファイルシステムライブラリをサポートしていないことから、未検証のサンプルコード・出力となっている。
+
+## バージョン
+### 言語
+- C++17
+
+### 処理系
+- [Clang](/implementation.md#clang):
+- [GCC, C++17 mode](/implementation.md#gcc): 8.1
+- [Visual C++](/implementation.md#visual_cpp):
diff --git a/reference/filesystem/path/op_append_assign.md b/reference/filesystem/path/op_append_assign.md
