abin 0.1.6

A library for working with binaries and strings. The library tries to avoid heap-allocations / memory-copy whenever possible by automatically choosing a reasonable strategy: stack for small binaries; static-lifetime-binary or reference-counting.
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

use crate::{SBin, StackBin};

const MAX_LEN: usize = StackBin::max_len();

/// Unfortunately `SmallVec` does not implement the size for 23.
pub struct StackBinBuilder {
    vec_excess_capacity: usize,
    inner: Inner,
}

enum Inner {
    Vec(Vec<u8>),
    Stack { len: usize, array: [u8; MAX_LEN] },
}

impl StackBinBuilder {
    #[inline]
    pub fn new(vec_excess_capacity: usize) -> Self {
        Self {
            vec_excess_capacity,
            inner: Inner::Stack {
                len: 0,
                array: [0; MAX_LEN],
            },
        }
    }

    #[inline]
    pub fn extend_from_slice(&mut self, other: &[u8]) {
        match &mut self.inner {
            Inner::Vec(vec) => vec.extend_from_slice(other),
            Inner::Stack { len, array } => {
                let other_len = other.len();
                let resulting_len = len.checked_add(other_len).unwrap();
                if resulting_len > MAX_LEN {
                    // we need to use a vec
                    let mut vec = Vec::with_capacity(resulting_len + self.vec_excess_capacity);
                    vec.extend_from_slice(&array[0..*len]);
                    vec.extend_from_slice(other);
                    self.inner = Inner::Vec(vec);
                } else {
                    // ok, still enough for the stack
                    let start_index = *len;
                    let end_index = start_index + other.len();
                    (&mut array[start_index..end_index]).copy_from_slice(other);
                    *len = resulting_len;
                }
            }
        }
    }

    /// Tries to extend from slice. Returns `true` if there's still enough space to fit onto the
    /// stack. Returns `false` if item has not been added, because it does not fit onto the stack.
    pub fn try_extend_from_slice(&mut self, other: &[u8]) -> bool {
        match &mut self.inner {
            Inner::Vec(_vec) => false,
            Inner::Stack { len, array } => {
                let other_len = other.len();
                let resulting_len = len.checked_add(other_len).unwrap();
                if resulting_len > MAX_LEN {
                    false
                } else {
                    // ok, still enough for the stack
                    let start_index = *len;
                    let end_index = start_index + other.len();
                    (&mut array[start_index..end_index]).copy_from_slice(other);
                    *len = resulting_len;
                    true
                }
            }
        }
    }

    /// only builds a binary if this fits onto the stack. Returns `None` otherwise.
    pub fn build_stack_only(&self) -> Option<SBin> {
        match &self.inner {
            Inner::Vec(_vec) => None,
            Inner::Stack { len, array } => Some(
                StackBin::try_from(&array[0..*len])
                    .expect("This MUST be small enough for the stack."),
            ),
        }
    }

    pub fn build(self) -> Result<SBin, Vec<u8>> {
        match self.inner {
            Inner::Vec(vec) => {
                // too large
                Err(vec)
            }
            Inner::Stack { len, array } => Ok(StackBin::try_from(&array[0..len])
                .expect("This MUST be small enough for the stack.")),
        }
    }
}