library/core/src/str/converts.rs

   1 //! Ways to create a `str` from bytes slice.
   2
   3 use crate::mem;
   4
   5 use super::validations::run_utf8_validation;
   6 use super::Utf8Error;
   7
   8 /// Converts a slice of bytes to a string slice.
   9 ///
  10 /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
  11 /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
  12 /// the two. Not all byte slices are valid string slices, however: [`&str`] requires
  13 /// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid
  14 /// UTF-8, and then does the conversion.
  15 ///
  16 /// [`&str`]: str
  17 /// [byteslice]: slice
  18 ///
  19 /// If you are sure that the byte slice is valid UTF-8, and you don't want to
  20 /// incur the overhead of the validity check, there is an unsafe version of
  21 /// this function, [`from_utf8_unchecked`], which has the same
  22 /// behavior but skips the check.
  23 ///
  24 /// If you need a `String` instead of a `&str`, consider
  25 /// [`String::from_utf8`][string].
  26 ///
  27 /// [string]: ../../std/string/struct.String.html#method.from_utf8
  28 ///
  29 /// Because you can stack-allocate a `[u8; N]`, and you can take a
  30 /// [`&[u8]`][byteslice] of it, this function is one way to have a
  31 /// stack-allocated string. There is an example of this in the
  32 /// examples section below.
  33 ///
  34 /// [byteslice]: slice
  35 ///
  36 /// # Errors
  37 ///
  38 /// Returns `Err` if the slice is not UTF-8 with a description as to why the
  39 /// provided slice is not UTF-8.
  40 ///
  41 /// # Examples
  42 ///
  43 /// Basic usage:
  44 ///
  45 /// ```
  46 /// use std::str;
  47 ///
  48 /// // some bytes, in a vector
  49 /// let sparkle_heart = vec![240, 159, 146, 150];
  50 ///
  51 /// // We know these bytes are valid, so just use `unwrap()`.
  52 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
  53 ///
  54 /// assert_eq!("💖", sparkle_heart);
  55 /// ```
  56 ///
  57 /// Incorrect bytes:
  58 ///
  59 /// ```
  60 /// use std::str;
  61 ///
  62 /// // some invalid bytes, in a vector
  63 /// let sparkle_heart = vec![0, 159, 146, 150];
  64 ///
  65 /// assert!(str::from_utf8(&sparkle_heart).is_err());
  66 /// ```
  67 ///
  68 /// See the docs for [`Utf8Error`] for more details on the kinds of
  69 /// errors that can be returned.
  70 ///
  71 /// A "stack allocated string":
  72 ///
  73 /// ```
  74 /// use std::str;
  75 ///
  76 /// // some bytes, in a stack-allocated array
  77 /// let sparkle_heart = [240, 159, 146, 150];
  78 ///
  79 /// // We know these bytes are valid, so just use `unwrap()`.
  80 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
  81 ///
  82 /// assert_eq!("💖", sparkle_heart);
  83 /// ```
  84 #[stable(feature = "rust1", since = "1.0.0")]
  85 #[rustc_const_unstable(feature = "const_str_from_utf8", issue = "91006")]
  86 pub const fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
  87     // This should use `?` again, once it's `const`
  88     match run_utf8_validation(v) {
  89         Ok(_) => {
  90             // SAFETY: validation succeeded.
  91             Ok(unsafe { from_utf8_unchecked(v) })
  92         }
  93         Err(err) => Err(err),
  94     }
  95 }
  96
  97 /// Converts a mutable slice of bytes to a mutable string slice.
  98 ///
  99 /// # Examples
 100 ///
 101 /// Basic usage:
 102 ///
 103 /// ```
 104 /// use std::str;
 105 ///
 106 /// // "Hello, Rust!" as a mutable vector
 107 /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
 108 ///
 109 /// // As we know these bytes are valid, we can use `unwrap()`
 110 /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
 111 ///
 112 /// assert_eq!("Hello, Rust!", outstr);
 113 /// ```
 114 ///
 115 /// Incorrect bytes:
 116 ///
 117 /// ```
 118 /// use std::str;
 119 ///
 120 /// // Some invalid bytes in a mutable vector
 121 /// let mut invalid = vec![128, 223];
 122 ///
 123 /// assert!(str::from_utf8_mut(&mut invalid).is_err());
 124 /// ```
 125 /// See the docs for [`Utf8Error`] for more details on the kinds of
 126 /// errors that can be returned.
 127 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 128 #[rustc_const_unstable(feature = "const_str_from_utf8", issue = "91006")]
 129 pub const fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> {
 130     // This should use `?` again, once it's `const`
 131     match run_utf8_validation(v) {
 132         Ok(_) => {
 133             // SAFETY: validation succeeded.
 134             Ok(unsafe { from_utf8_unchecked_mut(v) })
 135         }
 136         Err(err) => Err(err),
 137     }
 138 }
 139
 140 /// Converts a slice of bytes to a string slice without checking
 141 /// that the string contains valid UTF-8.
 142 ///
 143 /// See the safe version, [`from_utf8`], for more information.
 144 ///
 145 /// # Safety
 146 ///
 147 /// The bytes passed in must be valid UTF-8.
 148 ///
 149 /// # Examples
 150 ///
 151 /// Basic usage:
 152 ///
 153 /// ```
 154 /// use std::str;
 155 ///
 156 /// // some bytes, in a vector
 157 /// let sparkle_heart = vec![240, 159, 146, 150];
 158 ///
 159 /// let sparkle_heart = unsafe {
 160 ///     str::from_utf8_unchecked(&sparkle_heart)
 161 /// };
 162 ///
 163 /// assert_eq!("💖", sparkle_heart);
 164 /// ```
 165 #[inline]
 166 #[must_use]
 167 #[stable(feature = "rust1", since = "1.0.0")]
 168 #[rustc_const_stable(feature = "const_str_from_utf8_unchecked", since = "1.55.0")]
 169 pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
 170     // SAFETY: the caller must guarantee that the bytes `v` are valid UTF-8.
 171     // Also relies on `&str` and `&[u8]` having the same layout.
 172     unsafe { mem::transmute(v) }
 173 }
 174
 175 /// Converts a slice of bytes to a string slice without checking
 176 /// that the string contains valid UTF-8; mutable version.
 177 ///
 178 /// See the immutable version, [`from_utf8_unchecked()`] for more information.
 179 ///
 180 /// # Examples
 181 ///
 182 /// Basic usage:
 183 ///
 184 /// ```
 185 /// use std::str;
 186 ///
 187 /// let mut heart = vec![240, 159, 146, 150];
 188 /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
 189 ///
 190 /// assert_eq!("💖", heart);
 191 /// ```
 192 #[inline]
 193 #[must_use]
 194 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 195 #[rustc_const_unstable(feature = "const_str_from_utf8_unchecked_mut", issue = "91005")]
 196 pub const unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
 197     // SAFETY: the caller must guarantee that the bytes `v`
 198     // are valid UTF-8, thus the cast to `*mut str` is safe.
 199     // Also, the pointer dereference is safe because that pointer
 200     // comes from a reference which is guaranteed to be valid for writes.
 201     unsafe { &mut *(v as *mut [u8] as *mut str) }
 202 }