tinyklv 0.1.1

The simplest Key-Length-Value (KLV) framework in Rust
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

// --------------------------------------------------
// mods
// --------------------------------------------------
mod breakcond;
mod frame;
mod partial;
mod sentinel;

// --------------------------------------------------
// local
// --------------------------------------------------
pub use crate::prelude::*;
pub use breakcond::*;
pub use frame::*;
pub use partial::*;
pub use sentinel::*;

/// Decodes the value portion of a KLV field from stream-type `S`
///
/// Encode counterpart: [`EncodeValue`](crate::traits::EncodeValue)
///
/// Common examples of stream types include `&[u8]` and `&str`
///
/// Automatically implemented for structs deriving the [`tinyklv::Klv`](crate::Klv) trait which have decoders for every field covered.
///
/// For custom decoding functions, ***no need to use this trait***. Instead, please ensure the functions signature matches the following:
///
/// * fixed length:     `fn <name>(input: &mut S)   -> tinyklv::Result<Self>;`
/// * variable length:  `fn <name>(len: usize)      -> impl Fn(&mut S) -> tinyklv::Result<Self>;`
pub trait DecodeValue<S>: Sized
where
    S: winnow::stream::Stream,
{
    fn decode_value(input: &mut S) -> crate::Result<Self>;
}

/// Automatically implemented for `Vec<T>` where `T` implements [`DecodeValue`].
///
/// Semantics: repeated inner decode until failure. Appropriate for representing
/// a repeated inner field in one parent KLV packet. For streaming a sequence of
/// top-level packets across fragmented reads, use [`crate::Decoder`] instead.
///
/// Cursor safety: if inner `T::decode_value` fails without consuming any bytes,
/// the outer cursor is rewound to the pre-attempt checkpoint so surrounding
/// parsers see the un-eaten bytes. If inner consumed bytes then failed, the
/// progress is committed and the loop stops.
impl<S, T> DecodeValue<S> for Vec<T>
where
    S: winnow::stream::Stream,
    T: DecodeValue<S>,
{
    #[inline(always)]
    fn decode_value(input: &mut S) -> crate::Result<Self> {
        let mut acc = Vec::new();
        loop {
            let before = input.eof_offset();
            let cp = input.checkpoint();
            match T::decode_value(input) {
                Ok(val) => acc.push(val),
                Err(_) => {
                    if input.eof_offset() == before {
                        input.reset(&cp);
                    }
                    break;
                }
            }
        }
        Ok(acc)
    }
}