matter_codec/lib.rs
1//! Matter TLV (Tag-Length-Value) encoding and decoding.
2//!
3//! # Scope
4//!
5//! The whole of Matter Core Specification §A.2: all scalar element types,
6//! UTF-8 and octet strings, every tag form (anonymous, context, common
7//! profile, implicit profile, fully-qualified), and containers (structure,
8//! array, list) with a 32-level depth limit. [`TlvWriter`] always picks the
9//! narrowest legal encoding for a tag or a length.
10//!
11//! [`TlvReader`] can be driven three ways: element-at-a-time with
12//! [`next`](TlvReader::next), zero-copy with
13//! [`next_ref`](TlvReader::next_ref) (yielding [`ElementRef`] /
14//! [`ValueRef`], which borrow strings and octet strings straight out of the
15//! input), or as a whole tree with [`read_value`](TlvReader::read_value).
16//! Containers you do not care about can be skipped outright — see
17//! [`skip_container`](TlvReader::skip_container), or
18//! [`skip_container_span`](TlvReader::skip_container_span) when you want the
19//! raw bytes back to forward verbatim.
20//!
21//! Verified by spec test vectors, a `proptest` round-trip property, and a
22//! `cargo-fuzz` target.
23//!
24//! # Usage
25//!
26//! ```
27//! use matter_codec::{Tag, TlvWriter};
28//! # fn main() -> Result<(), matter_codec::Error> {
29//! let mut bytes = Vec::new();
30//! let mut writer = TlvWriter::new(&mut bytes);
31//! writer.put_bool(Tag::Anonymous, true)?;
32//! assert_eq!(bytes, [0x09]);
33//! # Ok(())
34//! # }
35//! ```
36
37#![forbid(unsafe_code)]
38
39mod element_type;
40mod tag_control;
41
42pub mod error;
43pub mod reader;
44pub mod tag;
45pub mod value;
46pub mod writer;
47
48pub use error::{Error, Result};
49pub use reader::{ContainerKind, Element, ElementRef, ElementSpan, TlvReader, MAX_DEPTH};
50pub use tag::Tag;
51pub use value::{Value, ValueRef};
52pub use writer::TlvWriter;
53
54/// Compile-checks the Rust examples in this crate's `README.md`.
55///
56/// `#[cfg(doctest)]` means the item exists only while rustdoc is collecting
57/// doctests, so the README is compiled by `cargo test --doc` without being
58/// duplicated into the rendered crate docs.
59#[cfg(doctest)]
60#[doc = include_str!("../README.md")]
61struct ReadmeDoctests;