Struct Utf8Decoder 

pub struct Utf8Decoder { /* private fields */ }

push based UTF-8 decoder that tracks byte positions

Examples

decode a valid character

let mut decoder = Utf8Decoder::new(0);
assert_eq!(decoder.push(0xF0), None); // accumulating
assert_eq!(decoder.push(0x9F), None);
assert_eq!(decoder.push(0xA6), None);
assert_eq!(decoder.push(0x80), Some(Ok((0, '🦀')))); // complete
decoder.finish()?; // check for truncated sequence

keeps going after an error. offending bytes are thrown in the garbage can

let mut decoder = Utf8Decoder::new(0);
assert_eq!(decoder.push(b'a'), Some(Ok((0, 'a'))));
assert_eq!(decoder.push(0xC3), None);
assert_eq!(
    decoder.push(0xC3),
    Some(Err(Error {
        range: 1..3,
        kind: ErrorKind::ExpectedContinuation(0xC3),
    }))
);
assert_eq!(decoder.push(b'b'), Some(Ok((3, 'b'))));

Implementations

impl Utf8Decoder

pub fn new(offset: usize) -> Self

create a decoder starting at byte offset offset

pub fn push(&mut self, b: u8) -> Option<Result<(usize, char)>>

process a single byte

Examples

let mut decoder = Utf8Decoder::default();

assert_eq!(decoder.push(0xC3), None); // accumulating
assert_eq!(decoder.push(0xA9), Some(Ok((0, 'é')))); // complete

// error
let expected = Some(Err(Error {
    range: 2..3,
    kind: ErrorKind::InvalidLead(0x80),
}));
assert_eq!(decoder.push(0x80), expected);

// after error, decoder is reset to idle and continues
assert_eq!(decoder.push(b'b'), Some(Ok((3, 'b'))));
assert_eq!(decoder.finish(), Ok(4)); // no truncated sequence

pub fn finish(self) -> Result<usize>

flush the decoder when there are no more bytes left

on success, returns the total number of bytes consumed

Errors

Returns an error of kind ErrorKind::UnfinishedSequence when current byte sequence is truncated

Examples

// idle decoder is all good
assert_eq!(Utf8Decoder::new(0).finish(), Ok(0));

// incomplete sequence returns `UnfinishedSequence`
let mut decoder = Utf8Decoder::new(0);
assert_eq!(decoder.push(0xC3), None);
assert_eq!(
    decoder.finish().unwrap_err().kind,
    ErrorKind::UnfinishedSequence
);

Trait Implementations

impl Clone for Utf8Decoder

fn clone(&self) -> Utf8Decoder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Utf8Decoder

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

Formats the value using the given formatter.

impl Default for Utf8Decoder

fn default() -> Utf8Decoder

Returns the “default value” for a type.

impl PartialEq for Utf8Decoder

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Utf8Decoder

impl StructuralPartialEq for Utf8Decoder