/serde-xdr

XDR serialization and deserialization implementation for Serde

Primary LanguageRustGNU General Public License v3.0GPL-3.0

XDR serialization and deserialization for Serde

This crate implements serialization and deserialization of the External Data Representation Standard (XDR) for the Serde serialization and deserialization framework.

Usage

To use the official version published on crates.io, add the following to your Cargo.toml file:

[dependencies]
serde-xdr = "0.6"

To serialize and deserialize data, you can use the provided helper functions:

  • xdr_serde::from_bytes(&mut bytes) -> Result<T>
  • xdr_serde::from_reader(&mut reader) -> Result<T>
  • xdr_serde::to_bytes(&object_to_serialize) -> Result<Vec<u8>>
  • xdr_serde::to_writer(&mut writer, &object_to_serialize) -> Result<()>

A more complete example is available in the documentation.

Data Type Map

The table below describes the mapping between Rust types and XDR.

Rust type XDR Reference XDR Details
bool boolean a 32-bit MSB integer that's zero or one
i8 integer a 32-bit MSB integer
i16 integer a 32-bit MSB integer
i32 integer a 32-bit MSB integer
i64 hyper integer a 64-bit MSB integer
u8 unsigned integer an unsigned 32-bit MSB integer
u16 unsigned integer an unsigned 32-bit MSB integer
u32 unsigned integer an unsigned 32-bit MSB integer
u64 unsigned hyper integer an unsigned 64-bit MSB integer
f32 floating-point a 32-bit MSB floating-point number
f64 double-precision floating-point a 64-bit MSB floating-point number
char unsigned integer an unsigned 32-bit MSB integer
&str 1 string an unsigned 32-bit MSB integer representing the length, followed by one byte for each character of the string
String 1 string an unsigned 32-bit MSB integer representing the length, followed by one byte for each character of the string
Option<T> optional-data a 32-bit MSB integer that's zero or one, and if it's one it is followed by the serialization of T
() void no bytes are serialized
struct T; void no bytes are serialized
struct T(A, B, ...) structure each element in the tuple is serialized in sequence
struct T { _: A, _: B, ... } structure each field is serialized in sequence in the order they were declared
(A, B, ...) structure each element in the tuple is serialized in sequence
enum 2 discriminated union an unsigned 32-bit MSB integer representing the index of the variant (starting from zero), followed by the serialization of the variant
&[T] 3 variable-length array 4 an unsigned 32-bit MSB integer representing the length, followed by the serialization of each element
[T; N] 3 variable-length array 5,6 an unsigned 32-bit MSB integer representing the length, followed by the serialization of each element
Vec<T> 3 variable-length array an unsigned 32-bit MSB integer representing the length, followed by the serialization of each element
serde_bytes::Bytes 3 variable-length opaque data an unsigned 32-bit MSB integer representing the length, followed by the bytes with up to three bytes with zeros for padding

Notes

  1. Must be valid ASCII and can't be longer than 2^32 - 1 characters.
  2. Can't have more than 2^32 - 1 variants.
  3. Can't have more than 2^32 - 1 elements.
  4. Use serde_bytes for a more efficient serialization.
  5. Efficient mapping to fixed-length array has not been implemented yet.
  6. If efficient serialization of [u8; N] is desired, use serde_xdr::opaque_data::fixed_length.

Status

This crate should not be considered stable before more thorough real-world tests have been made. If you find any bugs or inconsistencies, please report them as GitHub issues.

One thing that is currently lacking tests is serialization and deserialization failure conditions.

Documentation also could be improved.