thruput-xdrs 0.17.1

XDR Serialization Library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

//! # _XDRS_ (XDR Serialization)
//!
//! This crate provides:
//!
//! - Traits [`ReadXDR`] and [`WriteXDR`], for converting between Rust values
//!   and the [XDR][RFC-4506] 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][RFC-4506] 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](cxs) ("Compact XDR Serialization")
//!   - [TXS](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.
//!
//! [RFC-4506]: https://datatracker.ietf.org/doc/html/rfc4506

#![no_std]
#![warn(missing_docs)]
#![allow(ambiguous_glob_reexports)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![allow(hidden_glob_reexports)]

#[cfg(target_pointer_width = "16")]
compile_error!("xdrs does not support 16-bit targets");

#[cfg(feature = "alloc")]
extern crate alloc;

// Traits for translating Rust values to and from the XDR data model
pub mod discrim;
pub mod encodes_as;
pub mod read_xdr;
pub mod write_xdr;

// Variable-length data written from separate chunks
pub mod chunked;

// The abstract interface for serialization formats
pub mod serialize;

// CXS serialization
pub mod cxs;

// TXS serialization
pub mod txs;

pub(crate) mod mu;

pub(crate) mod valid_u32;

pub use chunked::*;
pub use discrim::*;
pub use encodes_as::*;
pub use read_xdr::*;
pub use write_xdr::*;

pub use serialize::reader::ReadError;
pub use serialize::reader::ReadResult;
pub use serialize::reader::*;

pub use serialize::writer::WriteError;
pub use serialize::writer::WriteResult;
pub use serialize::writer::*;

pub use serialize::writer_unchecked::*;

#[cfg(feature = "repr")]
#[cfg_attr(docsrs, doc(cfg(feature = "repr")))]
pub use xdr_repr;

#[cfg(feature = "derive")]
#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
pub use xdr_derive::{ConstWriteXDR, ConstXDRSize, ReadXDR, WriteXDR};

#[cfg(all(feature = "derive", feature = "repr"))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "derive", feature = "repr"))))]
pub use xdr_derive::XDR;

#[cfg(feature = "int128")]
#[cfg_attr(docsrs, doc(cfg(feature = "int128")))]
mod int128;

pub use xdr_common::*;

#[cfg(feature = "heapless")]
#[cfg_attr(docsrs, doc(cfg(feature = "heapless")))]
mod heapless;