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

use core::{ops::Deref, str::Utf8Error};

/// A possible error value when converting a string from a UTF-8 byte vector.
///
/// This type is the error type for the [`BumpString::from_utf8`](crate::BumpString::from_utf8), [`MutBumpString::from_utf8`](crate::MutBumpString::from_utf8) and [`BumpBox<[u8]>::into_boxed_str`](crate::BumpBox::into_boxed_str). It
/// is designed in such a way to carefully avoid reallocations: the
/// [`into_bytes`](FromUtf8Error::into_bytes) method will give back the byte vector that was used in the
/// conversion attempt.
///
/// The [`Utf8Error`] type provided by [`std::str`] represents an error that may
/// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's
/// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error`
/// through the [`utf8_error`] method.
///
/// [`Utf8Error`]: core::str::Utf8Error
/// [`std::str`]: core::str "std::str"
/// [`&str`]: prim@str "&str"
/// [`utf8_error`]: FromUtf8Error::utf8_error
#[derive(Debug)]
pub struct FromUtf8Error<Bytes> {
    pub(crate) bytes: Bytes,
    pub(crate) error: Utf8Error,
}

impl<Bytes> FromUtf8Error<Bytes> {
    /// Returns a slice of [`u8`]s bytes that were attempted to convert to a `String`.
    #[must_use]
    #[inline(always)]
    pub fn as_bytes(&self) -> &[u8]
    where
        Bytes: Deref<Target = [u8]>,
    {
        &self.bytes
    }

    /// Returns the bytes that were attempted to convert to a `String`.
    #[must_use = "`self` will be dropped if the result is not used"]
    #[inline(always)]
    pub fn into_bytes(self) -> Bytes {
        self.bytes
    }

    /// Fetch a `Utf8Error` to get more details about the conversion failure.
    ///
    /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may
    /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's
    /// an analogue to `FromUtf8Error`. See its documentation for more details
    /// on using it.
    ///
    /// [`std::str`]: core::str "std::str"
    /// [`&str`]: prim@str "&str"
    #[inline(always)]
    pub fn utf8_error(&self) -> Utf8Error {
        self.error
    }
}