ser-write 0.1.0

Common traits for writer-style serializers and deserializers designed for no_std targets
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
100
101
102
103
104
105
106

ser-write
=========

Writer-style serializers and deserializers for convenience designed with embedded (`no_std`) targets in mind.

* Writer-style serializers use the common writer trait found in this crate.
* Designed for `no_std`.
* Fully supports `std` or `alloc` when enabled for code portability and testablilty.
* For each serializer a deserializer is provided for convenience.
* Embedded projects can implement `SerWrite` trait for custom containers, frame builders and more.

This crate provides:

* the trait - `SerWrite` which should be used by serializers to write the serialized output,
* `SerError` - a convenient error type,
* `SliceWriter` - a convenient slice writer object implementing `SerWrite`,
* `SerWrite` implementations for foreign types.

Depending on the enabled crate features, `SerWrite` is implemented for:

* `SliceWriter` - example slice writer implementation,
* [`arrayvec::ArrayVec<u8,CAP>`](https://crates.io/crates/arrayvec) - `arrayvec` feature,
* [`heapless::Vec<u8,CAP>`](https://crates.io/crates/heapless) - `heapless` feature,
* `Vec<u8>` - `alloc` or `std` feature,
* `VecDeque<u8>` - `alloc` or `std` feature,
* `io::Cursor<T: io::Write>` - `std` feature,


Usage
-----

Start by adding a dependency to the serializer:

For example:

```
[dependencies]
ser-write-json = { version = "0.1", default-features = false }
```

If you want to also pull implementations of `SerWrite` for the foreign types add:

```
ser-write = { version = "0.1", default-features = false, features = ["arrayvec", "heapless"] }
```

In the above example implementations for: `arrayvec::ArrayVec<u8;_>` and `heapless::Vec<u8>` are selected.


Serializers
-----------

Currently available serializers and deserializers are:

* [JSON](https://json.org) (compact) - [ser-write-json](ser-write-json/)
* [MessagePack](https://msgpack.org) - [ser-write-msgpack](ser-write-msgpack/)


Example
-------

An example `SliceWriter` implementation:

```rs
use ser_write::{SerWrite, SerResult, SerError};

#[derive(Debug, PartialEq)]

pub struct SliceWriter<'a> {
    pub buf: &'a mut [u8],
    pub len: usize
}

impl SerWrite for SliceWriter<'_> {
    fn write(&mut self, buf: &[u8]) -> SerResult<()> {
        let end = self.len + buf.len();
        match self.buf.get_mut(self.len..end) {
            Some(chunk) => {
                chunk.copy_from_slice(buf);
                self.len = end;
                Ok(())
            }
            None => Err(SerError::BufferFull)
        }
    }
}
```


Alternatives
------------

For `alloc` only:
* [serde_json](https://crates.io/crates/serde_json)

Alternatively there's a Rust Embedded Community crate for serializeing JSONs without `std`:

* [serde-json-core](https://crates.io/crates/serde-json-core)
* [serde-json-core-fmt](https://crates.io/crates/serde-json-core-fmt) (a writer-style attempt abusing `fmt::Display` trait)

`serde-json-core` is a true `no_std`, no `alloc` alternative but rather inconvenient. One has to serialize data into intermediate slices instead just pushing data to outgoing buffers or frame builder implementations.


Why though?
-----------

* This crate would not be needed once something like `io::Write` lands in the Rust core.