xdrs/
lib.rs

1//! # _XDRS_ (XDR Serialization)
2//!
3//! This crate provides:
4//!
5//! - Traits [`ReadXDR`] and [`WriteXDR`], for converting between Rust values
6//!   and the [XDR][RFC-4506] data model.
7//!
8//! - Trait [`EncodesAs`], for declaring that a type encodes to the same bytes
9//!   as some XDR type, so it can be passed where that type is expected.
10//!
11//! - Types [`ChunkedBytes`] and [`ChunkedVec`], which encode data held in
12//!   separate chunks like one `BytesM` or `VecM`, without first copying the
13//!   chunks together.
14//!
15//! - Traits [`Reader`] and [`Writer`], for converting between the
16//!   [XDR][RFC-4506] data model and some serialization format.
17//!
18//! - Trait [`WriterUnchecked`], an infallible, unsafe counterpart to
19//!   [`Writer`] with no runtime checks, for code-size-sensitive targets.
20//!
21//! - Implementations of [`Reader`] and [`Writer`]:
22//!   - [CXS](cxs) ("Compact XDR Serialization")
23//!   - [TXS](txs) ("Traditional XDR Serialization")
24//!
25//! The library is `no_std`, but a few extra things can be
26//! enabled with feature `alloc`.
27//!
28//! ## Features
29//!
30//! This crate supports several optional features:
31//!
32//! ### Deserialization options
33//!
34//! - **`permissive`**: When reading CXS data, don't reject (as is the default)
35//!   integers using non-minimal-size encoding.
36//!   Also, when reading TXS data, do not reject non-zero padding bytes.
37//!   This includes the upper two bytes of a 4-byte wire integer decoded as
38//!   `i16` or `u16`, which are treated as padding; in permissive mode these
39//!   bytes are allowed to be non-zero and the value is truncated to 16 bits.
40//!
41//! ### Allocation
42//!
43//! - **`alloc`**: Enables allocation-based interfaces:
44//!   - `Vec<u8>` and `Vec<T>` implementations of [`ReadXDR`] and [`WriteXDR`]
45//!   - `String` implementations of [`ReadXDR`] and [`WriteXDR`]
46//!   - `BufWriter` types in [`cxs`] and [`txs`] modules
47//!     for growable buffers
48//!   - `encode()` functions that return owned `Vec<u8>`
49//!
50//!   **`xdr_common` owned types require `alloc`.** Without the `alloc` feature,
51//!   `BytesM<MAX>`, `StringM<MAX>`, and `VecM<T, MAX>` compile but their
52//!   `ReadXDR` implementations panic unconditionally at runtime. Do not call
53//!   the decode APIs for these types in a no-alloc build.
54//!
55//! ### Extended types
56//!
57//! - **`int128`**: Enables convenient extensions to the XDR specification:
58//!   support for `i128` and `u128`. These types are encoded as two 64-bit
59//!   integers (high bits and low bits).
60//!
61//! ### Optional dependencies
62//!
63//! - **`derive`**: Enables derive macros from the `xdr-derive` crate:
64//!   - `#[derive(ReadXDR)]`: Automatically implement [`ReadXDR`]
65//!   - `#[derive(WriteXDR)]`: Automatically implement [`WriteXDR`]
66//!   - `#[derive(XDR)]`: Automatically implement XDR type representation
67//!     traits
68//!
69//! - **`repr`** (requires `alloc`): Enables the `xdr-repr` crate for XDR
70//!   specification representation. Provides types and traits for describing XDR
71//!   type definitions.
72//!
73//! - **`heapless`**: Enables support for types from the `heapless` package.
74//!
75//! - **`ns`** (implies `repr`): Enables namespace support in `xdr-repr` for
76//!   C++-like scoping of XDR definitions.
77//!
78//! [RFC-4506]: https://datatracker.ietf.org/doc/html/rfc4506
79
80#![no_std]
81#![warn(missing_docs)]
82#![allow(ambiguous_glob_reexports)]
83#![cfg_attr(docsrs, feature(doc_cfg))]
84#![allow(hidden_glob_reexports)]
85
86#[cfg(target_pointer_width = "16")]
87compile_error!("xdrs does not support 16-bit targets");
88
89#[cfg(feature = "alloc")]
90extern crate alloc;
91
92// Traits for translating Rust values to and from the XDR data model
93pub mod discrim;
94pub mod encodes_as;
95pub mod read_xdr;
96pub mod write_xdr;
97
98// Variable-length data written from separate chunks
99pub mod chunked;
100
101// The abstract interface for serialization formats
102pub mod serialize;
103
104// CXS serialization
105pub mod cxs;
106
107// TXS serialization
108pub mod txs;
109
110pub(crate) mod mu;
111
112pub(crate) mod valid_u32;
113
114pub use chunked::*;
115pub use discrim::*;
116pub use encodes_as::*;
117pub use read_xdr::*;
118pub use write_xdr::*;
119
120pub use serialize::reader::ReadError;
121pub use serialize::reader::ReadResult;
122pub use serialize::reader::*;
123
124pub use serialize::writer::WriteError;
125pub use serialize::writer::WriteResult;
126pub use serialize::writer::*;
127
128pub use serialize::writer_unchecked::*;
129
130#[cfg(feature = "repr")]
131#[cfg_attr(docsrs, doc(cfg(feature = "repr")))]
132pub use xdr_repr;
133
134#[cfg(feature = "derive")]
135#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
136pub use xdr_derive::{ConstWriteXDR, ConstXDRSize, ReadXDR, WriteXDR};
137
138#[cfg(all(feature = "derive", feature = "repr"))]
139#[cfg_attr(docsrs, doc(cfg(all(feature = "derive", feature = "repr"))))]
140pub use xdr_derive::XDR;
141
142#[cfg(feature = "int128")]
143#[cfg_attr(docsrs, doc(cfg(feature = "int128")))]
144mod int128;
145
146pub use xdr_common::*;
147
148#[cfg(feature = "heapless")]
149#[cfg_attr(docsrs, doc(cfg(feature = "heapless")))]
150mod heapless;
xdrs/lib.rs

xdrs/
lib.rs
