Crate wire_rs

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§

VectoredCursor: A cursor that acts as an index over a set of vectored immutable slices and provides operations to sequentially read data from the slices.
VectoredCursorMut: A cursor that acts as an index over a set of vectored mutable slices and provides operations to sequentially write data to the slices.
VectoredReader: A wrapper around a slice of &[u8] slices that provides an easy interface for reading data types from the vectored slices.
VectoredWriter
WireCursor: A cursor that acts as an index over a contiguous immutable slice and provides operations to sequentially read data from it.
WireCursorMut: A cursor that acts as an index over a mutable slice and provides operations to sequentially write data to it.
WireIndex: An index of a buffer or vectored buffers.
WireReader: A wrapper around a &[u8] slice that provides an easy interface for reading data types from the slice.
WireWriter

Enums§

WireError: An error in reading from or writing to a wire.

Traits§

VectoredRead: Deserialization to an owned data type from the vectored wire.
VectoredReadComp: Deserialization to a composite data type (i.e. containing both owned structures and references) from the vectored wire.
VectoredReadPart: Deserialization to an owned data type from a portion of the vectored wire smaller than what the data type would normally consume.
VectoredReadRef: Deserialization to an immutable reference of a data type from the vectored wire.
VectoredWrite: Serialization from a data type to the vectored wire.
VectoredWritePart: Serialization from an owned data type to a portion of the vectored wire smaller than what the data type would normally produce.
WireRead: Deserialization to an owned data type from the wire.
WireReadComp: Deserialization to a composite data type (i.e. containing both owned structures and references) from the wire.
WireReadPart: Deserialization to an owned data type from a portion of the wire smaller than what the data type would normally consume.
WireReadRef: Deserialization to an immutable reference of a data type from the wire.
WireWrite: Serialization from a data type to the wire.
WireWritePart: Serialization from a data type to a portion of the wire smaller than the full size of the data type.

Type Aliases§