thruput-xdrs 0.18.0

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

//! Writing XDR values to a serialization format.
//!
//! This module defines the [`Writer`] trait, which provides methods for
//! writing [XDR][RFC-4506] primitive types (as defined in RFC 4506)
//! to some underlying serialization format.
//! Implementations of this trait can be used with [`WriteXDR`](crate::WriteXDR)
//! to serialize complex types.
//!
//! [RFC-4506]: https://datatracker.ietf.org/doc/html/rfc4506

use crate::discrim::DiscriminantEncoding;

/// Errors that can occur when writing XDR data.
#[derive(Copy, Clone, Debug)]
pub enum WriteError {
    /// The writer has run out of space.
    SpaceExhausted,

    /// An array length is too large to be represented in XDR.
    InvalidArrayLength,
}

impl core::fmt::Display for WriteError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            WriteError::SpaceExhausted => write!(f, "space exhausted"),
            WriteError::InvalidArrayLength => write!(f, "invalid array length (too large)"),
        }
    }
}

impl core::error::Error for WriteError {}

/// A result type for writer operations.
pub type WriteResult<T = ()> = core::result::Result<T, WriteError>;

/// Something that can write XDR values to a serialization format.
///
/// This trait provides methods for writing XDR primitive types to an
/// underlying serialization format. The type parameter `F` represents
/// the format being written (e.g., `CXS` or `TXS`).
///
/// Implementations of this trait are used by [`WriteXDR`](crate::WriteXDR)
/// to serialize complex types.
///
pub trait Writer<F> {
    // Callers must ensure bytes.len() <= u32::MAX; only debug-asserted.
    #[doc(hidden)]
    fn write_opaque_fixed(&mut self, bytes: &[u8]) -> WriteResult<()>;

    // Writes `bytes` as the next piece of a fixed-length opaque, with no
    // padding. A sequence of these must be ended by `write_opaque_padding`
    // with the pieces' total length, which callers must ensure is
    // <= u32::MAX; not checked.
    #[doc(hidden)]
    fn write_opaque_unpadded(&mut self, bytes: &[u8]) -> WriteResult<()>;

    // Writes the padding that ends a fixed-length opaque of `len` bytes
    // written with `write_opaque_unpadded`.
    #[doc(hidden)]
    fn write_opaque_padding(&mut self, len: usize) -> WriteResult<()>;

    /// Writes a byte sequence of variable length.
    fn write_opaque_variable(&mut self, bytes: &[u8]) -> WriteResult<()>;

    /// Writes a signed 64-bit integer.
    fn write_i64(&mut self, n: i64) -> WriteResult<()>;

    /// Writes a signed 32-bit integer.
    fn write_i32(&mut self, n: i32) -> WriteResult<()>;

    /// Writes a signed 16-bit integer.
    fn write_i16(&mut self, n: i16) -> WriteResult<()>;

    /// Writes an unsigned 64-bit integer.
    fn write_u64(&mut self, n: u64) -> WriteResult<()>;

    /// Writes an unsigned 32-bit integer.
    fn write_u32(&mut self, n: u32) -> WriteResult<()>;

    /// Writes an unsigned 16-bit integer.
    fn write_u16(&mut self, n: u16) -> WriteResult<()>;

    /// Writes a boolean value.
    fn write_bool(&mut self, b: bool) -> WriteResult<()>;

    /// Writes a union's `i32` tag `d` as a discriminant encoded as
    /// `encoding`.
    fn write_discriminant(&mut self, d: i32, encoding: DiscriminantEncoding) -> WriteResult<()> {
        match encoding {
            DiscriminantEncoding::Signed => self.write_i32(d),
            DiscriminantEncoding::Unsigned => self.write_u32(d as u32),
            DiscriminantEncoding::Bool => self.write_bool(d != 0),
        }
    }

    /// Writes a 32-bit IEEE 754 floating-point value.
    fn write_f32(&mut self, n: f32) -> WriteResult<()>;

    /// Writes a 64-bit IEEE 754 floating-point value.
    fn write_f64(&mut self, n: f64) -> WriteResult<()>;
}