bitstream-rs 0.2.0

Crate for reading and writing single bit values from ordinary Readers and Writers
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

//! A module for `padding` bits into bytes
//!
//! This module contains the trait for defining a padding strategy for `BitReader` and `BitWriter`.

use std::io::{Write};
use std::io::Result as IOResult;

/// **Padding** specifies what sort of padding should be used by
/// [BitReader](../struct.BitReader.html)/[BitWriter](../struct.BitWriter.html)
///
/// This trait can be used to implement custom padding of bits to a whole byte.
pub trait Padding {
    /// Get the maximum size of the padding.
    ///
    /// This is used to determine how many bytes should be passed to
    /// [bits_left](#tymethod.bits_left)
    fn max_size(&self) -> usize;

    /// Pad the last bits of the stream.
    ///
    /// This is called by [BitWriter](../struct.BitWriter.html) on drop to make sure the last bits are
    /// written to the output, using the specified padding. The padding is responsible for writing
    /// the last byte, or else it may lead to unintended loss of data.
    fn pad<W: Write>(&self, last_byte: u8, byte_fill: u8, writer: &mut W) -> IOResult<()>;

    /// Determine how many bits are left to read.
    ///
    /// This is called by [BitReader](../struct.BitReader.html) when encountering the last byte in the
    /// input stream. This will be called with the last `n` bytes of the input stream, where `n`
    /// is [`max_size()`](#tymethod.max_size), or fewer, if there are fewer bytes in the whole input
    /// stream.
    fn bits_left(&self, last_bytes: &[u8]) -> IOResult<usize>;
}

/// **NoPadding** is the default [Padding](trait.Padding.html) used by
/// [BitReader](../struct.BitReader.html)/[BitWriter](../struct.BitWriter.html)
///
/// This does not add any padding to the output stream, apart from filling up the the stream
/// with 0s until the next byte is full.
#[derive(Default, Debug)]
pub struct NoPadding {}

impl NoPadding {
    /// Create a new instance
    pub fn new() -> Self {
        NoPadding {}
    }
}

impl Padding for NoPadding {
    fn max_size(&self) -> usize {
        0
    }

    fn pad<W: Write>(&self, last_byte: u8, byte_fill: u8, writer: &mut W) -> IOResult<()> {
        if byte_fill > 0 {
            writer.write_all(&[last_byte])
        } else {
            Ok(())
        }
    }

    fn bits_left(&self, _: &[u8]) -> IOResult<usize> {
        Ok(0)
    }
}

/// **LengthPadding** can be used encode the number of bits in the bit stream.
///
/// When using this padding, an extra byte is appended at the end of the stream. This byte
/// indicates how many bots in the previous byte are valid.
#[derive(Debug, Default)]
pub struct LengthPadding {}

impl LengthPadding {
    /// Create a new instance
    pub fn new() -> Self {
        LengthPadding {}
    }
}

impl Padding for LengthPadding {
    fn max_size(&self) -> usize {
        2
    }

    fn pad<W: Write>(&self, last_byte: u8, byte_fill: u8, writer: &mut W) -> IOResult<()> {
        if byte_fill > 0 {
            writer.write_all(&[last_byte, byte_fill])
        } else {
            writer.write_all(&[8u8])
        }
    }

    fn bits_left(&self, last_bytes: &[u8]) -> IOResult<usize> {
        if last_bytes.len() == 2 {
            Ok(last_bytes[1] as usize)
        } else {
            Ok(0)
        }
    }
}