Add doc examples to str::from_utf8_unchecked_mut

Fixes #44461

1 files changed, 28 insertions, 0 deletions

diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index 62e84c9ebd0..858ada07344 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -382,6 +382,34 @@ pub unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
 /// See the immutable version, [`from_utf8_unchecked()`][fromutf8], for more information.
 ///
 /// [fromutf8]: fn.from_utf8_unchecked.html
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// use std::str;
+///
+/// let mut heart = vec![240, 159, 146, 150];
+/// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
+///
+/// assert_eq!("💖", heart);
+/// ```
+///
+/// Invalid UTF-8:
+///
+/// ```
+/// use std::str;
+///
+/// // Invalid bytes.
+/// let mut bytes = vec![240, 40, 140, 188];
+///
+/// // Returns a str:
+/// unsafe { str::from_utf8_unchecked_mut(&mut bytes) };
+///
+/// // from_utf8 returns an error instead:
+/// assert!(str::from_utf8(&bytes).is_err());
+/// ```
 #[inline]
 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 pub unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {