Implement Div and DivAssign for PathBuf

src/libstd/path.rs

@@ -77,7 +77,7 @@ use crate::fs;
 use crate::hash::{Hash, Hasher};
 use crate::io;
 use crate::iter::{self, FusedIterator};
-use crate::ops::{self, Deref};
+use crate::ops::{self, Deref, Div, DivAssign};
 use crate::rc::Rc;
 use crate::str::FromStr;
 use crate::sync::Arc;
@@ -1708,6 +1708,120 @@ impl AsRef<OsStr> for PathBuf {
     }
 }
 
+/// Implements the `/` operator for concatenating two paths.
+///
+/// This consumes the `PathBuf` on the left-hand side and re-uses its buffer (growing it if
+/// necessary). This is done to avoid allocating a new `PathBuf` and copying the entire contents on
+/// every operation, which would lead to `O(n^2)` running time when building an `n`-byte path by
+/// repeated concatenation.
+///
+/// The path on the right-hand side is only borrowed; its contents are copied into the returned
+/// `PathBuf`.
+///
+/// # Examples
+///
+/// Concatenating two `PathBuf`s takes the first by value and borrows the second:
+///
+/// ```
+/// # use std::path::PathBuf;
+/// let a = PathBuf::from("hello");
+/// let b = PathBuf::from("world");
+/// let c = a + &b;
+/// // `a` is moved and can no longer be used here.
+/// ```
+///
+/// If you want to keep using the first `PathBuf`, you can clone it and append to the clone instead:
+///
+/// ```
+/// # use std::path::PathBuf;
+/// let a = PathBuf::from("hello");
+/// let b = PathBuf::from("world");
+/// let c = a.clone() + &b;
+/// // `a` is still valid here.
+/// ```
+///
+/// Concatenating `&Path` slices can be done by converting the first to a `PathBuf`:
+///
+/// ```
+/// # use std::path::Path;
+/// let a = Path::new("hello");
+/// let b = Path::new("world");
+/// let c = a.to_path_buf() + b;
+/// ```
+#[stable(feature = "div_concat_pathbuf", since = "1.38.0")]
+impl Div<&Path> for PathBuf {
+    type Output = PathBuf;
+    fn div(mut self, rhs: &Path) -> Self::Output {
+        self.push(rhs);
+        self
+    }
+}
+
+/// Implements the `/` operator for concatenating two paths.
+///
+/// This implementation takes a `&str` instead of a `&Path`. Refer to the `&Path` implementation for
+/// more details.
+#[stable(feature = "div_concat_pathbuf", since = "1.38.0")]
+impl Div<&str> for PathBuf {
+    type Output = PathBuf;
+    fn div(mut self, rhs: &str) -> Self::Output {
+        self.push(rhs);
+        self
+    }
+}
+
+
+/// Implements the `/` operator for concatenating two paths.
+///
+/// This implementation takes a `&OsStr` instead of a `&Path`. Refer to the `&Path` implementation
+/// for more details.
+#[stable(feature = "div_concat_pathbuf", since = "1.38.0")]
+impl Div<&OsStr> for PathBuf {
+    type Output = PathBuf;
+    fn div(mut self, rhs: &OsStr) -> Self::Output {
+        self.push(rhs);
+        self
+    }
+}
+
+/// Implements the `/=` operator for appending to a `PathBuf`.
+///
+/// This has the same behavior as the [`push`] method.
+///
+/// [`push`]: struct.PathBuf.html#method.push
+#[stable(feature = "div_concat_pathbuf", since = "1.38.0")]
+impl DivAssign<&Path> for PathBuf {
+    fn div_assign(&mut self, rhs: &Path) {
+        self.push(rhs);
+    }
+}
+
+
+/// Implements the `/=` operator for appending to a `PathBuf`.
+///
+/// This has the same behavior as the [`push`] method.
+///
+/// [`push`]: struct.PathBuf.html#method.push
+#[stable(feature = "div_concat_pathbuf", since = "1.38.0")]
+impl DivAssign<&str> for PathBuf {
+    fn div_assign(&mut self, rhs: &str) {
+        self.push(rhs);
+    }
+}
+
+
+/// Implements the `/=` operator for appending to a `PathBuf`.
+///
+/// This has the same behavior as the [`push`] method.
+///
+/// [`push`]: struct.PathBuf.html#method.push
+#[stable(feature = "div_concat_pathbuf", since = "1.38.0")]
+impl DivAssign<&OsStr> for PathBuf {
+    fn div_assign(&mut self, rhs: &OsStr) {
+        self.push(rhs);
+    }
+}
+
 /// A slice of a path (akin to [`str`]).
 ///
 /// This type supports a number of operations for inspecting a path, including