Struct rut::Decoder

pub struct Decoder { /* fields omitted */ }

A bytewise UTF-8 decoder.

Methods

impl Decoder

pub fn new() -> Decoder

Creates a new decoder.

pub fn decode_byte(&mut self, byte: u8) -> DecoderResult

Decodes a single byte.

Correct Use

Due to the nature of bytewise UTF-8 decoding, blindly continuing through errors will lead to vastly incorrect results.

For example, the byte sequence C2, 41, 42 would return the results <Continue>, <Error>, B.
However, Unicode expects this sequence to be treated as <Error>, A, B.

This means that, when an error is encountered inside of a sequence, the offending byte should be passsed to decode_byte again.
This is because an ill-formed sequence ends at the last valid byte, not at the first invalid byte.

This is essentially what the decode_one function does.

Example

Performing lossy decoding with Decoder:

use std::fmt::Write;
use rut::{Decoder, DecoderResult, Error::*};

let mut s = String::new();
let mut d = Decoder::new();

// An ill-formed UTF-8 sequence as described above.
let bytes = [0xC2, 0x41, 0x42];

for &byte in &bytes {
    let mut result = d.decode_byte(byte);

    if let DecoderResult::Error(e) = result {
        match e {
            BrokenSequence
            | OverlongEncoding
            | InvalidCodePoint => {
                write!(&mut s, "\u{FFFD}").unwrap();
                result = d.decode_byte(byte);
            },
            _ => {}
        }
    }

    match result {
        DecoderResult::Continue => continue,
        DecoderResult::Char(c)  => write!(&mut s, "{}", c).unwrap(),
        DecoderResult::Error(_) => write!(&mut s, "\u{FFFD}").unwrap()
    }
}

assert_eq!(&s, "�AB");

Trait Implementations

impl Clone for Decoder

fn clone(&self) -> Decoder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for Decoder

impl Debug for Decoder

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

Formats the value using the given formatter.

impl Default for Decoder

fn default() -> Decoder

Returns the "default value" for a type.