json_slabs/types.rs
1//! Types related to the JSLB (JsonSlabs) file format.
2
3use std::fmt;
4
5/// Magic bytes at the start of every `.jslb` file.
6pub const MAGIC: [u8; 8] = [0xDC, 0xDF, 0x4A, 0x53, 0x4C, 0x42, 0x01, 0x00];
7
8/// On-disk format version this crate reads and writes.
9pub const VERSION: u32 = 1;
10
11/// The object key that marks a slab reference in a JSON slab.
12///
13/// A JSON object of the form `{ "$s": <slab-index> }` — and no other
14/// members — is a placeholder for the contents of another slab. See
15/// [`SlabPlaceholder`].
16pub const SLAB_REF_KEY: &str = "$s";
17
18/// Size of the fixed file header in bytes.
19pub const FIXED_HEADER_SIZE: usize = 20;
20
21/// Size of one slab-table entry in bytes. These entries immediately follow
22/// the file header.
23pub const SLAB_TABLE_ENTRY_SIZE: usize = 12;
24
25/// The type of a slab, as stored in the file.
26///
27/// All numbers are stored in little-endian byte order.
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29#[repr(u32)]
30pub enum SlabType {
31 /// An array of signed 8-bit integers.
32 Int8 = 0x00,
33 /// An array of unsigned 8-bit integers.
34 Uint8 = 0x01,
35 /// An array of signed 16-bit integers, little-endian on disk.
36 Int16 = 0x02,
37 /// An array of unsigned 16-bit integers, little-endian on disk.
38 Uint16 = 0x03,
39 /// An array of signed 32-bit integers, little-endian on disk.
40 Int32 = 0x04,
41 /// An array of unsigned 32-bit integers, little-endian on disk.
42 Uint32 = 0x05,
43 /// An array of iEEE 754 binary32 floats, little-endian on disk.
44 Float32 = 0x06,
45 /// An array of iEEE 754 binary64 floats, little-endian on disk.
46 Float64 = 0x07,
47 /// An array of signed 64-bit integers, little-endian on disk.
48 Int64 = 0x08,
49 /// An array of unsigned 64-bit integers, little-endian on disk.
50 Uint64 = 0x09,
51 /// UTF-8 JSON bytes. Used both for the root skeleton slab and for
52 /// sub-JSON slabs referenced from the skeleton.
53 Json = 0x0a,
54}
55
56impl SlabType {
57 /// Size in bytes of a single element of this slab type.
58 pub fn element_size(self) -> usize {
59 match self {
60 Self::Int16 | Self::Uint16 => 2,
61 Self::Int32 | Self::Uint32 | Self::Float32 => 4,
62 Self::Float64 | Self::Int64 | Self::Uint64 => 8,
63 _ => 1,
64 }
65 }
66
67 /// Short human-readable name (`"i32"`, `"f64"`, `"json"`, ...).
68 /// Used by [`fmt::Display`].
69 pub fn name(self) -> &'static str {
70 match self {
71 Self::Int8 => "i8",
72 Self::Uint8 => "u8",
73 Self::Int16 => "i16",
74 Self::Uint16 => "u16",
75 Self::Int32 => "i32",
76 Self::Uint32 => "u32",
77 Self::Float32 => "f32",
78 Self::Float64 => "f64",
79 Self::Int64 => "i64",
80 Self::Uint64 => "u64",
81 Self::Json => "json",
82 }
83 }
84}
85
86impl fmt::Display for SlabType {
87 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
88 f.write_str(self.name())
89 }
90}
91
92impl TryFrom<u32> for SlabType {
93 type Error = u32;
94 fn try_from(v: u32) -> Result<Self, Self::Error> {
95 Ok(match v {
96 0x00 => Self::Int8,
97 0x01 => Self::Uint8,
98 0x02 => Self::Int16,
99 0x03 => Self::Uint16,
100 0x04 => Self::Int32,
101 0x05 => Self::Uint32,
102 0x06 => Self::Float32,
103 0x07 => Self::Float64,
104 0x08 => Self::Int64,
105 0x09 => Self::Uint64,
106 0x0a => Self::Json,
107 _ => return Err(v),
108 })
109 }
110}
111
112/// A reference to a slice of slab bytes, annotated with the slab type.
113///
114/// Returned by [`ParsedFile::slab_at`](crate::ParsedFile::slab_at) and friends.
115/// Multi-byte integer/float slabs are always little-endian on disk.
116#[derive(Debug, Clone, Copy)]
117pub struct SlabBytes<'a> {
118 /// The element type of `bytes`.
119 pub slab_type: SlabType,
120 /// Borrowed slab bytes. Length is a multiple of
121 /// `slab_type.element_size()`.
122 pub bytes: &'a [u8],
123}
124
125impl<'a> SlabBytes<'a> {
126 /// Number of typed elements in the slab, i.e.
127 /// `bytes.len() / slab_type.element_size()`.
128 pub fn element_count(&self) -> usize {
129 self.bytes.len() / self.slab_type.element_size()
130 }
131}
132
133/// Numeric primitive that can appear as the element type of a
134/// typed-array slab, implemented by `i8`, `u8`, `i16`, etc.
135///
136/// Used as the trait bound for `T` in [`ParsedFile::read::<T>`](crate::ParsedFile::read)
137/// and the various [`Builder::add_slab`](crate::Builder::add_slab) methods.
138///
139/// This trait is sealed, because we want to be able to write a slice
140/// of primitives to the file by reinterpreting the slice of primitives
141/// as a slice of bytes (which works at least on little-endian machines;
142/// the file format always uses little-endian). We use a sealed (and
143/// unsafe) marker trait to indicate that this reinterpretion is sound.
144pub trait SlabPrimitive: Copy + sealed::Sealed {
145 /// The [`SlabType`] tag for this Rust primitive on disk.
146 const SLAB_TYPE: SlabType;
147 /// Fixed-size byte array type produced by [`to_le_bytes`](Self::to_le_bytes).
148 type LeBytes: AsRef<[u8]>;
149 /// Encode a single element as its little-endian byte representation.
150 fn to_le_bytes(self) -> Self::LeBytes;
151 /// Decode a single element from its little-endian byte
152 /// representation. `bytes` must be exactly
153 /// `SLAB_TYPE.element_size()` long.
154 fn from_le_bytes(bytes: &[u8]) -> Self;
155}
156
157mod sealed {
158 /// This makes it so that [`SlabPrimitive`](super::SlabPrimitive)
159 /// cannot be implemented outside this crate.
160 ///
161 /// This trait also guarantees the invariant that the `unsafe` block
162 /// in `write_slice_le` relies on when it reinterprets `&[Self]` as
163 /// `&[u8]`.
164 ///
165 /// # Safety
166 ///
167 /// `Self` must be valid to view as `size_of::<Self>()` initialized
168 /// bytes: no padding, no uninhabited or niche-restricted values, no
169 /// interior mutability, and no pointers (whose bytes are not
170 /// meaningful on disk). In practice: only the built-in integer and
171 /// float primitives qualify.
172 pub unsafe trait Sealed {}
173}
174
175// SAFETY for all of the following: these are the built-in integer and
176// float primitives. Each is a fixed-size scalar with no padding, no
177// invalid bit patterns, and no interior mutability.
178unsafe impl sealed::Sealed for u8 {}
179unsafe impl sealed::Sealed for i8 {}
180unsafe impl sealed::Sealed for u16 {}
181unsafe impl sealed::Sealed for i16 {}
182unsafe impl sealed::Sealed for u32 {}
183unsafe impl sealed::Sealed for i32 {}
184unsafe impl sealed::Sealed for u64 {}
185unsafe impl sealed::Sealed for i64 {}
186unsafe impl sealed::Sealed for f32 {}
187unsafe impl sealed::Sealed for f64 {}
188
189impl SlabPrimitive for u8 {
190 const SLAB_TYPE: SlabType = SlabType::Uint8;
191 type LeBytes = [u8; 1];
192 fn to_le_bytes(self) -> [u8; 1] {
193 [self]
194 }
195 fn from_le_bytes(bytes: &[u8]) -> Self {
196 bytes[0]
197 }
198}
199impl SlabPrimitive for i8 {
200 const SLAB_TYPE: SlabType = SlabType::Int8;
201 type LeBytes = [u8; 1];
202 fn to_le_bytes(self) -> [u8; 1] {
203 [self as u8]
204 }
205 fn from_le_bytes(bytes: &[u8]) -> Self {
206 bytes[0] as i8
207 }
208}
209
210macro_rules! impl_slab_primitive {
211 ($t:ty, $tag:ident, $n:literal) => {
212 impl SlabPrimitive for $t {
213 const SLAB_TYPE: SlabType = SlabType::$tag;
214 type LeBytes = [u8; $n];
215 fn to_le_bytes(self) -> [u8; $n] {
216 <$t>::to_le_bytes(self)
217 }
218 fn from_le_bytes(bytes: &[u8]) -> Self {
219 <$t>::from_le_bytes(bytes.try_into().unwrap())
220 }
221 }
222 };
223}
224
225impl_slab_primitive!(u16, Uint16, 2);
226impl_slab_primitive!(i16, Int16, 2);
227impl_slab_primitive!(u32, Uint32, 4);
228impl_slab_primitive!(i32, Int32, 4);
229impl_slab_primitive!(u64, Uint64, 8);
230impl_slab_primitive!(i64, Int64, 8);
231impl_slab_primitive!(f32, Float32, 4);
232impl_slab_primitive!(f64, Float64, 8);
233
234/// Decoded form of the 20-byte fixed header.
235#[derive(Debug, Clone, Copy)]
236pub struct Header {
237 /// Total number of slabs in the file (including the root JSON slab).
238 pub slab_count: usize,
239 /// Slab table index of the root JSON skeleton slab. Guaranteed to be
240 /// less than `slab_count` when produced by [`Header::parse`].
241 pub root_json_slab_index: usize,
242}
243
244/// One slab-table entry, decoded but not yet bound to file/buffer data.
245#[derive(Debug, Clone, Copy)]
246pub struct SlabTableEntry {
247 /// The on-disk type tag of the slab.
248 pub slab_type: SlabType,
249 /// Byte offset from the start of the file to the slab's first byte.
250 pub start_offset: u64,
251 /// Slab length in bytes. Guaranteed to be a multiple of
252 /// `slab_type.element_size()` when produced by [`SlabTableEntry::parse`].
253 pub byte_length: u64,
254}
255
256/// A reference to a slab by its index in the file's slab table.
257///
258/// Returned from [`Builder::add_slab`](crate::Builder::add_slab) when building a file,
259/// and accepted by [`ParsedFile::read`](crate::ParsedFile::read) and friends when
260/// reading one back. The inner `usize` is the raw slab index.
261///
262/// This type implements [`fmt::Display`]:
263/// - `format!("{}", SlabPlaceholder(2))` produces `2`
264/// - `format!("{:#}, SlabPlaceholder(2))` produces `{"$s":2}`
265#[derive(Debug, Clone, Copy, PartialEq, Eq)]
266pub struct SlabPlaceholder(pub usize);
267
268impl SlabPlaceholder {
269 /// The underlying slab table index.
270 pub fn index(self) -> usize {
271 self.0
272 }
273}
274
275impl fmt::Display for SlabPlaceholder {
276 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
277 if f.alternate() {
278 write!(f, r#"{{"{SLAB_REF_KEY}":{}}}"#, self.0)
279 } else {
280 self.0.fmt(f)
281 }
282 }
283}