binary-util
A panic-free binary utility crate to read/write binary streams over the wire.
BinaryUtils provides the following features:
binary_util::io
, to read and write to streams manually.binary_util::interfaces
, to allow automation of reading data structures.binary_util::BinaryIo
, to automatically implementbinary_util::interfaces::Reader
andbinary_util::interfaces::Writer
.binary_util::types
for reading and writing non-primitive types likeu24
andvarint
.
Getting Started
Binary Utils is available on crates.io, add the following to your Cargo.toml
:
[]
= "0.3.4"
Optionally, if you wish to remove the derive
feature, you can add the following to your Cargo.toml
:
[]
= { = "0.3.4", = false }
To explicitly enable derive, you can use:
[]
= { = "0.3.0", = false, = ["derive"] }
Binary IO
The io
module provides a way to contingiously write and read binary data with the garauntees of being panic-free.
This module provides two structs, ByteReader
and ByteWriter
, which are both wrappers
around bytes::Buf
and bytes::BufMut
respectively.
Generally, you will want to use ByteReader
and ByteWriter
when you are reading and writing binary data manually.
Read Example: The following example shows how to read a varint from a stream:
use ByteReader;
const BUFFER: & = &; // 2147483647
Write Example: The following is an example of how to write a string to a stream:
use ByteWriter;
Real-world example:
A more real-world use-case of this module could be a simple pong server,
where you have two packets, Ping
and Pong
, that respectively get relayed
over udp.
This is an example using both ByteReader
and ByteWriter
utilizing std::net::UdpSocket
to send and receive packets.
use ;
use UdpSocket;
Interfaces
The interfaces
module provides a way to implement reading and writing binary data with
two traits, Reader
and Writer
.
Generally, you will refer to using BinaryIo
when you are implementing or enum; However in the
scenario you are implementing a type that may not be compatible with BinaryIo
, you can use
these traits instead.
Example:
The following example implements the Reader
and Writer
traits for a HelloPacket
allowing
it to be used with BinaryIo
; this example also allows you to read and write the packet with an
easier convention.
use ;
use ;
With the example above, you now are able to read and write the packet with BinaryIo
,
as well as the added functionality of being able to read and write the packet with
easier with the read
and write
methods that are now implemented.
Types
The types
module provides a way to implement non-primitive types when using the BinaryIo
derive macro.
This module provides the following helper types:
- [
varu32
](https://docs.rs/binary-util/latest/binary_util/types/struct.varu32.html - An unsigned 32-bit variable length integer - [
vari32
](https://docs.rs/binary-util/latest/binary_util/types/struct.vari32.html - A signed 32-bit variable length integer - [
varu64
](https://docs.rs/binary-util/latest/binary_util/types/struct.varu64.html - An unsigned 64-bit variable length integer - [
vari64
](https://docs.rs/binary-util/latest/binary_util/types/struct.vari64.html - A signed 64-bit variable length integer u24
- A 24-bit unsigned integeri24
- A 24-bit signed integerLE
- A little endian typeBE
- A big endian type
General Usage:
use BinaryIo;
use ;
use ;