diff options
Diffstat (limited to 'src/lib.rs')
| -rw-r--r-- | src/lib.rs | 64 |
1 files changed, 63 insertions, 1 deletions
@@ -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] |