Rollup merge of #40290 - 3Hren:master, r=aturon

Add `as_bytes()` for `FromUtf8Error`.

This change allows to obtain an underlying invalid UTF-8 bytes without `FromUtf8Error` destruction. Such method may be useful for example in a library that attempts to save both valid and invalid UTF-8 strings in some struct and to be able to provide immutable access to it without destruction.

Personally without this change I ended with `Result<String, (Vec<u8>, Utf8Error)`, which almost copies the functionality of `FromUtf8Error`, but allows immutable view access.

3 files changed, 28 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/SUMMARY.md b/src/doc/unstable-book/src/SUMMARY.md
index d492903f03f..36999eb143f 100644
--- a/src/doc/unstable-book/src/SUMMARY.md
+++ b/src/doc/unstable-book/src/SUMMARY.md
@@ -79,6 +79,7 @@
 - [fmt_internals](fmt-internals.md)
 - [fn_traits](fn-traits.md)
 - [fnbox](fnbox.md)
+- [from_utf8_error_as_bytes](from_utf8_error_as_bytes.md)
 - [fundamental](fundamental.md)
 - [fused](fused.md)
 - [future_atomic_orderings](future-atomic-orderings.md)
diff --git a/src/doc/unstable-book/src/from_utf8_error_as_bytes.md b/src/doc/unstable-book/src/from_utf8_error_as_bytes.md
new file mode 100644
index 00000000000..570f779417f
--- /dev/null
+++ b/src/doc/unstable-book/src/from_utf8_error_as_bytes.md
@@ -0,0 +1,7 @@
+# `from_utf8_error_as_bytes`
+
+The tracking issue for this feature is: [#40895]
+
+[#40895]: https://github.com/rust-lang/rust/issues/40895
+
+------------------------
diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs
index 7d9d7276201..8d6cf305112 100644
--- a/src/libcollections/string.rs
+++ b/src/libcollections/string.rs
@@ -1403,6 +1403,26 @@ impl String {
 }
 
 impl FromUtf8Error {
+    /// Returns a slice of [`u8`]s bytes that were attempted to convert to a `String`.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// #![feature(from_utf8_error_as_bytes)]
+    /// // some invalid bytes, in a vector
+    /// let bytes = vec![0, 159];
+    ///
+    /// let value = String::from_utf8(bytes);
+    ///
+    /// assert_eq!(&[0, 159], value.unwrap_err().as_bytes());
+    /// ```
+    #[unstable(feature = "from_utf8_error_as_bytes", reason = "recently added", issue = "40895")]
+    pub fn as_bytes(&self) -> &[u8] {
+        &self.bytes[..]
+    }
+
     /// Returns the bytes that were attempted to convert to a `String`.
     ///
     /// This method is carefully constructed to avoid allocation. It will