andylokandy/byte

A low-level, zero-copy, panic-free, binary serializer and deserializer. (parser and encoder)

Byte

A low-level, zero-copy and panic-free binary serializer and deserializer.

Documentation

Usage

Add the following to your Cargo.toml:

[dependencies]
byte = "0.2"

Byte is a no_std library; it can be used in any #![no_std] situation or crate.

Overview

Byte is designed to encode or decode binary data in a fast and low-level way. A classical use case is I2C communication en/decoding.

Byte provides two core traits TryRead and TryWrite. Types that implement these traits can be serialized into or deserialized from byte slices.

The library is meant to be simple, and it will always be.

Example

use byte::*;

let bytes: &[u8] = &[0xde, 0xad, 0xbe, 0xef];

let offset = &mut 0;
let num = bytes.read_with::<u32>(offset, BE).unwrap();
assert_eq!(num, 0xdeadbeef);
assert_eq!(*offset, 4);

use byte::*;
use byte::ctx::{Str, NULL};

let bytes: &[u8] = b"hello, world!\0dump";

let offset = &mut 0;
let str = bytes.read_with::<&str>(offset, Str::Delimiter(NULL)).unwrap();
assert_eq!(str, "hello, world!");
assert_eq!(*offset, 14);

Contribution

All kinds of contribution are welcomed.

• Issues. Feel free to open an issue when you find typos, bugs, or have any question.
• Pull requests. New collection, better implementation, more tests, more documents and typo fixes are all welcomed.

License

Licensed under MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

byte's Issues

HardFault when writing u16

This line in src/ctx/num.rs:80 HardFaults for me:

unsafe { *(&mut bytes[0] as *mut _ as *mut _) = val };

     0x0000f3d4 <+168>:   ldrh    r0, [r0, #16]
     0x0000f3d6 <+170>:   rev16   r0, r0
=>   0x0000f3d8 <+172>:   strh    r0, [r6, #4]

Register values after 0x0000f3d6 has executed:

(gdb) info reg
r0             0x1e00              7680
r1             0x1                 1
r2             0xb                 11
r3             0x74                116
r4             0x11                17
r5             0x75                117
r6             0x2000045f          536872031
r7             0x200067b8          536897464
r8             0x76ffeebf          1996484287
r9             0x200002dc          536871644
r10            0xe9579d7e          -380134018
r11            0xeef7fdfa          -285737478
r12            0xfbdfedbf          -69210689
sp             0x20006690          0x20006690
lr             0x407b              16507
pc             0xf3d8              0xf3d8 <<mqtt_sn::defs::Message as byte::TryWrite>::try_write+172>
xPSR           0x21000017          553648151
msp            0x20006690          0x20006690
psp            0xfffbadf4          0xfffbadf4
primask        0x0                 0
basepri        0x0                 0
faultmask      0x0                 0
control        0x0                 0

I have validated that r6 + 4 is a valid memory address inside of the write buffer. No clue what is going on here.

Target platform is armv6-m, it works fine on Linux (x64).

A release with the empty read and write fix

I have been hit with the empty read/write issue when using the ieee802154 crate. Would it be possible to make a crate.io release of byte with that fix?

Add helper functions to send the serialized data directly to a stream

This feature exists in the bincode crate, which simplifies reading from and writing to streams (like TCP) more comfortable.

• Write data to stream (similar to this)
• Read data from strem (similar to this)

Usability of TryWrite trait

In order to use the TryWrite trait, you would need to allocate a byte array of the correct size in advance.

But how is it meant to be used? You can't know the size in advance.

I think, the API of the trait would need to change. The easiest change would be adding a second method, which returns the size in bytes without allocating anything.
Another option would be to return a Result<Vec> instaed of supplying a mutable reference to an u8 slice and returning the size, but I guess, that would be inefficient.
Or maybe the current trait could be used with some kind of fake slice?

So if you don't have a better solution, I'll add a new size method to the trait.

TryRead and TryWrite for u8 and i8 should be agnostic to context.

Currently, in the case of u8 and i8, only TryRead<Endian> and TryWrite<Endian> are implemented. In reality, endianness doesn't matter for single byte values, and you end up writing verbose code that seems to hint that there's some sort of different handling of the bytes.

// these two are the same net result
let u1: u8 = bytes.read_with(ofs, byte::ctx::Endian::Little)?;
let u2: u8 = bytes.read_with(ofs, byte::ctx::Endian::Big)?;

// ditto
let i1: i8 = bytes.read_with(ofs, byte::ctx::Endian::Little)?;
let i2: i8 = bytes.read_with(ofs, byte::ctx::Endian::Big)?;
        
// yet i cant use the default context (`()`) even though it makes my code a lot more readable 
// and doesn't leave me wondering why I need to specify an endianness for a single-byte value.
let sensible: u8 = bytes.read(ofs);
let sensible2: i8 = bytes.read(ofs);

Perhaps the TryRead for u8 and i8 should really be impl<'a, Ctx> TryRead<'a, Ctx> ? Or at the very least, also have a TryRead<()>/TryWrite<()> like bool (and conversely, maybe bool should be generic on context)?

Create a derive library

It would be nice to be able to derive the traits TryRead and TryWrite.
It would have to be done similar to serde-derive, but will probably be a bit easier because of the simpler format used in this crate.

This will have to be done in an additional crate and will be called byte-derive.

I'll try it myself, but I'm not that experienced with proc macros.