Crate nuts_bytes

Conversion into a binary data format.

The nuts-bytes crate implements a tool that converts structured data into a binary format. See the Format specification section for a detailed description of the format.

Deserialization from a binary representation

The deserialization describes the process of converting binary data into a data type that implements the FromBytes trait.

The Reader utility performs this deserialization by

1. taking binary data from a source type that implements the TakeBytes trait and finally
2. performs the deserialization.

The crate implements TakeBytes already for &[u8]. It takes bytes from a slice of u8 values.

Deserialization example

use nuts_bytes::{Error, Reader, TakeBytesError};

// deserialize a primitive (u32)
let mut reader = Reader::new([0x00, 0x00, 0x02, 0x9A].as_slice());
let n: u32 = reader.read().unwrap();

assert_eq!(n, 666);

// Not enough data available
let mut reader = Reader::new([0; 3].as_slice());
let err = reader.read::<u32>().unwrap_err();

assert!(matches!(err, Error::TakeBytes(TakeBytesError::Eof)));

Serialization into a binary representation

The serialization describes the process of converting a data type that implements the ToBytes trait into its binary representation.

The Writer utility performs this serialization. It

1. performs the serialization and finally
2. pushes the binary data into a target type, that implements the PutBytes trait.

The crate implements PutBytes for the following types:

• &mut [u8] Serialize into a slice of u8 values. Not more than slice::len() bytes can be written. If the number of bytes exceeds the size of the slice, a PutBytesError::NoSpace error is raised.
• Vec<u8> Serialize into a Vec of u8 values. The binary data are appended to the Vec.
• &mut Vec<u8> Serialize into a mutable reference of a Vec of u8 values. The binary data are appended to the Vec.

Serialization examples

Serialize into a vec

use nuts_bytes::Writer;

// serialize a primitive (u32)
let mut writer = Writer::new(vec![]);
let n = writer.write(&666u32).unwrap();

assert_eq!(n, 4);
assert_eq!(writer.into_target(), [0x00, 0x00, 0x02, 0x9A]);

Serialize into a slice

use nuts_bytes::Writer;

// serialize a primitive (u32)
let mut buf = [0; 4];
let mut writer = Writer::new(buf.as_mut_slice());
let n = writer.write(&666u32).unwrap();

assert_eq!(n, 4);
assert_eq!(buf, [0x00, 0x00, 0x02, 0x9A]);

// Not enough space for serialization
let mut buf = [0; 3];
let mut writer = Writer::new(buf.as_mut_slice());
let err = writer.write(&666u32).unwrap_err();

assert_eq!(format!("{}", err), "no more space available for writing");

Format specification

The binary format is described here in detail.

Modules

• doc_derive
  Derive macros available if nuts-bytes is built with features = ["derive"].
• doc_format
  Documentation: format specification

Structs

• Reader
  A cursor like utility that reads structured data from an arbitrary source.
• Writer
  A cursor like utility that writes structured data into an arbitrary target.

Enums

• Error
  Error type of the library.
• PutBytesError
  Error type for the PutBytes trait.
• TakeBytesError
  Error type for the TakeBytes trait.

Traits

• FromBytes
  Trait that supports reading datatypes from a binary data stream.
• PutBytes
  Trait that describes a writer of binary data.
• TakeBytes
  Trait that describes a reader of binary data.
• ToBytes
  Trait that supports writing datatypes into a binary data stream.

Derive Macros

• FromBytes
  Derive macro implementation of the FromBytes trait.
• ToBytes
  Derive macro implementation of the ToBytes trait.