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§
- Vectored
Cursor - A cursor that acts as an index over a set of vectored immutable slices and provides operations to sequentially read data from the slices.
- Vectored
Cursor Mut - A cursor that acts as an index over a set of vectored mutable slices and provides operations to sequentially write data to the slices.
- Vectored
Reader - A wrapper around a slice of
&[u8]
slices that provides an easy interface for reading data types from the vectored slices. - Vectored
Writer - Wire
Cursor - A cursor that acts as an index over a contiguous immutable slice and provides operations to sequentially read data from it.
- Wire
Cursor Mut - A cursor that acts as an index over a mutable slice and provides operations to sequentially write data to it.
- Wire
Index - An index of a buffer or vectored buffers.
- Wire
Reader - A wrapper around a
&[u8]
slice that provides an easy interface for reading data types from the slice. - Wire
Writer
Enums§
- Wire
Error - An error in reading from or writing to a wire.
Traits§
- Vectored
Read - Deserialization to an owned data type from the vectored wire.
- Vectored
Read Comp - Deserialization to a composite data type (i.e. containing both owned structures and references) from the vectored wire.
- Vectored
Read Part - Deserialization to an owned data type from a portion of the vectored wire smaller than what the data type would normally consume.
- Vectored
Read Ref - Deserialization to an immutable reference of a data type from the vectored wire.
- Vectored
Write - Serialization from a data type to the vectored wire.
- Vectored
Write Part - Serialization from an owned data type to a portion of the vectored wire smaller than what the data type would normally produce.
- Wire
Read - Deserialization to an owned data type from the wire.
- Wire
Read Comp - Deserialization to a composite data type (i.e. containing both owned structures and references) from the wire.
- Wire
Read Part - Deserialization to an owned data type from a portion of the wire smaller than what the data type would normally consume.
- Wire
Read Ref - Deserialization to an immutable reference of a data type from the wire.
- Wire
Write - Serialization from a data type to the wire.
- Wire
Write Part - Serialization from a data type to a portion of the wire smaller than the full size of the data type.