converts.rs.html -- source
Description: Source to the Rust file `library/core/src/str/converts.rs`.
Keywords: rust, rustlang, rust-lang

      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192

    //! Ways to create a `str` from bytes slice.

    use crate::mem;

    use super::validations::run_utf8_validation;
    use super::Utf8Error;

    /// Converts a slice of bytes to a string slice.
    ///
    /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
    /// ([`&[u8]`][byteslice]) 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.
    ///
    /// [`&str`]: str
    /// [byteslice]: ../../std/primitive.slice.html
    ///
    /// 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`][string].
    ///
    /// [string]: ../../std/string/struct.String.html#method.from_utf8
    ///
    /// Because you can stack-allocate a `[u8; N]`, and you can take a
    /// [`&[u8]`][byteslice] of it, this function is one way to have a
    /// stack-allocated string. There is an example of this in the
    /// examples section below.
    ///
    /// [byteslice]: ../../std/primitive.slice.html
    ///
    /// # 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);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
        run_utf8_validation(v)?;
        // SAFETY: Just ran validation.
        Ok(unsafe { from_utf8_unchecked(v) })
    }

    /// Converts a mutable slice of bytes to a mutable string slice.
    ///
    /// # Examples
    ///
    /// Basic usage:
    ///
    /// ```
    /// use std::str;
    ///
    /// // "Hello, Rust!" as a mutable vector
    /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
    ///
    /// // As we know these bytes are valid, we can use `unwrap()`
    /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
    ///
    /// assert_eq!("Hello, Rust!", outstr);
    /// ```
    ///
    /// Incorrect bytes:
    ///
    /// ```
    /// use std::str;
    ///
    /// // Some invalid bytes in a mutable vector
    /// let mut invalid = vec![128, 223];
    ///
    /// assert!(str::from_utf8_mut(&mut invalid).is_err());
    /// ```
    /// See the docs for [`Utf8Error`] for more details on the kinds of
    /// errors that can be returned.
    #[stable(feature = "str_mut_extras", since = "1.20.0")]
    pub fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> {
        run_utf8_validation(v)?;
        // SAFETY: Just ran validation.
        Ok(unsafe { from_utf8_unchecked_mut(v) })
    }

    /// Converts a slice of bytes to a string slice without checking
    /// that the string contains valid UTF-8.
    ///
    /// See the safe version, [`from_utf8`], for more information.
    ///
    /// # Safety
    ///
    /// This function is unsafe because it does not check that the bytes passed to
    /// it are valid UTF-8. If this constraint is violated, undefined behavior
    /// results, as the rest of Rust assumes that [`&str`]s are valid UTF-8.
    ///
    /// [`&str`]: str
    ///
    /// # Examples
    ///
    /// Basic usage:
    ///
    /// ```
    /// use std::str;
    ///
    /// // some bytes, in a vector
    /// let sparkle_heart = vec![240, 159, 146, 150];
    ///
    /// let sparkle_heart = unsafe {
    ///     str::from_utf8_unchecked(&sparkle_heart)
    /// };
    ///
    /// assert_eq!("💖", sparkle_heart);
    /// ```
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_unstable(feature = "const_str_from_utf8_unchecked", issue = "75196")]
    #[allow_internal_unstable(const_fn_transmute)]
    pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
        // SAFETY: the caller must guarantee that the bytes `v` are valid UTF-8.
        // Also relies on `&str` and `&[u8]` having the same layout.
        unsafe { mem::transmute(v) }
    }

    /// Converts a slice of bytes to a string slice without checking
    /// that the string contains valid UTF-8; mutable version.
    ///
    /// See the immutable version, [`from_utf8_unchecked()`] for more information.
    ///
    /// # 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);
    /// ```
    #[inline]
    #[stable(feature = "str_mut_extras", since = "1.20.0")]
    pub unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
        // SAFETY: the caller must guarantee that the bytes `v`
        // are valid UTF-8, thus the cast to `*mut str` is safe.
        // Also, the pointer dereference is safe because that pointer
        // comes from a reference which is guaranteed to be valid for writes.
        unsafe { &mut *(v as *mut [u8] as *mut str) }
    }