Skip to main content

rm2k/
wire.rs

1//! The LCF wire codec: compressed integers, fixed-width primitives, file magics.
2//!
3//! Pure functions over byte slices, no cursor state; [`Cursor`](crate::cursor::Cursor) adds
4//! position tracking and diagnostics. Allocation-free, no `unsafe`.
5//!
6//! # Compressed integers
7//!
8//! LCF varints are **big-endian** base-128 with an MSB continuation bit, unlike protobuf's LEB128;
9//! an off-the-shelf varint crate decodes them wrong.
10//!
11//! A well-formed encoding is at most 5 bytes. Longer ones are malformed, but their bytes must still
12//! be consumed to keep the cursor in sync: [`decode_varint`] reads until a byte with the high bit
13//! clear, decodes to `0`, and sets `overflow` so the caller can record a
14//! [`DiagKind::BadVarint`](crate::diag::DiagKind::BadVarint). Accumulation is in a 32-bit register
15//! (`value = (value << 7) | (byte & 0x7F)`), so a maximal 5-byte encoding wraps.
16
17use crate::sink::Sink;
18
19pub const LDB_HEADER: &[u8] = b"LcfDataBase";
20pub const LMU_HEADER: &[u8] = b"LcfMapUnit";
21pub const LMT_HEADER: &[u8] = b"LcfMapTree";
22pub const LSD_HEADER: &[u8] = b"LcfSaveData";
23
24/// Most bytes a 32-bit compressed integer may occupy.
25pub const MAX_VARINT_LEN: usize = 5;
26/// Most bytes a 64-bit compressed integer may occupy.
27pub const MAX_VARINT64_LEN: usize = 10;
28
29/// A decoded compressed integer.
30#[derive(Clone, Copy, Debug, Eq, PartialEq)]
31pub struct Varint {
32    /// The value, already zeroed when `overflow` is set.
33    pub value: u32,
34    /// Bytes consumed, including the over-long tail when `overflow` is set.
35    pub consumed: usize,
36    /// The encoding ran past the byte cap; liblcf substitutes `0`.
37    pub overflow: bool,
38}
39
40/// Decode a 32-bit compressed integer from the front of `buf`.
41///
42/// Returns `None` when `buf` ends before a terminating byte (high bit clear) is found. liblcf
43/// treats that as `0` at EOF; callers should do the same after recording a diagnostic.
44#[must_use]
45pub fn decode_varint(buf: &[u8]) -> Option<Varint> {
46    let mut value: u32 = 0;
47    let mut consumed = 0usize;
48
49    loop {
50        let byte = *buf.get(consumed)?;
51        consumed += 1;
52        value = (value << 7) | u32::from(byte & 0x7F);
53        if byte & 0x80 == 0 {
54            break;
55        }
56    }
57
58    let overflow = consumed > MAX_VARINT_LEN;
59    Some(Varint {
60        value: if overflow { 0 } else { value },
61        consumed,
62        overflow,
63    })
64}
65
66/// A decoded 64-bit compressed integer.
67#[derive(Clone, Copy, Debug, Eq, PartialEq)]
68pub struct Varint64 {
69    /// The value, already zeroed when `overflow` is set.
70    pub value: u64,
71    /// Bytes consumed, including the over-long tail when `overflow` is set.
72    pub consumed: usize,
73    /// The encoding ran past the byte cap; liblcf substitutes `0`.
74    pub overflow: bool,
75}
76
77/// Decode a 64-bit compressed integer from the front of `buf`.
78///
79/// Same as [`decode_varint`] with a 10-byte cap (`LcfReader::ReadUInt64`,
80/// `src/reader_lcf.cpp:106`). Used only by the sparse string-vector encoding, where a value above
81/// `u32::MAX` is a run-length gap marker, not a length (`src/dbstring_struct.cpp:93`).
82#[must_use]
83pub fn decode_varint64(buf: &[u8]) -> Option<Varint64> {
84    let mut value: u64 = 0;
85    let mut consumed = 0usize;
86
87    loop {
88        let byte = *buf.get(consumed)?;
89        consumed += 1;
90        value = (value << 7) | u64::from(byte & 0x7F);
91        if byte & 0x80 == 0 {
92            break;
93        }
94    }
95
96    let overflow = consumed > MAX_VARINT64_LEN;
97    Some(Varint64 {
98        value: if overflow { 0 } else { value },
99        consumed,
100        overflow,
101    })
102}
103
104/// Encoded length in bytes of `value` as a compressed integer.
105///
106/// Mirrors `LcfReader::IntSize` (`src/reader_lcf.cpp:330`): `ceil(bits / 7)`, minimum 1.
107#[must_use]
108pub const fn varint_len(value: u32) -> u32 {
109    let mut x = value;
110    let mut result = 0u32;
111    loop {
112        x >>= 7;
113        result += 1;
114        if x == 0 {
115            return result;
116        }
117    }
118}
119
120/// Encoded length in bytes of `value` as a 64-bit compressed integer.
121#[must_use]
122pub const fn varint64_len(value: u64) -> u32 {
123    let mut x = value;
124    let mut result = 0u32;
125    loop {
126        x >>= 7;
127        result += 1;
128        if x == 0 {
129            return result;
130        }
131    }
132}
133
134/// Encode `value` into `out`, returning how many bytes were written.
135///
136/// Mirrors `LcfWriter::WriteInt` (`src/writer_lcf.cpp:50`), which emits 7-bit groups from bit 28
137/// downwards - so it never writes more than 5 bytes and silently drops anything above bit 34.
138#[must_use]
139pub fn encode_varint(value: u32, out: &mut [u8; MAX_VARINT_LEN]) -> usize {
140    let mut len = 0usize;
141    let mut shift: i32 = 28;
142    while shift >= 0 {
143        if value >= (1u32 << shift) || shift == 0 {
144            let group = ((value >> shift) & 0x7F) as u8;
145            out[len] = if shift > 0 { group | 0x80 } else { group };
146            len += 1;
147        }
148        shift -= 7;
149    }
150    len
151}
152
153/// Encode `value` as a 64-bit compressed integer into `out`, returning bytes written.
154#[must_use]
155pub fn encode_varint64(value: u64, out: &mut [u8; MAX_VARINT64_LEN]) -> usize {
156    let mut len = 0usize;
157    let mut shift: i32 = 56;
158    while shift >= 0 {
159        if value >= (1u64 << shift) || shift == 0 {
160            let group = ((value >> shift) & 0x7F) as u8;
161            out[len] = if shift > 0 { group | 0x80 } else { group };
162            len += 1;
163        }
164        shift -= 7;
165    }
166    len
167}
168
169/// Write `value` to `sink` as a compressed integer.
170///
171/// # Errors
172/// Propagates the sink's error. Infallible for `Vec<u8>`.
173#[inline]
174pub fn write_varint<S: Sink>(sink: &mut S, value: u32) -> Result<(), S::Error> {
175    let mut buf = [0u8; MAX_VARINT_LEN];
176    let len = encode_varint(value, &mut buf);
177    sink.write(&buf[..len])
178}
179
180/// Write `value` to `sink` as a 64-bit compressed integer.
181///
182/// # Errors
183/// Propagates the sink's error. Infallible for `Vec<u8>`.
184#[inline]
185pub fn write_varint64<S: Sink>(sink: &mut S, value: u64) -> Result<(), S::Error> {
186    let mut buf = [0u8; MAX_VARINT64_LEN];
187    let len = encode_varint64(value, &mut buf);
188    sink.write(&buf[..len])
189}
190
191/// Read a little-endian `i16` from the front of `buf`.
192#[must_use]
193#[inline]
194pub fn read_i16_le(buf: &[u8]) -> Option<i16> {
195    buf.get(..2).map(|b| i16::from_le_bytes([b[0], b[1]]))
196}
197
198/// Read a little-endian `u32` from the front of `buf`.
199#[must_use]
200#[inline]
201pub fn read_u32_le(buf: &[u8]) -> Option<u32> {
202    buf.get(..4).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
203}
204
205/// Read a little-endian `i32` from the front of `buf`.
206///
207/// Raw form used inside packed arrays. A bare `Int32` **field** is a compressed integer instead
208/// ([`decode_varint`]). liblcf's comment on `LcfWriter::Write<int32_t>(&Vec<int32_t>)` says
209/// otherwise, and is wrong (`src/writer_lcf.cpp:101`).
210#[must_use]
211#[inline]
212pub fn read_i32_le(buf: &[u8]) -> Option<i32> {
213    buf.get(..4).map(|b| i32::from_le_bytes([b[0], b[1], b[2], b[3]]))
214}
215
216/// Read a little-endian `f64` from the front of `buf`.
217#[must_use]
218#[inline]
219pub fn read_f64_le(buf: &[u8]) -> Option<f64> {
220    buf.get(..8)
221        .map(|b| f64::from_le_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]))
222}