barrique 1.0.0

Portable binary serialiation format
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
103
104
105
106
107
108
109
110
111
112
113
114

//! Standard implementation of `barrique` binary serialization format
//!
//! `barrique` is a serialization format designed for local out-of-memory
//! caches, featuring metadata, compression and streaming. Data stored in
//! the core primitive — region. Regions are LZ4 compressed blocks
//! of encoded bytes additionally storing small metadata header.
//!
//! # Example
//!
//! Most likely you'll start with implementations generated by derive macro:
//!
//! ```
//! use barrique::{Encode, Decode};
//! use barrique::frame::Frame;
//! use barrique::region::Seed;
//!
//! #[derive(Encode, Decode, Clone, PartialEq)]
//! struct Bee {
//!     name: String,
//!     state: State
//!     #[barrique(skip)]
//!     age: u8,
//! }
//!
//! #[derive(Encode, Decode, Clone, PartialEq)]
//! #[barrique(tag_repr = "u8")]
//! enum State {
//!     Collecting(i32, i32),
//!     Buzzing {
//!         sound_level: u8
//!     },
//!     Sleeping
//! }
//!
//! let bee = Bee {
//!     name: "Oh, hey!",
//!     state: State::Sleeping,
//!     age: 2
//! };
//! let mut dst = vec![];
//!
//! let frame = Frame::new(&mut dst, Seed::new(0))
//!     .with_label("A beehive");
//! frame.encode(bee.clone());
//!
//! let frame = Frame::decode(&dst, Seed::new(0))
//!     .expect("Failed to open a frame");
//! assert_eq!(frame.get_value().unwrap(), bee);
//! ```
//!
//! `Frame` is specification-defined format wrapping a stream primitive. Streams
//! available as `StreamEncoder` and `StreamDecoder`.
//!
//! # Streaming
//!
//! `barrique` format was designed to keep buffer memory usage constant, which is
//! 128 KiB (`AllocOrd` allows to specify it if a value to encode is less
//! than 128 KiB). The buffer size limit is exact length of two raw regions,
//! previous region is stored to improve LZ4 compression ratio, which
//! maximum window size is 64 KiB.
//!
//! The crate provides a wrapper for `std::io::Write` and `std::io::Read` traits
//! called `CursorView` in order to utilize streaming, making memory usage up to 192 KiB
//! where 128 KiB allocated by the stream primitive and additional 64 KiB is the maximum
//! size of dynamic buffer of a `CursorView` (although it can be more than 64 KiB, stream
//! primitive requests up to 64 KiB per request).
//!
//! An example of `CursorView` application:
//!
//! ```
//! use barrique::cursor::CursorView;
//! use barrique::encode::StreamEncoder;
//! use barrique::region::{AllocOrd, Seed};
//! use std::fs::File;
//!
//! let file = File::create("serialized.bin").unwrap();
//! let mut dst = CursorView::new(file);
//!
//! let mut encoder = StreamEncoder::new(&mut dst, Seed::new(0), AllocOrd::Full);
//! <str as Encode>::encode(&mut encoder, "Hello, world!").unwrap();
//!
//! encoder.flush();
//! dst.flush();
//! ```
//!
//! # `no_std` support
//!
//! Available via `no_std` feature, however, `alloc` crate is required

#![cfg_attr(not(feature = "std"), no_std)]

// Underlying C implementation of LZ4 depends on allocation unless specific preprocessor
// definition is stated, which is impossible with current bindings. Either way pushing
// 128 KiB size RegionBuffer to the stack is a little bit unsuitable
extern crate alloc;
extern crate core;

#[cfg(feature = "derive")]
pub use barrique_derive::{Encode, Decode};
pub(crate) use barrique_derive::tuple_drop_guard;

pub mod cursor;
pub mod decode;
pub mod encode;
pub mod frame;
pub mod r#impl;
pub mod region;

mod lz4;

mod tests {
    #[test]
    fn it_works() {}
}