diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 95 |
1 files changed, 54 insertions, 41 deletions
@@ -2,92 +2,105 @@ [`bzipper`](https://crates.io/crates/bzipper) is a binary (de)serialiser for the Rust language. -Contrary to [Serde](https://crates.io/crates/serde/)/[Bincode](https://crates.io/crates/bincode/), the goal of this crate is to serialise data with a known size limit. +Contrary to [Serde](https://crates.io/crates/serde/)/[Bincode](https://crates.io/crates/bincode/), the goal of bzipper is to serialise with a known size constraint. Therefore, this crate may be more suited for networking or other cases where a fixed-sized buffer is needed. Keep in mind that this project is still work-in-progress. -This crate does not require any dependencies at the moment. -It is also compatible with `no_std`. +This crate is compatible with `no_std`. -See [Docs.rs](https://docs.rs/bzipper/latest/bzipper/) for documentation. - -## Data Model +## Data model Most primitive types serialise losslessly, with the exception being `usize` and `isize`. -These serialise as `u16` and `i16`, respectively, for portability reasons. +These serialise as `u32` and `i32`, respectively, for portability reasons. Unsized types, such as `str` and slices, are not supported. -Instead, array should be used. +Instead, arrays should be used. For strings, the `FixedString` type is also provided. ## Usage -This crate revolves around the `Serialise` and `Deserialise` traits, both of which work around streams (more specifically, d-streams and s-streams). +This crate revolves around the `Serialise` and `Deserialise` traits, both of which are commonly used in conjunction with streams (more specifically, s-streams and d-streams). + +Many core types come implemented with bzipper, including primitives as well as some standard library types such as `Option` and `Result`. + +It is recommended in most cases to just derive these traits for custom types (enumerations and structures only). +Here, each field is chained in declaration order: + +```rs +use bzipper::{Deserialise, Serialise}; + +#[derive(Debug, Deserialise, PartialEq, Serialise)] +struct IoRegister { + addr: u32, + value: u16, +} + +let mut buf: [u8; IoRegister::SERIALISED_SIZE] = Default::default(); +IoRegister { addr: 0x04000000, value: 0x0402 }.serialise(&mut buf).unwrap(); -Many core types come implemented with `bzipper`, including primitives as well as some standard library types such as `Option` and `Result`. +assert_eq!(buf, [0x04, 0x00, 0x00, 0x00, 0x04, 0x02]); + +assert_eq!(IoRegister::deserialise(&buf).unwrap(), IoRegister { addr: 0x04000000, value: 0x0402 }); +``` ### Serialisation -To serialise an object implementing `Serialise`, simply allocate a so-called "s-stream" (short for *serialisation stream*) with the `Sstream` type: +To serialise an object implementing `Serialise`, simply allocate a buffer for the serialisation. +The required size of any given serialisation is specified by the `SERIALISED_SIZE` constant: ```rs -let mut buf: [u8; 16] = Default::default(); +use bzipper::Serialise; -let mut stream = bzipper::Sstream::new(&mut buf); +let mut buf: [u8; char::SERIALISED_SIZE] = Default::default(); +'Ж'.serialise(&mut buf).unwrap(); + +assert_eq!(buf, [0x00, 0x00, 0x04, 0x16]); ``` -The resulting stream is immutable in the sense that it cannot grow its buffer, altough it does keep track of the buffer's state. +The only special requirement of the `serialise` method is that the provided byte slice has an element count of exactly `SERIALISED_SIZE`. -A byte sequence can be added to our new stream by passing the stream to a call to the `serialise` method: +We can also use streams to *chain* multiple elements together. ```rs use bzipper::Serialise; -let mut buf: [u8; 2] = Default::default(); +let mut buf: [u8; char::SERIALISED_SIZE * 5] = Default::default(); let mut stream = bzipper::Sstream::new(&mut buf); -0x4554_u16.serialise(&mut stream).unwrap(); -``` - -The ammount of bytes used by the serialiser (that is, the ammount of bytes written to the stream) is indicated by its return value (i.e. it has the type `Result<usize, Serialise::Error>`). +stream.append(&'ل'); +stream.append(&'ا'); +stream.append(&'م'); +stream.append(&'د'); +stream.append(&'ا'); -Whilst the *maximum* ammount of bytes is specified by the `SERIALISE_LIMIT` constant, this can in cases be lower (for example with `None` variants which are always encoded as a single, null byte). +assert_eq!(buf, [0x00, 0x00, 0x06, 0x44, 0x00, 0x00, 0x06, 0x27, 0x00, 0x00, 0x06, 0x45, 0x00, 0x00, 0x06, 0x2F, 0x00, 0x00, 0x06, 0x27]); +``` When serialising primitives, the resulting byte stream is in big endian (a.k.a. network endian). It is recommended for implementors to adhere to this convention as well. -After serialisation, the s-stream records the new write-to position of the buffer. This allows for *chaining* of serialisations, which can prove useful when implementing the trait for custom types. - ### Deserialisation -As with serialisation, deserialisation uses streams (just with the `Dstream` type; short for *deserialisation stream*): +Deserialisation works with an almost identical syntax to serialisation. + +To deserialise a buffer, simply call the `deserialise` method: ```rs -let data = [0x45, 0x54]; +use bzipper::Deserialise; -let mut stream = bzipper::Dstream::new(&data); +let data = [0x45, 0x54]; +assert_eq!(<u16>::deserialise(&data).unwrap(), 0x4554); ``` -Using these streams is also just as simple as with s-streams: +Just like with serialisations, the `Dstream` can be used to deserialise chained elements: ```rs use bzipper::Deserialise; let data = [0x45, 0x54]; -let mut stream = bzipper::Dstream::new(&data); +let stream = bzipper::Dstream::new(&data); -assert_eq!(u16::deserialise(&mut stream).unwrap(), 0x4554); +assert_eq!(stream.take::<u8>().unwrap(), 0x45); +assert_eq!(stream.take::<u8>().unwrap(), 0x54); ``` - -When chaining serialisations, keep in mind that appropriate deserialisations should come in **reverse order** (streams function similarly to stacks in this sense). - -## Copyright & Licensing - -Copyright 2024 Gabriel Bjørnager Jensen. - -This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - -You should have received a copy of the GNU Lesser General Public License along with this program. If not, see <https://www.gnu.org/licenses/>. |