Struct std::str::Utf8Error

1.0.0 · source ·
pub struct Utf8Error { /* private fields */ }
Expand description

Errors which can occur when attempting to interpret a sequence of u8 as a string.

As such, the from_utf8 family of functions and methods for both Strings and &strs make use of this error, for example.

§Examples

This error type’s methods can be used to create functionality similar to String::from_utf8_lossy without allocating heap memory:

fn from_utf8_lossy<F>(mut input: &[u8], mut push: F) where F: FnMut(&str) {
    loop {
        match std::str::from_utf8(input) {
            Ok(valid) => {
                push(valid);
                break
            }
            Err(error) => {
                let (valid, after_valid) = input.split_at(error.valid_up_to());
                unsafe {
                    push(std::str::from_utf8_unchecked(valid))
                }
                push("\u{FFFD}");

                if let Some(invalid_sequence_length) = error.error_len() {
                    input = &after_valid[invalid_sequence_length..]
                } else {
                    break
                }
            }
        }
    }
}
Run

Implementations§

source§

impl Utf8Error

1.5.0 (const: 1.63.0) · source

pub const fn valid_up_to(&self) -> usize

Returns the index in the given string up to which valid UTF-8 was verified.

It is the maximum index such that from_utf8(&input[..index]) would return Ok(_).

§Examples

Basic usage:

use std::str;

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

// std::str::from_utf8 returns a Utf8Error
let error = str::from_utf8(&sparkle_heart).unwrap_err();

// the second byte is invalid here
assert_eq!(1, error.valid_up_to());
Run
1.20.0 (const: 1.63.0) · source

pub const fn error_len(&self) -> Option<usize>

Provides more information about the failure:

  • None: the end of the input was reached unexpectedly. self.valid_up_to() is 1 to 3 bytes from the end of the input. If a byte stream (such as a file or a network socket) is being decoded incrementally, this could be a valid char whose UTF-8 byte sequence is spanning multiple chunks.

  • Some(len): an unexpected byte was encountered. The length provided is that of the invalid byte sequence that starts at the index given by valid_up_to(). Decoding should resume after that sequence (after inserting a U+FFFD REPLACEMENT CHARACTER) in case of lossy decoding.

Trait Implementations§

source§

impl Clone for Utf8Error

source§

fn clone(&self) -> Utf8Error

Returns a copy of the value. Read more
source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Utf8Error

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
source§

impl Display for Utf8Error

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
source§

impl Error for Utf8Error

source§

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()
1.30.0 · source§

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any. Read more
source§

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting
source§

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access #99301)
Provides type based access to context intended for error reports. Read more
source§

impl PartialEq for Utf8Error

source§

fn eq(&self, other: &Utf8Error) -> bool

This method tests for self and other values to be equal, and is used by ==.
source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Copy for Utf8Error

source§

impl Eq for Utf8Error

source§

impl StructuralPartialEq for Utf8Error

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.