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]: ../../std/primitive.slice.html
  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]: ../../std/primitive.slice.html
  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 pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
  86     run_utf8_validation(v)?;
  87     // SAFETY: Just ran validation.
  88     Ok(unsafe { from_utf8_unchecked(v) })
  89 }
  90
  91 /// Converts a mutable slice of bytes to a mutable string slice.
  92 ///
  93 /// # Examples
  94 ///
  95 /// Basic usage:
  96 ///
  97 /// ```
  98 /// use std::str;
  99 ///
 100 /// // "Hello, Rust!" as a mutable vector
 101 /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
 102 ///
 103 /// // As we know these bytes are valid, we can use `unwrap()`
 104 /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
 105 ///
 106 /// assert_eq!("Hello, Rust!", outstr);
 107 /// ```
 108 ///
 109 /// Incorrect bytes:
 110 ///
 111 /// ```
 112 /// use std::str;
 113 ///
 114 /// // Some invalid bytes in a mutable vector
 115 /// let mut invalid = vec![128, 223];
 116 ///
 117 /// assert!(str::from_utf8_mut(&mut invalid).is_err());
 118 /// ```
 119 /// See the docs for [`Utf8Error`] for more details on the kinds of
 120 /// errors that can be returned.
 121 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 122 pub fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> {
 123     run_utf8_validation(v)?;
 124     // SAFETY: Just ran validation.
 125     Ok(unsafe { from_utf8_unchecked_mut(v) })
 126 }
 127
 128 /// Converts a slice of bytes to a string slice without checking
 129 /// that the string contains valid UTF-8.
 130 ///
 131 /// See the safe version, [`from_utf8`], for more information.
 132 ///
 133 /// # Safety
 134 ///
 135 /// This function is unsafe because it does not check that the bytes passed to
 136 /// it are valid UTF-8. If this constraint is violated, undefined behavior
 137 /// results, as the rest of Rust assumes that [`&str`]s are valid UTF-8.
 138 ///
 139 /// [`&str`]: str
 140 ///
 141 /// # Examples
 142 ///
 143 /// Basic usage:
 144 ///
 145 /// ```
 146 /// use std::str;
 147 ///
 148 /// // some bytes, in a vector
 149 /// let sparkle_heart = vec![240, 159, 146, 150];
 150 ///
 151 /// let sparkle_heart = unsafe {
 152 ///     str::from_utf8_unchecked(&sparkle_heart)
 153 /// };
 154 ///
 155 /// assert_eq!("💖", sparkle_heart);
 156 /// ```
 157 #[inline]
 158 #[stable(feature = "rust1", since = "1.0.0")]
 159 #[rustc_const_unstable(feature = "const_str_from_utf8_unchecked", issue = "75196")]
 160 #[rustc_allow_const_fn_unstable(const_fn_transmute)]
 161 pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
 162     // SAFETY: the caller must guarantee that the bytes `v` are valid UTF-8.
 163     // Also relies on `&str` and `&[u8]` having the same layout.
 164     unsafe { mem::transmute(v) }
 165 }
 166
 167 /// Converts a slice of bytes to a string slice without checking
 168 /// that the string contains valid UTF-8; mutable version.
 169 ///
 170 /// See the immutable version, [`from_utf8_unchecked()`] for more information.
 171 ///
 172 /// # Examples
 173 ///
 174 /// Basic usage:
 175 ///
 176 /// ```
 177 /// use std::str;
 178 ///
 179 /// let mut heart = vec![240, 159, 146, 150];
 180 /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
 181 ///
 182 /// assert_eq!("💖", heart);
 183 /// ```
 184 #[inline]
 185 #[stable(feature = "str_mut_extras", since = "1.20.0")]
 186 pub unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
 187     // SAFETY: the caller must guarantee that the bytes `v`
 188     // are valid UTF-8, thus the cast to `*mut str` is safe.
 189     // Also, the pointer dereference is safe because that pointer
 190     // comes from a reference which is guaranteed to be valid for writes.
 191     unsafe { &mut *(v as *mut [u8] as *mut str) }
 192 }