Skip to main content

unityrs_core/
stream.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/streams/EndianBinaryReader.py. See THIRD_PARTY_LICENSES.
2//! A bounded reader over a byte slice with the semantics of UnityPy's
3//! `EndianBinaryReader`: the memory reader, `EndianBinaryReader_Memoryview`
4//! (`streams/EndianBinaryReader.py:231-284`), or the stream reader,
5//! `EndianBinaryReader_Streamable` (`:287-324`), which UnityPy reads a file
6//! it loads from a path with ([`ReaderKind`]; `kind`'s module docs list
7//! what it reads that way and its rules).
8//!
9//! Container and metadata parsers read through it; the value walker has its
10//! own cursor (UnityPyBoost's bounds rule differs, plan section 3.10), which
11//! takes the same [`ReaderKind`]. No method panics: every read UnityPy
12//! refuses is an [`Error::OutOfBounds`], or the stream reader's
13//! [`StreamRefusal`] as an [`Error::Malformed`].
14//!
15//! **Positions are signed** (plan section 3.3). A Python `Position` is an
16//! unbounded integer that UnityPy moves with plain arithmetic, so on the
17//! memory reader it can go negative (a negative `node_count` in
18//! `parse_blob`, `file_size - metadata_size` below format 9, `Length -
19//! compressedSize` for blocks-info at the end, a negative `TypelessData`
20//! length on the pure-Python path) or past the end, and the reads after it
21//! go on with Python's rules, which this module's helpers implement once
22//! and an oracle fixture pins (`tests/fixtures/scaffold/reader.json`, from
23//! `tools/fixtures/scaffold.py`):
24//! - [`py_read`]: `read(n)`, a Python slice (negative indexes count from the
25//!   end; a reversed range is empty); the position moves by `n` whatever
26//!   the slice held;
27//! - [`py_unpack_from`]: every fixed-width read of 2, 4 or 8 bytes is
28//!   `struct.unpack_from(view, Position)` (`:340-343`): a negative offset
29//!   counts from the end, and the read must fit;
30//! - one-byte reads (`read_u8`, `read_i8`, `read_bool`) are
31//!   `unpack(fmt, read(1))` (`:93-97`, `:126-127`): the slice of [`py_read`] must hold
32//!   exactly one byte, and the position has moved by 1 even when it raises
33//!   (at `-1`, `view[-1:0]` is empty);
34//! - [`py_align`]: `align_stream`, Python's floor modulo (`-7` aligns to `-4`);
35//! - [`py_string_to_null`]: `re.search` clamps its start and end into the
36//!   buffer, a hit sets the absolute position after the NUL, and a miss reads
37//!   `max_length` bytes as a slice unless `pos + max_length >= len`.
38//!
39//! The stream reader's position is never negative and stops at the end; the
40//! same fixture pins its rules (its `stream_` cases), which [`ReaderKind`]
41//! implements.
42//!
43//! Owner: package C. The free functions and [`Reader::read_i32_array`] are
44//! the scaffold's (implemented).
45
46mod kind;
47
48use std::ops::Range;
49use std::sync::Arc;
50
51use crate::error::Error;
52use crate::limits::{Meter, MeteredVec};
53
54pub use kind::{ReaderKind, STREAM_READER, StreamRefusal};
55
56/// Byte order of a reader or a file.
57#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
58pub enum Endian {
59    /// `<`
60    Little,
61    /// `>`
62    Big,
63}
64
65/// `read_string_to_null`'s default `max_length` (`EndianBinaryReader.py:275`).
66/// Within the window the string runs to its NUL. With no NUL in the window it
67/// is cut at the window when more bytes follow, and raises otherwise.
68pub const STRING_TO_NULL_WINDOW: usize = 32_767;
69
70/// The memoryview reader's `read(size)` at `pos` over `len` bytes
71/// (`streams/EndianBinaryReader.py:249-256`), with Python's arithmetic: size
72/// 0 reads nothing and leaves the position; size -1 reads to the end; any
73/// other size is the slice `view[pos : pos + size]`, where a negative index
74/// counts from the end, indexes clamp to `0..=len` and a reversed range is
75/// empty. Returns the byte range and the new position, `pos + size` (`len`
76/// for -1), which may be negative or past the end, as a Python `Position` can
77/// be. A bundle entry (`File.py:78-81`), `parse_blob`'s node area and string
78/// buffer, and the pure-Python reader's `TypelessData` all read this way
79/// (plan section 3.6). Implemented by the scaffold.
80#[must_use]
81pub fn py_read(len: usize, pos: i128, size: i64) -> (Range<usize>, i128) {
82    if size == 0 {
83        return (0..0, pos);
84    }
85    let l = i128::try_from(len).unwrap_or(i128::MAX);
86    let size = if size == -1 {
87        l.saturating_sub(pos)
88    } else {
89        i128::from(size)
90    };
91    let stop = pos.saturating_add(size);
92    let index = |i: i128| -> usize {
93        let i = if i < 0 { i.saturating_add(l) } else { i };
94        usize::try_from(i.clamp(0, l)).unwrap_or(0)
95    };
96    let start = index(pos);
97    let end = index(stop).max(start);
98    (start..end, stop)
99}
100
101/// `struct.unpack_from(fmt, view, pos)` for a format of `n` bytes over `len`
102/// bytes (`CPython`'s `s_unpack_from`): the start index of the bytes it reads,
103/// or `None` where it raises `struct.error`. A negative `pos` counts from the
104/// end and must leave the whole read before the end (`pos + n <= 0`) and
105/// inside the buffer (`pos + len >= 0`). Every fixed-width read of 2, 4 or 8
106/// bytes UnityPy's memoryview reader makes through its own methods
107/// (`reader.read_int()`) takes this path, then moves the position by `n`
108/// (only on success). The pure-Python typetree reader's primitive nodes do
109/// not: they read through the base class's `unpack(fmt, read(n))`
110/// (`walk::python`, plan 3.10). Implemented by the scaffold.
111#[must_use]
112pub fn py_unpack_from(len: usize, pos: i128, n: usize) -> Option<usize> {
113    let l = i128::try_from(len).ok()?;
114    let n = i128::try_from(n).ok()?;
115    let mut offset = pos;
116    if offset < 0 {
117        if offset.saturating_add(n) > 0 || offset.saturating_add(l) < 0 {
118            return None;
119        }
120        offset = offset.saturating_add(l);
121    }
122    if l.saturating_sub(offset) < n {
123        return None;
124    }
125    usize::try_from(offset).ok()
126}
127
128/// `align_stream(n)` (`streams/EndianBinaryReader.py:155-156`):
129/// `pos + (n - pos % n) % n` with Python's floor modulo, so a negative
130/// position aligns towards zero (`-7` to `-4` for `n = 4`). `n` 0 leaves the
131/// position (Python would raise; no caller passes 0). Implemented by the scaffold.
132#[must_use]
133pub fn py_align(pos: i128, n: u32) -> i128 {
134    let n = i128::from(n);
135    if n == 0 {
136        return pos;
137    }
138    pos.saturating_add((n - pos.rem_euclid(n)) % n)
139}
140
141/// `read_string_to_null(max_length)` of the memoryview reader
142/// (`streams/EndianBinaryReader.py:275-284`) at `pos` over `data`: the
143/// string's byte range and the new position, or `None` where it raises
144/// ("String not terminated"). `re.search(view, pos, pos + max_length)` clamps
145/// both bounds into `0..=len` (`py_string_window`), so a negative start
146/// searches from 0; a hit returns the bytes up to the first NUL in the window
147/// and sets the position after that NUL (an absolute index). With no NUL in
148/// the window it raises when `pos + max_length >= len`, and otherwise returns
149/// `read(max_length)`, a slice from `pos` that may hold a NUL or nothing at
150/// all (`py_string_to_null_found`, which a caller that indexed the buffer's
151/// NULs answers with). Implemented by the scaffold.
152#[must_use]
153pub fn py_string_to_null(
154    data: &[u8],
155    pos: i128,
156    max_length: usize,
157) -> Option<(Range<usize>, i128)> {
158    let window = py_string_window(data.len(), pos, max_length);
159    let nul = data
160        .get(window.clone())
161        .and_then(|w| w.iter().position(|b| *b == 0))
162        .map(|k| window.start + k);
163    py_string_to_null_found(data.len(), pos, max_length, nul)
164}
165
166/// The bytes [`py_string_to_null`] searches for its NUL at `pos` over `len`
167/// bytes: `re.search`'s window `pos..pos + max_length`, each bound clamped
168/// into `0..=len`, empty where the end falls before the start.
169#[must_use]
170pub(crate) fn py_string_window(len: usize, pos: i128, max_length: usize) -> Range<usize> {
171    let l = i128::try_from(len).unwrap_or(i128::MAX);
172    let max = i128::try_from(max_length).unwrap_or(i128::MAX);
173    let clamp = |i: i128| usize::try_from(i.clamp(0, l)).unwrap_or(0);
174    let start = clamp(pos);
175    start..clamp(pos.saturating_add(max)).max(start)
176}
177
178/// [`py_string_to_null`]'s answer once its search is done: `nul` is the
179/// first NUL in [`py_string_window`]'s window, as an index of the whole
180/// buffer, or `None` where the window holds none. A caller that knows where
181/// the NULs are (a typetree blob's string buffer, indexed once) answers
182/// every offset without searching it again.
183#[must_use]
184pub(crate) fn py_string_to_null_found(
185    len: usize,
186    pos: i128,
187    max_length: usize,
188    nul: Option<usize>,
189) -> Option<(Range<usize>, i128)> {
190    let l = i128::try_from(len).ok()?;
191    let max = i128::try_from(max_length).ok()?;
192    if let Some(nul) = nul {
193        let start = py_string_window(len, pos, max_length).start;
194        return Some((start..nul, i128::try_from(nul).ok()? + 1));
195    }
196    if pos.saturating_add(max) >= l {
197        return None;
198    }
199    Some(py_read(len, pos, i64::try_from(max_length).ok()?))
200}
201
202/// What `read(N)` returns where UnityPy keeps the bytes as they are (a
203/// GUID, a hash): the [`py_read`] slice, inline. It holds `N` bytes, or
204/// fewer where the slice is short: none at a position in `-N..0` (the
205/// slice `view[p:p+N]` runs from the end back to the start, so it is
206/// empty, though the position moves to `p + N`), the rest at the end.
207#[derive(Clone, Copy, PartialEq, Eq, Hash)]
208pub struct ShortArray<const N: usize> {
209    bytes: [u8; N],
210    len: usize,
211}
212
213const _: () = crate::send_sync::<ShortArray<16>>();
214
215impl<const N: usize> ShortArray<N> {
216    /// The first `N` bytes of `got` (all of it, when shorter).
217    #[must_use]
218    pub fn from_slice(got: &[u8]) -> Self {
219        let len = got.len().min(N);
220        let mut bytes = [0u8; N];
221        if let (Some(to), Some(from)) = (bytes.get_mut(..len), got.get(..len)) {
222            to.copy_from_slice(from);
223        }
224        Self { bytes, len }
225    }
226
227    /// The bytes read.
228    #[must_use]
229    pub fn as_slice(&self) -> &[u8] {
230        self.bytes.get(..self.len).unwrap_or_default()
231    }
232}
233
234impl<const N: usize> From<[u8; N]> for ShortArray<N> {
235    fn from(bytes: [u8; N]) -> Self {
236        Self { bytes, len: N }
237    }
238}
239
240impl<const N: usize> std::ops::Deref for ShortArray<N> {
241    type Target = [u8];
242
243    fn deref(&self) -> &[u8] {
244        self.as_slice()
245    }
246}
247
248impl<const N: usize> std::fmt::Debug for ShortArray<N> {
249    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
250        self.as_slice().fmt(f)
251    }
252}
253
254/// A cursor over `data`, read by the rules of one of UnityPy's readers
255/// ([`ReaderKind`]). Positions are absolute within `data` and signed, as a
256/// Python `Position` (module docs): on the memory reader every read follows
257/// the helper of its Python primitive at whatever position it is, negative
258/// or past the end; the stream reader's position is never negative.
259#[derive(Clone, Debug)]
260pub struct Reader<'a> {
261    data: &'a [u8],
262    pos: i128,
263    endian: Endian,
264    kind: ReaderKind,
265}
266
267impl<'a> Reader<'a> {
268    /// A memory reader at position 0 (what UnityPy reads bytes with).
269    #[must_use]
270    pub fn new(data: &'a [u8], endian: Endian) -> Self {
271        Self::with_kind(data, endian, ReaderKind::Memory)
272    }
273
274    /// A reader of `kind` at position 0.
275    #[must_use]
276    pub fn with_kind(data: &'a [u8], endian: Endian, kind: ReaderKind) -> Self {
277        Self {
278            data,
279            pos: 0,
280            endian,
281            kind,
282        }
283    }
284
285    /// The whole slice.
286    #[must_use]
287    pub fn data(&self) -> &'a [u8] {
288        self.data
289    }
290
291    /// Which reader's rules it reads by.
292    #[must_use]
293    pub fn kind(&self) -> ReaderKind {
294        self.kind
295    }
296
297    /// The position, as Python holds it.
298    #[must_use]
299    pub fn position(&self) -> i128 {
300        self.pos
301    }
302
303    /// An assignment to `reader.Position`: the memory reader takes any
304    /// position, negative or past the end; the stream reader refuses a
305    /// negative one or one at or above 2^63 ([`ReaderKind::seek`]), and
306    /// stays where it was.
307    pub fn set_position(&mut self, pos: i128) -> Result<(), Error> {
308        self.pos = self.kind.seek(pos)?;
309        Ok(())
310    }
311
312    /// Where a read the caller made itself, by this reader's rules, leaves
313    /// the position (`typetree::parse::string_to_null`): no assignment, so
314    /// nothing to refuse.
315    pub(crate) fn advance_to(&mut self, pos: i128) {
316        self.pos = pos;
317    }
318
319    /// The byte order of multi-byte reads.
320    #[must_use]
321    pub fn endian(&self) -> Endian {
322        self.endian
323    }
324
325    /// Changes the byte order (a `SerializedFile` header switches it).
326    pub fn set_endian(&mut self, endian: Endian) {
327        self.endian = endian;
328    }
329
330    /// The bytes `read(-1)` would return from here: what a table's growth may
331    /// count on (plan section 3.3). The same on both readers.
332    #[must_use]
333    pub fn remaining(&self) -> usize {
334        py_read(self.data.len(), self.pos, -1).0.len()
335    }
336
337    /// `align_stream(n)`: [`py_align`], without a bounds check, assigned
338    /// to the position: the memory reader takes any result; the stream
339    /// reader's position is never negative, so the arithmetic is the same,
340    /// and it refuses a result at or above 2^63 as its `seek` does
341    /// ([`ReaderKind::align`]), staying where it was.
342    pub fn align(&mut self, n: u32) -> Result<(), Error> {
343        // UnityPy streams/EndianBinaryReader.py:155-156
344        self.pos = self.kind.align(self.pos, n)?;
345        Ok(())
346    }
347
348    /// The bytes after the position, as [`Error::OutOfBounds`] reports them.
349    fn have(&self) -> u64 {
350        u64::try_from(self.remaining()).unwrap_or(u64::MAX)
351    }
352
353    fn out_of_bounds(&self, what: &'static str, pos: i128, need: usize) -> Error {
354        Error::OutOfBounds {
355            what,
356            pos,
357            need: u64::try_from(need).unwrap_or(u64::MAX),
358            have: self.have(),
359            reader: self.kind,
360            length: self.data.len(),
361        }
362    }
363
364    /// `read(n)`, the range of `data` it returns: the memory reader's
365    /// [`py_read`] slice, short or empty at the ends (`read_bytes` on a
366    /// truncated block, `File.py:79`), the position moved by `n`; or the
367    /// stream reader's, which refuses an `n` below -1 and stops at the end
368    /// ([`ReaderKind::read`]).
369    pub fn read_range(&mut self, n: i64) -> Result<Range<usize>, Error> {
370        // UnityPy streams/EndianBinaryReader.py:249-256, :295
371        let (range, pos) = self.kind.read(self.data.len(), self.pos, n)?;
372        self.pos = pos;
373        Ok(range)
374    }
375
376    /// `read(n)` as it is: [`Self::read_range`]'s bytes.
377    pub fn read(&mut self, n: i64) -> Result<&'a [u8], Error> {
378        let range = self.read_range(n)?;
379        Ok(self.data.get(range).unwrap_or_default())
380    }
381
382    /// `n` bytes where UnityPy's caller unpacks them whole (`read(n)`, then
383    /// `struct.unpack`): what `read(n)` returns must hold `n` bytes, else
384    /// `OutOfBounds`; the position moves as `read(n)` moves it either way.
385    pub fn read_bytes(&mut self, n: usize) -> Result<&'a [u8], Error> {
386        let pos = self.pos;
387        let got = self.read(i64::try_from(n).unwrap_or(i64::MAX))?;
388        if got.len() == n {
389            Ok(got)
390        } else {
391            Err(self.out_of_bounds("bytes", pos, n))
392        }
393    }
394
395    /// `read(n)` as it is for a size UnityPy's own code fixes (3, 16 or 32
396    /// bytes), which neither reader refuses: short or empty at the ends.
397    pub fn read_bytes_short(&mut self, n: usize) -> &'a [u8] {
398        self.read(i64::try_from(n).unwrap_or(i64::MAX))
399            .unwrap_or_default()
400    }
401
402    /// `read_string_to_null` with the 32,767-byte window, by the reader's
403    /// rule ([`py_string_to_null`] or the stream reader's loop,
404    /// [`ReaderKind::string_to_null`]).
405    pub fn read_string_to_null(&mut self) -> Result<&'a [u8], Error> {
406        // UnityPy streams/EndianBinaryReader.py:136-144, :275-284
407        let pos = self.pos;
408        match self
409            .kind
410            .string_to_null(self.data, pos, STRING_TO_NULL_WINDOW)
411        {
412            Some((range, new)) => {
413                self.pos = new;
414                Ok(self.data.get(range).unwrap_or_default())
415            }
416            None => Err(self.out_of_bounds("string to null", pos, 1)),
417        }
418    }
419
420    /// The error [`Self::read_string_to_null`] raises at the position, for
421    /// a caller that searched the window itself and found no NUL with no
422    /// room left (`typetree::parse::string_to_null`).
423    pub(crate) fn string_to_null_error(&self) -> Error {
424        self.out_of_bounds("string to null", self.pos, 1)
425    }
426
427    /// One byte for `unpack(fmt, read(1))` (`:93-97`): the position moves as
428    /// `read(1)` moves it even when it returns nothing.
429    fn one_byte(&mut self, what: &'static str) -> Result<u8, Error> {
430        let pos = self.pos;
431        match self.read_bytes_short(1) {
432            [b] => Ok(*b),
433            _ => Err(self.out_of_bounds(what, pos, 1)),
434        }
435    }
436
437    /// One byte as a bool (non-zero is true): `unpack("?", read(1))`.
438    pub fn read_bool(&mut self) -> Result<bool, Error> {
439        // UnityPy streams/EndianBinaryReader.py:126-127
440        self.one_byte("bool").map(|b| b != 0)
441    }
442
443    /// `u8`: `unpack("B", read(1))`.
444    pub fn read_u8(&mut self) -> Result<u8, Error> {
445        // UnityPy streams/EndianBinaryReader.py:96-97
446        self.one_byte("u8")
447    }
448
449    /// `i8`: `unpack("b", read(1))`.
450    pub fn read_i8(&mut self) -> Result<i8, Error> {
451        // UnityPy streams/EndianBinaryReader.py:93-94
452        self.one_byte("i8").map(|b| i8::from_le_bytes([b]))
453    }
454
455    /// `N` bytes by the reader's own fixed-width read ([`ReaderKind::unpack`]):
456    /// `struct.unpack_from(view, Position)` (`:340-343`) on the memory
457    /// reader, whose position moves by `N` only on success;
458    /// `struct.unpack(stream.read(N))` (`:345-346`) on the stream reader,
459    /// whose position moves by what it read either way.
460    fn fixed<const N: usize>(&mut self, what: &'static str) -> Result<[u8; N], Error> {
461        let pos = self.pos;
462        let (at, next) = self.kind.unpack(self.data.len(), pos, N);
463        let Some(at) = at else {
464            let e = self.out_of_bounds(what, pos, N);
465            self.pos = next;
466            return Err(e);
467        };
468        let mut b = [0u8; N];
469        if let Some(src) = self.data.get(at..at.saturating_add(N)) {
470            b.copy_from_slice(src);
471        }
472        self.pos = next;
473        if self.endian == Endian::Big {
474            b.reverse();
475        }
476        // Little-endian from here on.
477        Ok(b)
478    }
479
480    /// `u16` in the reader's byte order: [`ReaderKind::unpack`].
481    pub fn read_u16(&mut self) -> Result<u16, Error> {
482        self.fixed("u16").map(u16::from_le_bytes)
483    }
484
485    /// `i16` in the reader's byte order: [`ReaderKind::unpack`].
486    pub fn read_i16(&mut self) -> Result<i16, Error> {
487        self.fixed("i16").map(i16::from_le_bytes)
488    }
489
490    /// `u32` in the reader's byte order: [`ReaderKind::unpack`].
491    pub fn read_u32(&mut self) -> Result<u32, Error> {
492        self.fixed("u32").map(u32::from_le_bytes)
493    }
494
495    /// `i32` in the reader's byte order: [`ReaderKind::unpack`].
496    pub fn read_i32(&mut self) -> Result<i32, Error> {
497        self.fixed("i32").map(i32::from_le_bytes)
498    }
499
500    /// `u64` in the reader's byte order: [`ReaderKind::unpack`].
501    pub fn read_u64(&mut self) -> Result<u64, Error> {
502        self.fixed("u64").map(u64::from_le_bytes)
503    }
504
505    /// `i64` in the reader's byte order: [`ReaderKind::unpack`].
506    pub fn read_i64(&mut self) -> Result<i64, Error> {
507        self.fixed("i64").map(i64::from_le_bytes)
508    }
509
510    /// `read(N)` kept as it is ([`ShortArray`]): a GUID or a hash, which
511    /// UnityPy stores without checking its length, so a short read (on the
512    /// memory reader at a position in `-N..0`; at the end on either) is no
513    /// error; the position moves as `read(N)` moves it.
514    pub fn read_short_array<const N: usize>(&mut self) -> ShortArray<N> {
515        ShortArray::from_slice(self.read_bytes_short(N))
516    }
517
518    /// A fixed-size byte array: `read(N)`, which must hold `N` bytes where
519    /// UnityPy's caller needs them all (it unpacks them); where it keeps
520    /// them as they are, [`Self::read_short_array`].
521    pub fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error> {
522        let got = self.read_bytes(N)?;
523        let mut b = [0u8; N];
524        b.copy_from_slice(got);
525        Ok(b)
526    }
527
528    /// `read_int_array` (`EndianBinaryReader.py:182`, `read_array_struct` at
529    /// `:164-168` and `:258-264`): an `i32` count read as the reader's own
530    /// `read_int` ([`ReaderKind::unpack`]), then the array: on the memory
531    /// reader `struct.unpack_from` of that many `i32` at the new position (a
532    /// negative one counts from the end), the position moving by
533    /// `4 * count`; on the stream reader `struct.unpack(read(4 * count))`,
534    /// which moves it by what it read, even when that is short. A negative
535    /// count raises (`Struct("<-1i")` is a bad format) with the position
536    /// after the count, as does an array the bytes do not hold (the stream
537    /// reader's has moved). The array is a vector on `meter`, the input's,
538    /// charged after the bytes are checked and before it is allocated, so a
539    /// count allocates nothing the bytes do not back and the array counts
540    /// against its input while it is kept (round 5: this returned a plain
541    /// `Vec`, the one input-sized allocation a parser made uncharged); a
542    /// refused charge is the meter's or the budget's error, with the
543    /// position after the count. Implemented by the scaffold; the cases are
544    /// recorded from UnityPy 1.25.2 (`read_i32_array_reads_as_unitypy_and_charges_the_meter`).
545    pub fn read_i32_array(&mut self, meter: &Arc<Meter>) -> Result<MeteredVec<i32>, Error> {
546        const WHAT: &str = "int array";
547        let len = self.data.len();
548        let have = self.have();
549        let (at, next) = self.kind.unpack(len, self.pos, 4);
550        let Some(at) = at else {
551            let e = Error::OutOfBounds {
552                what: WHAT,
553                pos: self.pos,
554                need: 4,
555                have,
556                reader: self.kind,
557                length: self.data.len(),
558            };
559            self.pos = next;
560            return Err(e);
561        };
562        let count = self.i32_at(at);
563        self.pos = next;
564        let Ok(n) = usize::try_from(count) else {
565            return Err(Error::Malformed {
566                what: WHAT,
567                detail: format!("negative count {count}").into(),
568            });
569        };
570        let (at, next) = n
571            .checked_mul(4)
572            .map_or((None, self.pos), |b| self.kind.unpack(len, self.pos, b));
573        let Some(at) = at else {
574            let e = Error::OutOfBounds {
575                what: WHAT,
576                pos: self.pos,
577                need: u64::try_from(n).unwrap_or(u64::MAX).saturating_mul(4),
578                have: self.have(),
579                reader: self.kind,
580                length: self.data.len(),
581            };
582            self.pos = next;
583            return Err(e);
584        };
585        let mut out = MeteredVec::with_capacity(meter, n)?;
586        for i in 0..n {
587            out.push(self.i32_at(at + 4 * i))?;
588        }
589        self.pos = next;
590        Ok(out)
591    }
592
593    /// The `i32` at `at`, which [`ReaderKind::unpack`] checked, in the
594    /// reader's byte order.
595    fn i32_at(&self, at: usize) -> i32 {
596        let mut b = [0u8; 4];
597        if let Some(src) = self.data.get(at..at + 4) {
598            b.copy_from_slice(src);
599        }
600        match self.endian {
601            Endian::Little => i32::from_le_bytes(b),
602            Endian::Big => i32::from_be_bytes(b),
603        }
604    }
605}
606
607#[cfg(test)]
608mod tests {
609    use super::{Endian, Reader, py_read};
610    use crate::budget::{Reservation, Unbounded};
611    use crate::error::Error;
612    use crate::error::LimitKind;
613    use crate::limits::{Meter, heap_cost};
614
615    #[test]
616    fn read_i32_array_reads_as_unitypy_and_charges_the_meter() {
617        // Recorded from UnityPy 1.25.2's memoryview reader (`read_int_array`
618        // at a set `Position`): (bytes, endian, position) -> values and the
619        // new position, or the error and the position after it.
620        let le = |v: &[i32]| v.iter().flat_map(|x| x.to_le_bytes()).collect::<Vec<u8>>();
621        let be = |v: &[i32]| v.iter().flat_map(|x| x.to_be_bytes()).collect::<Vec<u8>>();
622        let m = Meter::unlimited();
623        let ok = |data: &[u8], endian, pos: i128| {
624            let mut r = Reader::new(data, endian);
625            r.set_position(pos).unwrap();
626            let v = r.read_i32_array(&m).unwrap();
627            (v.as_slice().to_vec(), r.position(), v.charge().bytes())
628        };
629        assert_eq!(
630            ok(&le(&[3, 1, -2, 3]), Endian::Little, 0),
631            (vec![1, -2, 3], 16, heap_cost(12))
632        );
633        assert_eq!(
634            ok(&be(&[3, 1, -2, 3]), Endian::Big, 0),
635            (vec![1, -2, 3], 16, heap_cost(12))
636        );
637        // A negative position counts from the end, for the count and the
638        // array alike.
639        assert_eq!(
640            ok(&le(&[1, 7, 9]), Endian::Little, -12),
641            (vec![7], -4, heap_cost(4))
642        );
643        assert_eq!(ok(&le(&[0]), Endian::Little, 0), (vec![], 4, 0));
644
645        let err = |data: &[u8], limit: u64| {
646            let m = Meter::new(limit, std::sync::Arc::new(Unbounded), Reservation::Input);
647            let mut r = Reader::new(data, Endian::Little);
648            let e = r.read_i32_array(&m).unwrap_err();
649            (e, r.position(), m.used())
650        };
651        // UnityPy: `bad char in struct format`, Position 4.
652        let (e, pos, used) = err(&le(&[-1, 5]), u64::MAX);
653        assert!(matches!(e, Error::Malformed { .. }), "{e:?}");
654        assert_eq!((pos, used), (4, 0));
655        // A huge count over 4 bytes: refused by the bytes, nothing charged.
656        let (e, pos, used) = err(&le(&[i32::MAX, 5]), u64::MAX);
657        assert!(
658            matches!(
659                e,
660                Error::OutOfBounds {
661                    need: 8_589_934_588,
662                    ..
663                }
664            ),
665            "{e:?}"
666        );
667        assert_eq!((pos, used), (4, 0));
668        let (e, pos, _) = err(&[1, 0], u64::MAX);
669        assert!(matches!(e, Error::OutOfBounds { need: 4, .. }), "{e:?}");
670        assert_eq!(pos, 0);
671        // An array the bytes hold but the meter does not: refused before it
672        // is allocated.
673        let (e, pos, used) = err(&le(&[64; 65]), 100);
674        assert!(
675            matches!(&e, Error::Limit(l) if l.kind() == LimitKind::InputMemory),
676            "{e:?}"
677        );
678        assert_eq!((pos, used), (4, 0));
679    }
680
681    #[test]
682    fn py_read_is_a_python_slice() {
683        // Recorded from UnityPy 1.25.2's memoryview reader over bytes(range(10)):
684        // (position, size) -> (bytes read, new position).
685        let cases: &[(i128, i64, std::ops::Range<usize>, i128)] = &[
686            (0, 4, 0..4, 4),
687            (8, 4, 8..10, 12),
688            (12, 4, 10..10, 16),
689            (3, 0, 0..0, 3),
690            (3, -1, 3..10, 10),
691            (-3, 2, 7..9, -1),
692            (-3, 5, 7..7, 2),
693            (5, -3, 5..5, 2),
694            (2, -5, 2..7, -3),
695            (-20, 5, 0..0, -15),
696            (-1, -1, 9..10, 10),
697            // Past the end, size -1: `size = Length - Position` is -2, so the
698            // position comes back to the end (UnityPy: `read(-1)` at 12 of 10
699            // leaves Position 10).
700            (12, -1, 10..10, 10),
701            (15, -1, 10..10, 10),
702            (i128::from(i64::MIN), i64::MAX, 0..9, -1),
703        ];
704        for (pos, size, range, new_pos) in cases {
705            let (r, p) = py_read(10, *pos, *size);
706            assert_eq!(r.len(), range.len(), "({pos}, {size})");
707            if !range.is_empty() {
708                assert_eq!(r, *range, "({pos}, {size})");
709            }
710            assert_eq!(p, *new_pos, "({pos}, {size})");
711        }
712    }
713}