revelo_util/lib.rs
1//! Low-level primitives underpinning the
2//! [revelo](https://github.com/vbasky/revelo) media-metadata library — a
3//! Rust transliteration of [MediaArea](https://mediaarea.net/)'s
4//! [ZenLib](https://github.com/MediaArea/ZenLib) C++ support library.
5//!
6//! The goal is **behaviour parity** with the C++ types used by MediaInfoLib,
7//! not idiomatic Rust. Naming follows the upstream `ZenLib::` namespace
8//! convention so that transliterated parser code reads as close to the C++
9//! original as possible. All code is `#[deny(unsafe_code)]`.
10//!
11//! # Modules
12//!
13//! ## [`Ztring`] — Unicode string with multi-encoding I/O
14//!
15//! A transliteration of `ZenLib::Ztring`. Upstream uses `wchar_t` (UTF-16) on
16//! Windows and `char` (UTF-8) elsewhere; this port uses a single UTF-8
17//! `String` internally regardless of host. The full set of `From_*` / `To_*`
18//! conversions is preserved:
19//!
20//! - **Encoding constructors**: `From_UTF8`, `From_UTF8_bytes`,
21//! `From_ISO_8859_1`, `From_Local`, `From_UTF16`, `From_UTF16LE`,
22//! `From_UTF16BE`
23//! - **FourCC / short-code constructors**: `From_CC4`, `From_CC3`, `From_CC2`,
24//! `From_CC1`
25//! - **Numeric constructors** (with radix): `From_Number_int8u` …
26//! `From_Number_int128u`, `From_Number_int8s` … `From_Number_int128s`,
27//! `From_Number_float32`, `From_Number_float64`
28//! - **Extraction**: `To_UTF8`, `To_Local`, `To_int8u` … `To_int64u`,
29//! `To_int8s` … (with radix), `as_str`, `into_string`
30//!
31//! `Ztring` implements `Clone`, `Debug`, `Default`, `PartialEq`, `Eq`,
32//! `PartialOrd`, `Ord`, and `Hash`. It also implements `From<&str>` and
33//! `From<String>` for ergonomic construction.
34//!
35//! ## [`BitStream`] — MSB-first bit reader
36//!
37//! A transliteration of `ZenLib::BitStream`. Reads up to 32 bits at a time
38//! from a byte slice in MSB-first order. Key API:
39//!
40//! - `BitStream::new(buffer: &[u8])` — attach to a slice
41//! - `get(how_many: usize) -> u32` — read the next N bits; returns 0 on
42//! underrun and sets an internal `buffer_under_run` flag
43//! - `attach(&mut self, buffer: &[u8])` — re-attach to a new slice
44//! - Bookmark / peek support and `Byte_Align` for partial-byte skipping
45//!
46//! ## [`types`] — ZenLib integer and float aliases
47//!
48//! Fixed-width type aliases that match `ZenLib/Conf.h` verbatim so
49//! transliterated code compiles without renaming:
50//!
51//! `Int8u`, `Int16u`, `Int32u`, `Int64u`, `Int128u` (unsigned),
52//! `Int8s`, `Int16s`, `Int32s`, `Int64s`, `Int128s` (signed),
53//! `Float32`, `Float64`, `Float80` (= `f64`), `Char`, and the sentinel
54//! constant `ERROR` (= `usize::MAX`).
55//!
56//! # Example
57//!
58//! ```no_run
59//! use revelo_util::{BitStream, Ztring};
60//!
61//! // Build a Ztring from a raw FourCC u32
62//! let z = Ztring::From_CC4(0x6672_6565); // "free"
63//! assert_eq!(z.as_str(), "free");
64//!
65//! // Read individual bits from a byte buffer
66//! let buf = [0b1010_0000u8, 0b0000_0001u8];
67//! let mut bs = BitStream::new(&buf);
68//! assert_eq!(bs.get(4), 0b1010);
69//! assert_eq!(bs.get(4), 0b0000);
70//! ```
71
72#![allow(non_snake_case)]
73#![deny(unsafe_code)]
74
75pub mod bitstream;
76pub mod types;
77pub mod ztring;
78
79pub use bitstream::BitStream;
80pub use types::*;
81pub use ztring::Ztring;