xdrs/serialize/
writer.rs

1//! Writing XDR values to a serialization format.
2//!
3//! This module defines the [`Writer`] trait, which provides methods for
4//! writing [XDR][RFC-4506] primitive types (as defined in RFC 4506)
5//! to some underlying serialization format.
6//! Implementations of this trait can be used with [`WriteXDR`](crate::WriteXDR)
7//! to serialize complex types.
8//!
9//! [RFC-4506]: https://datatracker.ietf.org/doc/html/rfc4506
10
11/// Errors that can occur when writing XDR data.
12#[derive(Copy, Clone, Debug)]
13pub enum WriteError {
14    /// The writer has run out of space.
15    SpaceExhausted,
16
17    /// An array length is too large to be represented in XDR.
18    InvalidArrayLength,
19}
20
21impl core::fmt::Display for WriteError {
22    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
23        match self {
24            WriteError::SpaceExhausted => write!(f, "space exhausted"),
25            WriteError::InvalidArrayLength => write!(f, "invalid array length (too large)"),
26        }
27    }
28}
29
30impl core::error::Error for WriteError {}
31
32/// A result type for writer operations.
33pub type WriteResult<T = ()> = core::result::Result<T, WriteError>;
34
35/// Something that can write XDR values to a serialization format.
36///
37/// This trait provides methods for writing XDR primitive types to an
38/// underlying serialization format. The type parameter `F` represents
39/// the format being written (e.g., `CXS` or `TXS`).
40///
41/// Implementations of this trait are used by [`WriteXDR`](crate::WriteXDR)
42/// to serialize complex types.
43///
44pub trait Writer<F> {
45    // Callers must ensure bytes.len() <= u32::MAX; only debug-asserted.
46    #[doc(hidden)]
47    fn write_opaque_fixed(&mut self, bytes: &[u8]) -> WriteResult<()>;
48
49    // Writes `bytes` as the next piece of a fixed-length opaque, with no
50    // padding. A sequence of these must be ended by `write_opaque_padding`
51    // with the pieces' total length, which callers must ensure is
52    // <= u32::MAX; not checked.
53    #[doc(hidden)]
54    fn write_opaque_unpadded(&mut self, bytes: &[u8]) -> WriteResult<()>;
55
56    // Writes the padding that ends a fixed-length opaque of `len` bytes
57    // written with `write_opaque_unpadded`.
58    #[doc(hidden)]
59    fn write_opaque_padding(&mut self, len: usize) -> WriteResult<()>;
60
61    /// Writes a byte sequence of variable length.
62    fn write_opaque_variable(&mut self, bytes: &[u8]) -> WriteResult<()>;
63
64    /// Writes a signed 64-bit integer.
65    fn write_i64(&mut self, n: i64) -> WriteResult<()>;
66
67    /// Writes a signed 32-bit integer.
68    fn write_i32(&mut self, n: i32) -> WriteResult<()>;
69
70    /// Writes a signed 16-bit integer.
71    fn write_i16(&mut self, n: i16) -> WriteResult<()>;
72
73    /// Writes an unsigned 64-bit integer.
74    fn write_u64(&mut self, n: u64) -> WriteResult<()>;
75
76    /// Writes an unsigned 32-bit integer.
77    fn write_u32(&mut self, n: u32) -> WriteResult<()>;
78
79    /// Writes an unsigned 16-bit integer.
80    fn write_u16(&mut self, n: u16) -> WriteResult<()>;
81
82    /// Writes a boolean value.
83    fn write_bool(&mut self, b: bool) -> WriteResult<()>;
84
85    /// Writes a 32-bit IEEE 754 floating-point value.
86    fn write_f32(&mut self, n: f32) -> WriteResult<()>;
87
88    /// Writes a 64-bit IEEE 754 floating-point value.
89    fn write_f64(&mut self, n: f64) -> WriteResult<()>;
90}
xdrs/serialize/writer.rs

xdrs/serialize/
writer.rs
