Expand description
Extensible interface for converting data to/from wire protocols.
The purpose of this crate is to provide a simplified interface for reading from/writing to a
buffer of bytes in an efficient and memory-safe way. It provides default implementations for
reading/writing primitive types–integers (u8, i32, f64, etc), strings (&str), byte slices
and arrays (&[u8; 3]). It also offers extensibilty to other types and more complex structs
via traits (WireRead, WireWrite, and their variants).
In addition to supporting standard single-slice buffers, this crate provides equivalent
support for non-contiguous buffers by means of the VectoredReader and VectoredWriter,
along with corresponding VectoredRead and VectoredWrite traits and their variants.
Instead of operating on a single slice (&[u8]), these operate on a slice of slices
(&[&[u8]]) and transparently handle reading from/writing to a chunk that spans multiple
slices. This can be useful in cases where it is not desirable or feasible to guarantee
contiguous memory–ring buffers, two-dimensional arrays, iovec API calls,
PACKET_MMAP buffers and the like.
The Reader and Writer data structures exposed by this crate are effectively light-weight wrappers around slices, meaning that they can be created, copied and dropped freely with very little memory overhead.
Examples
To read data from a simple slice:
use wire_rs::{WireError, WireReader};
fn read_data<'a>(slice: &'a [u8]) -> Result<(u16, i8, &'a str), WireError> {
let mut reader: WireReader = WireReader::new(slice);
let s1 = reader.read()?;
let s2 = reader.read()?;
let s3 = reader.read_ref(7)?;
Ok((s1, s2, s3))
}
To write data to a slice:
use wire_rs::{WireError, WireWriter};
fn write_data(slice: &mut [u8]) -> Result<(), WireError> {
let mut writer: WireWriter = WireWriter::new(slice);
writer.write(&10i32)?;
writer.write_part::<u64, 3>(&0xFFu64)?; // Write the least significant 3 bytes of the given value to the wire (as long as the value will fit)
writer.write("Hello, world!")?;
writer.finalize()?; // Return an error if there were more bytes available on `slice` that we didn't write to
Ok(())
}
To read/write data in little endian:
use wire_rs::{WireReader, WireWriter};
fn endianness() {
let default_reader: WireReader = WireReader::new(&[]);
// ^ Big-endian by default (same for WireWriter)
// Note: you may need to explicitly specify the `WireReader` type
// such as in this case to use the default.
let be_reader = WireReader::<true>::new(&[]);
// Explicitly set to big-endian ^
let le_writer = WireWriter::<false>::new(&mut []);
// Explicitly set to little-endian ^
}
Structs
&[u8] slices that provides an easy interface for
reading data types from the vectored slices.&[u8] slice that provides an easy interface for reading data types
from the slice.