diff options
| -rw-r--r-- | CHANGELOG.md | 5 | ||||
| -rw-r--r-- | Cargo.toml | 2 | ||||
| -rw-r--r-- | README.md | 64 | ||||
| -rw-r--r-- | doc-icon.svg (renamed from bzipper-monochrome.svg) | 0 | ||||
| -rw-r--r-- | src/deserialise/test.rs | 4 | ||||
| -rw-r--r-- | src/lib.rs | 64 |
6 files changed, 134 insertions, 5 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index c16e1dd..b6b156e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,11 @@ This is the changelog of `bzipper`. See `"README.md"` for more information. +## 0.4.7 + +* Extensively elaborate docs +* Update readme + ## 0.4.6 * Fix docs logo (again) @@ -1,6 +1,6 @@ [package] name = "bzipper" -version = "0.4.6" +version = "0.4.7" authors = ["Gabriel Bjørnager Jensen"] edition = "2021" description = "Binary (de)serialiser." @@ -1,4 +1,4 @@ -# `bzipper` +# bzipper [`bzipper`](https://crates.io/crates/bzipper) is a binary (de)serialiser for the Rust language. @@ -8,6 +8,7 @@ Therefore, this crate may be more suited for networking or other cases where a f 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`. See [Docs.rs](https://docs.rs/bzipper/latest/bzipper/) for documentation. @@ -20,6 +21,67 @@ Unsized types, such as `str` and slices, are not supported. Instead, array 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). + +Many core types come implemented with `bzipper`, including primitives as well as some standard library types such as `Option` and `Result`. + +### Serialisation + +To serialise an object implementing `Serialise`, simply allocate a so-called "s-stream" (short for *serialisation stream*) with the `Sstream` type: + +```rs +let mut buf: [u8; 16] = Default::default(); + +let mut stream = bzipper::Sstream::new(&mut buf); +``` + +The resulting stream is immutable in the sense that it cannot grow its buffer, altough it does keep track of the buffer's state. + +A byte sequence can be added to our new stream by passing the stream to a call to the `serialise` method: + +```rs +use bzipper::Serialise; + +let mut buf: [u8; 2] = 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>`). + +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). + +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*): + +```rs +let data = [0x45, 0x54]; + +let mut stream = bzipper::Dstream::new(&data); +``` + +Using these streams is also just as simple as with s-streams: + +```rs +use bzipper::Deserialise; + +let data = [0x45, 0x54]; +let mut stream = bzipper::Dstream::new(&data); + +assert_eq!(u16::deserialise(&mut stream).unwrap(), 0x4554); +``` + +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. diff --git a/bzipper-monochrome.svg b/doc-icon.svg index 5a6e1f8..5a6e1f8 100644 --- a/bzipper-monochrome.svg +++ b/doc-icon.svg diff --git a/src/deserialise/test.rs b/src/deserialise/test.rs index 70293cb..e398b4d 100644 --- a/src/deserialise/test.rs +++ b/src/deserialise/test.rs @@ -19,7 +19,7 @@ // er General Public License along with bzipper. If // not, see <https://www.gnu.org/licenses/>. -use crate::{Deserialise, FixedString}; +use crate::{Deserialise, Dstream, FixedString}; #[test] fn test_deserialise() { @@ -33,7 +33,7 @@ fn test_deserialise() { 0x00, 0x03, 0xB1, 0x01, 0x00, 0x00, 0x01, 0x80, ]; - let mut stream = From::from(&data); + let mut stream = Dstream::new(&data); assert_eq!( u8::deserialise(&mut stream).unwrap(), @@ -19,7 +19,7 @@ // er General Public License along with bzipper. If // not, see <https://www.gnu.org/licenses/>. -#![doc(html_logo_url = "https://gitlab.com/bjoernager/bzipper/-/raw/master/bzipper-monochrome.svg?ref_type=heads")] +#![doc(html_logo_url = "https://gitlab.com/bjoernager/bzipper/-/raw/master/doc-icon.svg?ref_type=heads")] //! Binary (de)serialisation. //! @@ -29,6 +29,7 @@ //! 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`. //! //! # Data model //! @@ -38,6 +39,67 @@ //! Unsized types, such as [`str`] and [slices](slice), are not supported. //! Instead, [arrays](array) 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](Dstream) and [s-streams](Sstream)). +//! +//! Many core types come implemented with `bzipper`, including primitives as well as some standard library types such as [`Option`] and [`Result`](core::result::Result). +//! +//! ## Serialisation +//! +//! To serialise an object implementing `Serialise`, simply allocate a so-called "s-stream" (short for *serialisation stream*) with the [`Sstream`] type: +//! +//! ``` +//! let mut buf: [u8; 16] = Default::default(); +//! +//! let mut stream = bzipper::Sstream::new(&mut buf); +//! ``` +//! +//! The resulting stream is immutable in the sense that it cannot grow its buffer, altough it does keep track of the buffer's state. +//! +//! A byte sequence can be added to our new stream by passing the stream to a call to the [`serialise`](Serialise::serialise) method: +//! +//! ``` +//! use bzipper::Serialise; +//! +//! let mut buf: [u8; 2] = 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>`). +//! +//! Whilst the *maximum* ammount of bytes is specified by the [`SERIALISE_LIMIT`](Serialise::SERIALISE_LIMIT) constant, this can in cases be lower (for example with [`None`] variants which are always encoded as a single, null byte). +//! +//! 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*): +//! +//! ``` +//! let data = [0x45, 0x54]; +//! +//! let mut stream = bzipper::Dstream::new(&data); +//! ``` +//! +//! Using these streams is also just as simple as with s-streams: +//! +//! ``` +//! use bzipper::Deserialise; +//! +//! let data = [0x45, 0x54]; +//! let mut stream = bzipper::Dstream::new(&data); +//! +//! assert_eq!(u16::deserialise(&mut stream).unwrap(), 0x4554); +//! ``` +//! +//! When chaining serialisations, keep in mind that appropriate deserialisations should come in **reverse order** (streams function similarly to stacks in this sense). #![no_std] |
