zerodds_cdr/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 ZeroDDS Contributors
3//! Crate `zerodds-cdr`. Safety classification: **SAFE**.
4//!
5//! XCDR1/XCDR2 encoder/decoder + KeyHash + PL_CDR1 member codec for
6//! `@mutable` structured data — fully implements the OMG XTypes 1.3 §7.4
7//! wire format.
8//!
9//! ## Spec
10//!
11//! - **OMG XTypes 1.3** §7.4 (Wire-Encoding) inkl. §7.4.1.2 (PL_CDR1),
12//! §7.4.2 (Plain CDR2 / Delimited CDR2 / PL_CDR2), §7.4.4 (Composite
13//! Types: String/Sequence/Array/Optional), §7.4.5 (Struct-Extensibility:
14//! final/appendable/mutable).
15//! - **OMG XTypes 1.3** §7.6.8 KeyHash (CDR_BE Key-Holder + MD5-Fallback).
16//! - **DDSI-RTPS 2.5** §10 Wire-Encapsulation (RepresentationIdentifier).
17//!
18//! ## Layer position
19//!
20//! Layer 1 — primitives. Direct dependents: `zerodds-types`, `zerodds-qos`,
21//! `zerodds-rtps`, `zerodds-discovery`, `zerodds-dcps`, `zerodds-idl-rust`,
22//! `dds-corba-{ior,iiop,giop,csiv2,cosnaming,rust}`, `zerodds-ts-wasm`.
23//!
24//! ## Public API (as of 1.0.0-rc.1)
25//!
26//! - [`BufferReader`] / [`BufferWriter`] — alignment-tracking byte-level
27//! I/O primitives.
28//! - [`Endianness`] — little/big-endian marker.
29//! - [`CdrEncode`] / [`CdrDecode`] — trait family for serializable
30//! types; implementations for all spec primitives plus composite
31//! types (String, `Vec<T>`, `[T; N]`, `Option<T>`) in the `composite` module.
32//! - [`EncodeError`] / [`DecodeError`] — typed errors with offset
33//! information.
34//! - [`fixed::Fixed`] — IDL `fixed<P,S>` decimal type with BCD encoding.
35//! - [`struct_enc`] — XCDR2 extensibility encoder (`encode_final`,
36//! `encode_appendable`, [`struct_enc::MutableStructEncoder`] +
37//! `read_mutable_member`).
38//! - [`xcdr1`] — XTypes-1.3-conformant PL_CDR1 member codec
39//! (`encode_pl_cdr1_member`, `read_pl_cdr1_member`,
40//! `read_all_pl_cdr1_members`, `write_pl_cdr1_sentinel`).
41//! - [`key_hash::compute_key_hash`] / [`PlainCdr2BeKeyHolder`] /
42//! [`KEY_HASH_LEN`] — XTypes 1.3 §7.6.8 KeyHash with MD5 fallback.
43//!
44//! ## Example
45//!
46//! ```rust
47//! use zerodds_cdr::{BufferWriter, BufferReader, Endianness, CdrEncode, CdrDecode};
48//!
49//! let mut w = BufferWriter::new(Endianness::Little);
50//! 42u32.encode(&mut w).unwrap();
51//! let bytes = w.into_bytes();
52//!
53//! let mut r = BufferReader::new(&bytes, Endianness::Little);
54//! assert_eq!(u32::decode(&mut r).unwrap(), 42);
55//! ```
56
57#![no_std]
58#![forbid(unsafe_code)]
59#![warn(missing_docs)]
60
61#[cfg(feature = "alloc")]
62extern crate alloc;
63
64#[cfg(feature = "std")]
65extern crate std;
66
67pub mod buffer;
68#[cfg(feature = "alloc")]
69pub mod composite;
70pub mod encode;
71pub mod endianness;
72pub mod error;
73#[cfg(feature = "alloc")]
74pub mod fixed;
75#[cfg(feature = "alloc")]
76pub mod key_hash;
77#[cfg(feature = "alloc")]
78pub mod struct_enc;
79#[cfg(feature = "alloc")]
80pub mod type_code;
81#[cfg(feature = "alloc")]
82pub mod xcdr1;
83
84#[cfg(feature = "serde-bridge")]
85pub mod serde_bridge;
86
87pub use endianness::Endianness;
88pub use error::{DecodeError, EncodeError};
89
90#[cfg(feature = "alloc")]
91pub use key_hash::{KEY_HASH_LEN, PlainCdr2BeKeyHolder, compute_key_hash};
92
93pub use buffer::BufferReader;
94#[cfg(feature = "alloc")]
95pub use buffer::BufferWriter;
96
97pub use encode::{CdrDecode, CdrEncode};
98
99#[cfg(feature = "alloc")]
100pub use composite::{WChar, WString, corba_wstring_bom, set_corba_wstring_bom};
101
102#[cfg(feature = "alloc")]
103pub use composite::{AnyValue, CorbaAny};
104
105#[cfg(feature = "alloc")]
106pub use type_code::TypeCode;