nuts-bytes 0.1.1

A binary data format for Serde
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

# nuts-bytes: A binary data format for [Serde].

The `nuts-bytes` crate implements a [Serde] data format that converts into
a binary format.

## API documentation

The API documentation is located [here](https://docs.rs/nuts-bytes/).

## Format specification

The binary format is specified in [docs/format.md].

## Deserialization example

```rust
use nuts_bytes::Reader;
use serde::Deserialize;

#[derive(Debug, Deserialize, PartialEq)]
struct SampleStruct {
    f1: u8,
    f2: u16,
};

#[derive(Debug, Deserialize, PartialEq)]
enum SampleEnum {
    V1(u32)
}

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

let n: u32 = reader.deserialize().unwrap();
assert_eq!(n, 666);

// deserialize a struct
let mut reader = Reader::new([0x07, 0x02, 0x9A, 0x00].as_slice());

let sample: SampleStruct = reader.deserialize().unwrap();
assert_eq!(sample, SampleStruct{ f1: 7, f2: 666 });
assert_eq!(*reader.as_ref(), [0x00]); // Still one byte left

// deserialize an enum
let mut reader = Reader::new([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x9A].as_slice());

let sample: SampleEnum = reader.deserialize().unwrap();
assert_eq!(sample, SampleEnum::V1(666));

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

assert_eq!(format!("{}", err), "No more bytes are available for reading.");
```

## Serialization example

```rust
use nuts_bytes::Writer;
use serde::Serialize;

#[derive(Serialize)]
struct SampleStruct {
    f1: u8,
    f2: u16,
};

#[derive(Serialize)]
enum SampleEnum {
    V1(u32)
}

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

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

// serialize a struct
let sample = SampleStruct{ f1: 7, f2: 666 };
let mut writer = Writer::new(vec![]);
let n = writer.serialize(&sample).unwrap();

assert_eq!(n, 3); // 3 bytes written
assert_eq!(writer.into_target(), [0x07, 0x02, 0x9A]);

// serialize an enum
let sample = SampleEnum::V1(666);
let mut writer = Writer::new(vec![]);
let n = writer.serialize(&sample).unwrap();

assert_eq!(n, 8); // 8 bytes written
assert_eq!(writer.into_target(), [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x9A]);
```

[Serde]: https://www.serde.rs
[docs/format.md]: https://github.com/drobin/nuts-bytes/blob/master/docs/format.md