Crate xdrs 

XDRS (XDR Serialization)

This crate provides:

• Traits ReadXDR and WriteXDR, for converting between Rust values and the XDR data model.

• Trait EncodesAs, for declaring that a type encodes to the same bytes as some XDR type, so it can be passed where that type is expected.

• Types ChunkedBytes and ChunkedVec, which encode data held in separate chunks like one BytesM or VecM, without first copying the chunks together.

• Traits Reader and Writer, for converting between the XDR data model and some serialization format.

• Trait WriterUnchecked, an infallible, unsafe counterpart to Writer with no runtime checks, for code-size-sensitive targets.

• Implementations of Reader and Writer:

  • CXS (“Compact XDR Serialization”)
  • TXS (“Traditional XDR Serialization”)

The library is no_std, but a few extra things can be enabled with feature alloc.

Features

This crate supports several optional features:

Deserialization options

• permissive: When reading CXS data, don’t reject (as is the default) integers using non-minimal-size encoding. Also, when reading TXS data, do not reject non-zero padding bytes. This includes the upper two bytes of a 4-byte wire integer decoded as i16 or u16, which are treated as padding; in permissive mode these bytes are allowed to be non-zero and the value is truncated to 16 bits.

Allocation

• alloc: Enables allocation-based interfaces:

  • Vec<u8> and Vec<T> implementations of ReadXDR and WriteXDR
  • String implementations of ReadXDR and WriteXDR
  • BufWriter types in cxs and txs modules for growable buffers
  • encode() functions that return owned Vec<u8>

  xdr_common owned types require alloc. Without the alloc feature, BytesM<MAX>, StringM<MAX>, and VecM<T, MAX> compile but their ReadXDR implementations panic unconditionally at runtime. Do not call the decode APIs for these types in a no-alloc build.

Extended types

• int128: Enables convenient extensions to the XDR specification: support for i128 and u128. These types are encoded as two 64-bit integers (high bits and low bits).

Optional dependencies

• derive: Enables derive macros from the xdr-derive crate:

  • #[derive(ReadXDR)]: Automatically implement ReadXDR
  • #[derive(WriteXDR)]: Automatically implement WriteXDR
  • #[derive(XDR)]: Automatically implement XDR type representation traits

• repr (requires alloc): Enables the xdr-repr crate for XDR specification representation. Provides types and traits for describing XDR type definitions.

• heapless: Enables support for types from the heapless package.

• ns (implies repr): Enables namespace support in xdr-repr for C++-like scoping of XDR definitions.

Re-exports

pub use serialize::reader::ReadError;

pub use serialize::reader::ReadResult;

pub use serialize::writer::WriteError;

pub use serialize::writer::WriteResult;

pub use xdr_repr;repr

pub use chunked::*;

pub use discrim::*;

pub use encodes_as::*;

pub use read_xdr::*;

pub use write_xdr::*;

pub use serialize::reader::*;

pub use serialize::writer::*;

pub use serialize::writer_unchecked::*;

Modules

chunked

Variable-length data held as separate chunks.

cxs

CXS (Compact XDR Serialization)

discrim

The XDRDiscriminant trait, for types that act as XDR union discriminants.

encodes_as

Declaring that one type serializes like another.

read_xdr

Reading XDR data into Rust types.

serde_hexserde

Serde adapter for fixed-size byte arrays encoded as hexadecimal strings.

serialize

An interface for serializing XDR primitives, which certain formats may implement. The formats must:

txs

TXS (Traditional XDR Serialization) implementation.

write_xdr

Writing Rust values as XDR data.

Structs

BytesM

A byte vector with a maximum length constraint.

StringM

A string type that stores arbitrary bytes with a maximum length constraint.

VecM

A vector with a maximum length constraint.

Enums

Error

Errors that can occur when working with XDR types.

Constants

MAX_PREALLOC_BYTESalloc

The maximum number of bytes a decoder will preallocate for a variable-length collection before reading its elements.

Traits

StaticIfNoAllocalloc

Helper trait bound on VecM elements that requires 'static only in no-alloc builds.

Functions

box_as_refalloc

Borrows the value behind a Box in a const context.

Type Aliases

Boxalloc

A pointer type that uniquely owns a heap allocation of type T.

Vecalloc

A contiguous growable array type.

Derive Macros

ConstWriteXDRderive

Derives const-compatible XDR encoding methods for compile-time use.

ConstXDRSizederive

Derives worst-case XDR size bounds as cxs::ConstMaxSize and txs::ConstMaxSize trait implementations.

ReadXDRderive

Derives the ReadXDR trait for a struct or enum.

WriteXDRderive

Derives the WriteXDR trait for a struct or enum.

XDRderive and repr

Derives the XDR and HasTypeDef traits.