alloc::str::from_utf8 - Rust
Description: API documentation for the Rust `from_utf8` fn in crate `alloc`.
Keywords: rust, rustlang, rust-lang, from_utf8

# 1.0.0[−][src]Function alloc::str::from_utf8

    pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error>

Converts a slice of bytes to a string slice.

A string slice (`&str`) is made of bytes (`u8`), and a byte slice (`&[u8]`) is made of bytes, so this function converts between the two. Not all byte slices are valid string slices, however: `&str` requires that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid UTF-8, and then does the conversion.

If you are sure that the byte slice is valid UTF-8, and you don't want to incur the overhead of the validity check, there is an unsafe version of this function, `from_utf8_unchecked`, which has the same behavior but skips the check.

If you need a `String` instead of a `&str`, consider `String::from_utf8`.

Because you can stack-allocate a `[u8; N]`, and you can take a `&[u8]` of it, this function is one way to have a stack-allocated string. There is an example of this in the examples section below.

# Errors

Returns `Err` if the slice is not UTF-8 with a description as to why the provided slice is not UTF-8.

# Examples

Basic usage:

    use std::str;

    // some bytes, in a vector
    let sparkle_heart = vec![240, 159, 146, 150];

    // We know these bytes are valid, so just use `unwrap()`.
    let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();

    assert_eq!("💖", sparkle_heart);

Incorrect bytes:

    use std::str;

    // some invalid bytes, in a vector
    let sparkle_heart = vec![0, 159, 146, 150];

    assert!(str::from_utf8(&sparkle_heart).is_err());

See the docs for `Utf8Error` for more details on the kinds of errors that can be returned.

A "stack allocated string":

    use std::str;

    // some bytes, in a stack-allocated array
    let sparkle_heart = [240, 159, 146, 150];

    // We know these bytes are valid, so just use `unwrap()`.
    let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();

    assert_eq!("💖", sparkle_heart);

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)