@@ -160,6 +160,182 @@ impl str {
160160 self . len ( ) == 0
161161 }
162162
163+ /// Converts a slice of bytes to a string slice.
164+ ///
165+ /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
166+ /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
167+ /// the two. Not all byte slices are valid string slices, however: [`&str`] requires
168+ /// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid
169+ /// UTF-8, and then does the conversion.
170+ ///
171+ /// [`&str`]: str
172+ /// [byteslice]: prim@slice
173+ ///
174+ /// If you are sure that the byte slice is valid UTF-8, and you don't want to
175+ /// incur the overhead of the validity check, there is an unsafe version of
176+ /// this function, [`from_utf8_unchecked`], which has the same
177+ /// behavior but skips the check.
178+ ///
179+ /// If you need a `String` instead of a `&str`, consider
180+ /// [`String::from_utf8`][string].
181+ ///
182+ /// [string]: ../std/string/struct.String.html#method.from_utf8
183+ ///
184+ /// Because you can stack-allocate a `[u8; N]`, and you can take a
185+ /// [`&[u8]`][byteslice] of it, this function is one way to have a
186+ /// stack-allocated string. There is an example of this in the
187+ /// examples section below.
188+ ///
189+ /// [byteslice]: slice
190+ ///
191+ /// # Errors
192+ ///
193+ /// Returns `Err` if the slice is not UTF-8 with a description as to why the
194+ /// provided slice is not UTF-8.
195+ ///
196+ /// # Examples
197+ ///
198+ /// Basic usage:
199+ ///
200+ /// ```
201+ /// use std::str;
202+ ///
203+ /// // some bytes, in a vector
204+ /// let sparkle_heart = vec![240, 159, 146, 150];
205+ ///
206+ /// // We can use the ? (try) operator to check if the bytes are valid
207+ /// let sparkle_heart = str::from_utf8(&sparkle_heart)?;
208+ ///
209+ /// assert_eq!("💖", sparkle_heart);
210+ /// # Ok::<_, str::Utf8Error>(())
211+ /// ```
212+ ///
213+ /// Incorrect bytes:
214+ ///
215+ /// ```
216+ /// use std::str;
217+ ///
218+ /// // some invalid bytes, in a vector
219+ /// let sparkle_heart = vec![0, 159, 146, 150];
220+ ///
221+ /// assert!(str::from_utf8(&sparkle_heart).is_err());
222+ /// ```
223+ ///
224+ /// See the docs for [`Utf8Error`] for more details on the kinds of
225+ /// errors that can be returned.
226+ ///
227+ /// A "stack allocated string":
228+ ///
229+ /// ```
230+ /// use std::str;
231+ ///
232+ /// // some bytes, in a stack-allocated array
233+ /// let sparkle_heart = [240, 159, 146, 150];
234+ ///
235+ /// // We know these bytes are valid, so just use `unwrap()`.
236+ /// let sparkle_heart: &str = str::from_utf8(&sparkle_heart).unwrap();
237+ ///
238+ /// assert_eq!("💖", sparkle_heart);
239+ /// ```
240+ #[ unstable( feature = "inherent_str_constructors" , issue = "131114" ) ]
241+ pub const fn from_utf8 ( v : & [ u8 ] ) -> Result < & str , Utf8Error > {
242+ converts:: from_utf8 ( v)
243+ }
244+
245+ /// Converts a mutable slice of bytes to a mutable string slice.
246+ ///
247+ /// # Examples
248+ ///
249+ /// Basic usage:
250+ ///
251+ /// ```
252+ /// use std::str;
253+ ///
254+ /// // "Hello, Rust!" as a mutable vector
255+ /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
256+ ///
257+ /// // As we know these bytes are valid, we can use `unwrap()`
258+ /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
259+ ///
260+ /// assert_eq!("Hello, Rust!", outstr);
261+ /// ```
262+ ///
263+ /// Incorrect bytes:
264+ ///
265+ /// ```
266+ /// use std::str;
267+ ///
268+ /// // Some invalid bytes in a mutable vector
269+ /// let mut invalid = vec![128, 223];
270+ ///
271+ /// assert!(str::from_utf8_mut(&mut invalid).is_err());
272+ /// ```
273+ /// See the docs for [`Utf8Error`] for more details on the kinds of
274+ /// errors that can be returned.
275+ #[ unstable( feature = "inherent_str_constructors" , issue = "131114" ) ]
276+ #[ rustc_const_unstable( feature = "const_str_from_utf8" , issue = "91006" ) ]
277+ pub const fn from_utf8_mut ( v : & mut [ u8 ] ) -> Result < & mut str , Utf8Error > {
278+ converts:: from_utf8_mut ( v)
279+ }
280+
281+ /// Converts a slice of bytes to a string slice without checking
282+ /// that the string contains valid UTF-8.
283+ ///
284+ /// See the safe version, [`from_utf8`], for more information.
285+ ///
286+ /// # Safety
287+ ///
288+ /// The bytes passed in must be valid UTF-8.
289+ ///
290+ /// # Examples
291+ ///
292+ /// Basic usage:
293+ ///
294+ /// ```
295+ /// use std::str;
296+ ///
297+ /// // some bytes, in a vector
298+ /// let sparkle_heart = vec![240, 159, 146, 150];
299+ ///
300+ /// let sparkle_heart = unsafe {
301+ /// str::from_utf8_unchecked(&sparkle_heart)
302+ /// };
303+ ///
304+ /// assert_eq!("💖", sparkle_heart);
305+ /// ```
306+ #[ inline]
307+ #[ must_use]
308+ #[ unstable( feature = "inherent_str_constructors" , issue = "131114" ) ]
309+ pub const unsafe fn from_utf8_unchecked ( v : & [ u8 ] ) -> & str {
310+ // SAFETY: converts::from_utf8_unchecked has the same safety requirements as this function.
311+ unsafe { converts:: from_utf8_unchecked ( v) }
312+ }
313+
314+ /// Converts a slice of bytes to a string slice without checking
315+ /// that the string contains valid UTF-8; mutable version.
316+ ///
317+ /// See the immutable version, [`from_utf8_unchecked()`] for more information.
318+ ///
319+ /// # Examples
320+ ///
321+ /// Basic usage:
322+ ///
323+ /// ```
324+ /// use std::str;
325+ ///
326+ /// let mut heart = vec![240, 159, 146, 150];
327+ /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
328+ ///
329+ /// assert_eq!("💖", heart);
330+ /// ```
331+ #[ inline]
332+ #[ must_use]
333+ #[ unstable( feature = "inherent_str_constructors" , issue = "131114" ) ]
334+ pub const unsafe fn from_utf8_unchecked_mut ( v : & mut [ u8 ] ) -> & mut str {
335+ // SAFETY: converts::from_utf8_unchecked_mut has the same safety requirements as this function.
336+ unsafe { converts:: from_utf8_unchecked_mut ( v) }
337+ }
338+
163339 /// Checks that `index`-th byte is the first byte in a UTF-8 code point
164340/// sequence or the end of the string.
165341///
0 commit comments