Struct bstr::Utf8Error

pub struct Utf8Error { /* fields omitted */ }

An error that occurs when UTF-8 decoding fails.

This error occurs when attempting to convert a non-UTF-8 byte string to a Rust string that must be valid UTF-8. For example, to_str is one such method.

Example

This example shows what happens when a given byte sequence is invalid, but ends with a sequence that is a possible prefix of valid UTF-8.

use bstr::{B, ByteSlice};

let s = B(b"foobar\xF1\x80\x80");
let err = s.to_str().unwrap_err();
assert_eq!(err.valid_up_to(), 6);
assert_eq!(err.error_len(), None);

This example shows what happens when a given byte sequence contains invalid UTF-8.

use bstr::ByteSlice;

let s = b"foobar\xF1\x80\x80quux";
let err = s.to_str().unwrap_err();
assert_eq!(err.valid_up_to(), 6);
// The error length reports the maximum number of bytes that correspond to
// a valid prefix of a UTF-8 encoded codepoint.
assert_eq!(err.error_len(), Some(3));

// In contrast to the above which contains a single invalid prefix,
// consider the case of multiple individal bytes that are never valid
// prefixes. Note how the value of error_len changes!
let s = b"foobar\xFF\xFFquux";
let err = s.to_str().unwrap_err();
assert_eq!(err.valid_up_to(), 6);
assert_eq!(err.error_len(), Some(1));

// The fact that it's an invalid prefix does not change error_len even
// when it immediately precedes the end of the string.
let s = b"foobar\xFF";
let err = s.to_str().unwrap_err();
assert_eq!(err.valid_up_to(), 6);
assert_eq!(err.error_len(), Some(1));

Methods

impl Utf8Error

pub fn valid_up_to(&self) -> usize

Returns the byte index of the position immediately following the last valid UTF-8 byte.

Example

This examples shows how valid_up_to can be used to retrieve a possibly empty prefix that is guaranteed to be valid UTF-8:

use bstr::ByteSlice;

let s = b"foobar\xF1\x80\x80quux";
let err = s.to_str().unwrap_err();

// This is guaranteed to never panic.
let string = s[..err.valid_up_to()].to_str().unwrap();
assert_eq!(string, "foobar");

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

Returns the total number of invalid UTF-8 bytes immediately following the position returned by valid_up_to. This value is always at least 1, but can be up to 3 if bytes form a valid prefix of some UTF-8 encoded codepoint.

If the end of the original input was found before a valid UTF-8 encoded codepoint could be completed, then this returns None. This is useful when processing streams, where a None value signals that more input might be needed.

Trait Implementations

impl Eq for Utf8Error

impl PartialEq<Utf8Error> for Utf8Error

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

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

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

This method tests for !=.

impl Display for Utf8Error

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for Utf8Error

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Error for Utf8Error

fn description(&self) -> &str

This method is soft-deprecated.

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

Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

The lower-level cause of this error, if any.

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

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