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}