glassy 0.0.3

An easy and fast library for encoding and decoding binary data.
Documentation 
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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

//! Quickly encode or decode binary data.
//!
//! [`glassy`](crate) is a library for easily and efficiently encoding and
//! decoding binary data to and from textual representations like Base32 and
//! Base64.  It was created for use in implementing the GNU coreutil `basenc`.

#![no_std]

use core::mem::MaybeUninit;

pub mod base32;
pub mod base64;

pub mod util;

/// The ability to encode binary data.
///
/// This trait is implemented on state machines which can be used to encode
/// binary data into a certain format (e.g. Base32 or Base64).
pub trait Encode {
    /// An error that occurs during encoding.
    type Error;

    /// The output buffer size to use for [`Encode::encode()`].
    ///
    /// When an input of the given length is passed to [`Encode::encode()`], an
    /// output buffer of the returned size must be provided to fill into.
    fn encode_buffer_size(&self, decoded_size: usize) -> usize;

    /// Encode the given data.
    ///
    /// The given input will be processed and some output bytes will be
    /// generated; these are written to the provided destination buffer.  This
    /// buffer must be at least as large as [`Encode::encode_buffer_size()`] for
    /// the provided input buffer size.
    fn encode(
        &mut self,
        decoded: &[u8],
        encoded: &mut [MaybeUninit<u8>],
    ) -> Result<usize, Self::Error>;

    /// The output buffer size to use for [`Encode::encode_end()`].
    ///
    /// When [`Encode::encode_end()`] is called, an output buffer of the
    /// returned size must be provided to fill into.
    fn encode_end_buffer_size(&self) -> usize;

    /// Encode the end of the input.
    ///
    /// If any state in the encoder remains to be output as encoded bytes, it
    /// will be performed here.  The given destination buffer must be at least
    /// as large as [`Encode::encode_end_buffer_size()`].  The encoder should
    /// not be used again.
    fn encode_end(
        &mut self,
        encoded: &mut [MaybeUninit<u8>],
    ) -> Result<usize, Self::Error>;
}

/// The ability to decode data.
///
/// This trait is implemented on state machines which can be used to decode
/// binary data from a certain format (e.g. Base32 or Base64).
pub trait Decode {
    /// An error that occurs during decoding.
    type Error;

    /// The output buffer size to use for [`Decode::decode()`].
    ///
    /// When an input of the given length is passed to [`Decode::decode()`], an
    /// output buffer of the returned size must be provided to fill into.
    fn decode_buffer_size(&self, encoded_size: usize) -> usize;

    /// Decode the given data.
    ///
    /// The given input will be processed and some output bytes will be
    /// generated; these are written to the provided destination buffer.  This
    /// buffer must be at least as large as [`Decode::decode_buffer_size()`] for
    /// the provided input buffer size.
    fn decode(
        &mut self,
        encoded: &[u8],
        decoded: &mut [MaybeUninit<u8>],
    ) -> Result<usize, Self::Error>;

    /// The output buffer size to use for [`Decode::decode_end()`].
    ///
    /// When [`Decode::decode_end()`] is called, an output buffer of the
    /// returned size must be provided to fill into.
    fn decode_end_buffer_size(&self) -> usize;

    /// Encode the end of the input.
    ///
    /// If any state in the decoder remains to be output as decoded bytes, it
    /// will be performed here.  The given destination buffer must be at least
    /// as large as [`Decode::decode_end_buffer_size()`].  The decoder should
    /// not be used again.
    fn decode_end(
        &mut self,
        decoded: &mut [MaybeUninit<u8>],
    ) -> Result<usize, Self::Error>;
}