tycho/partial/
mod.rs

1//! Partial unmarshall and traversal. (requires `partial` feature)
2//!
3//!
4//! ## Appliactions
5//! Parital reading **is** for:
6//! - Reading large tycho encoded files.
7//!
8//! Parital reading **is not** for:
9//! - Reading from streams/sockets.
10//!
11//! Tycho Parital reading is designed for reading from large files where proccessing is limited
12//! such as in a database or data store, where the contents do not need to be serialized.
13//!
14//! ## Quick Example
15//! ```
16//! use tycho::partial::{PartialReader, PartialElement};
17//!
18//! // Create a partial reader from a vec with example bytes.
19//! let mut reader = PartialReader::from_vec(vec![
20//!     /* ... */
21//! # 5, 35, 102, 111, 111, 0, 1, 4, 1, 10, 98, 97, 114, 0, 1, 4, 2, 0, 20, 98, 97, 122, 0, 1, 2, 11, 72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100
22//! ]);
23//!
24//! // Get the root element from
25//! let root = reader.element().unwrap();
26//!
27//! // check if the root element is a structure
28//! if let PartialElement::Struct(mut s) = root {
29//!
30//!     // iterate over fields with reader.
31//!     for (key, value) in s.iter(&mut reader) {
32//!         println!("{:?}: {:?}", key, value);
33//!     }
34//! }
35//!
36//! ```
37//!
38//! ## Getting Started
39//!
40//! ### Reader
41//! Parital reading requires a `ParitalReader` to be created.
42//! The partial reader has an internal pointer and handles state management.
43//!
44//! A `ParitalReader` can wrap any type that implements `Read` and `Seek`
45//! and thier respective async counterparts.
46//!
47//! `ParitalReader` then implements its own `Read` trait that handles the pointer when read.
48//!
49//! ```
50//! // From a Vec<u8>
51//! use tycho::partial::PartialReader;
52//!
53//! let mut reader = PartialReader::from_vec(Vec::<u8>::new());
54//! ```
55//!
56//! ```
57//! // From a cursor
58//! use std::io::Cursor;
59//! use tycho::partial::PartialReader;
60//!
61//! let cursor = Cursor::new(Vec::<u8>::new());
62//! let mut reader = PartialReader::from(cursor);
63//! ```
64//! ```no_run
65//! // From a file
66//! use std::io::{Cursor, BufReader};
67//! use tycho::partial::PartialReader;
68//! use std::fs::File;
69//!
70//! let file = File::open("path/to/file").unwrap();
71//! let buf = BufReader::new(file);
72//! let mut reader = PartialReader::from(buf);
73//! ```
74//!
75//! ### Pointers
76//! Pointers map to a set of bytes within a reader.
77//! They contain a `position` and `size`,
78//! with position representing the start loaction and size the data length.
79//!
80//! Pointers are given out within a ParitalElement and wrapped within a container type.
81//! While the user may not interact with a pointer directly it may help with understanding how
82//! tycho paritally parses bytes.
83//!
84//! ### Element
85//! ParitalElements contain a proccessed value or a unproccess container with its respective pointer.
86//!
87//! Within this libary there are four types of partial element:
88//! - Proccessed (Unit, Value)
89//! - Pointing (Option, Variant)
90//! - Container (Struct, List, Map, Array)
91//! - Compression (Compression)
92//!
93//! Proccessed values can be accesed by pattern matching the `ParitalElement` enum,
94//! which will return a normaal value.
95//!
96//! Pointing elements return a box with another partial element which can be pattern matched
97//! and handled accordingly.
98//!
99//! Container elements allow you to iterate over thier children one at a time.
100//! See below for more infomation
101//!
102//! Compression elements allow you to get the bytes or another partial element upon request.
103//!
104//! ### Containers
105//! All container types (Struct, List, Map, Array) share a `PartialContainer` which takes a generic.
106//!
107//! The PartialContainer type has another `head` pointer to keep track of the current item.
108//!
109//! **Further documentation soon*
110
111
112#[cfg(feature = "async_tokio")]
113pub use async_::reader::PartialAsyncReader;
114
115pub use element::PartialElement;
116pub use reader::{PartialPointer, PartialReader};
117//pub use types::{PartialArray, PartialList, PartialMap, PartialStruct};
118
119//pub mod types;
120pub mod container;
121pub(crate) mod reader;
122pub(crate) mod element;
123pub mod types;
124
125//pub(crate) mod test;
126
127#[cfg(feature = "async_tokio")]
128pub(crate) mod async_;
129
tycho/partial/mod.rs

tycho/partial/
mod.rs
