Skip to main content

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}