rm2k-lib 1.0.1

Reads and writes the RPG Maker 2000/2003 LCF binary formats (LDB, LMU, LMT, LSD).
Documentation
//! The LCF wire codec: compressed integers, fixed-width primitives, file magics.
//!
//! Pure functions over byte slices, with no cursor state - [`Cursor`](crate::cursor::Cursor)
//! layers position tracking and diagnostics on top. Everything here is allocation-free and free
//! of `unsafe`.
//!
//! # Compressed integers
//!
//! LCF's variable-length integer is **big-endian** base-128 with an MSB continuation bit - the
//! opposite byte order from protobuf's LEB128, so an off-the-shelf varint crate will decode it
//! wrong.
//!
//! A well-formed encoding is at most 5 bytes. A longer one is malformed, but its bytes still have
//! to be consumed to keep the cursor in sync with the rest of the file: [`decode_varint`] keeps
//! reading until it sees a byte with the high bit clear, decodes to `0`, and reports the overrun
//! via `overflow` so the caller can record a
//! [`DiagKind::BadVarint`](crate::diag::DiagKind::BadVarint) rather than treating it as `0` and
//! saying nothing. Accumulation happens in a 32-bit register (`value = (value << 7) | (byte &
//! 0x7F)`), so a maximal 5-byte encoding wraps rather than widening.

use crate::sink::Sink;

pub const LDB_HEADER: &[u8] = b"LcfDataBase";
pub const LMU_HEADER: &[u8] = b"LcfMapUnit";
pub const LMT_HEADER: &[u8] = b"LcfMapTree";
pub const LSD_HEADER: &[u8] = b"LcfSaveData";

/// Most bytes a 32-bit compressed integer may occupy.
pub const MAX_VARINT_LEN: usize = 5;
/// Most bytes a 64-bit compressed integer may occupy.
pub const MAX_VARINT64_LEN: usize = 10;

/// A decoded compressed integer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Varint {
    /// The value, already zeroed when `overflow` is set.
    pub value: u32,
    /// Bytes consumed, including the over-long tail when `overflow` is set.
    pub consumed: usize,
    /// The encoding ran past the byte cap; liblcf substitutes `0`.
    pub overflow: bool,
}

/// Decode a 32-bit compressed integer from the front of `buf`.
///
/// Returns `None` when `buf` ends before a terminating byte (high bit clear) is found. liblcf
/// treats that as `0` at EOF; callers should do the same after recording a diagnostic.
#[must_use]
pub fn decode_varint(buf: &[u8]) -> Option<Varint> {
    let mut value: u32 = 0;
    let mut consumed = 0usize;

    loop {
        let byte = *buf.get(consumed)?;
        consumed += 1;
        value = (value << 7) | u32::from(byte & 0x7F);
        if byte & 0x80 == 0 {
            break;
        }
    }

    let overflow = consumed > MAX_VARINT_LEN;
    Some(Varint {
        value: if overflow { 0 } else { value },
        consumed,
        overflow,
    })
}

/// A decoded 64-bit compressed integer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Varint64 {
    /// The value, already zeroed when `overflow` is set.
    pub value: u64,
    /// Bytes consumed, including the over-long tail when `overflow` is set.
    pub consumed: usize,
    /// The encoding ran past the byte cap; liblcf substitutes `0`.
    pub overflow: bool,
}

/// Decode a 64-bit compressed integer from the front of `buf`.
///
/// Same shape as [`decode_varint`] with a 10-byte cap (`LcfReader::ReadUInt64`,
/// `src/reader_lcf.cpp:106`). Used only by the sparse string-vector encoding, where a value above
/// `u32::MAX` is a run-length gap marker rather than a string length
/// (`src/dbstring_struct.cpp:93`).
#[must_use]
pub fn decode_varint64(buf: &[u8]) -> Option<Varint64> {
    let mut value: u64 = 0;
    let mut consumed = 0usize;

    loop {
        let byte = *buf.get(consumed)?;
        consumed += 1;
        value = (value << 7) | u64::from(byte & 0x7F);
        if byte & 0x80 == 0 {
            break;
        }
    }

    let overflow = consumed > MAX_VARINT64_LEN;
    Some(Varint64 {
        value: if overflow { 0 } else { value },
        consumed,
        overflow,
    })
}

/// Encoded length in bytes of `value` as a compressed integer.
///
/// Mirrors `LcfReader::IntSize` (`src/reader_lcf.cpp:330`): `ceil(bits / 7)`, minimum 1.
#[must_use]
pub const fn varint_len(value: u32) -> u32 {
    let mut x = value;
    let mut result = 0u32;
    loop {
        x >>= 7;
        result += 1;
        if x == 0 {
            return result;
        }
    }
}

/// Encoded length in bytes of `value` as a 64-bit compressed integer.
#[must_use]
pub const fn varint64_len(value: u64) -> u32 {
    let mut x = value;
    let mut result = 0u32;
    loop {
        x >>= 7;
        result += 1;
        if x == 0 {
            return result;
        }
    }
}

/// Encode `value` into `out`, returning how many bytes were written.
///
/// Mirrors `LcfWriter::WriteInt` (`src/writer_lcf.cpp:50`), which emits 7-bit groups from bit 28
/// downwards - so it never writes more than 5 bytes and silently drops anything above bit 34.
#[must_use]
pub fn encode_varint(value: u32, out: &mut [u8; MAX_VARINT_LEN]) -> usize {
    let mut len = 0usize;
    let mut shift: i32 = 28;
    while shift >= 0 {
        if value >= (1u32 << shift) || shift == 0 {
            let group = ((value >> shift) & 0x7F) as u8;
            out[len] = if shift > 0 { group | 0x80 } else { group };
            len += 1;
        }
        shift -= 7;
    }
    len
}

/// Encode `value` as a 64-bit compressed integer into `out`, returning bytes written.
#[must_use]
pub fn encode_varint64(value: u64, out: &mut [u8; MAX_VARINT64_LEN]) -> usize {
    let mut len = 0usize;
    let mut shift: i32 = 56;
    while shift >= 0 {
        if value >= (1u64 << shift) || shift == 0 {
            let group = ((value >> shift) & 0x7F) as u8;
            out[len] = if shift > 0 { group | 0x80 } else { group };
            len += 1;
        }
        shift -= 7;
    }
    len
}

/// Write `value` to `sink` as a compressed integer.
///
/// # Errors
/// Propagates the sink's error. Infallible for `Vec<u8>`.
#[inline]
pub fn write_varint<S: Sink>(sink: &mut S, value: u32) -> Result<(), S::Error> {
    let mut buf = [0u8; MAX_VARINT_LEN];
    let len = encode_varint(value, &mut buf);
    sink.write(&buf[..len])
}

/// Write `value` to `sink` as a 64-bit compressed integer.
///
/// # Errors
/// Propagates the sink's error. Infallible for `Vec<u8>`.
#[inline]
pub fn write_varint64<S: Sink>(sink: &mut S, value: u64) -> Result<(), S::Error> {
    let mut buf = [0u8; MAX_VARINT64_LEN];
    let len = encode_varint64(value, &mut buf);
    sink.write(&buf[..len])
}

/// Read a little-endian `i16` from the front of `buf`.
#[must_use]
#[inline]
pub fn read_i16_le(buf: &[u8]) -> Option<i16> {
    buf.get(..2).map(|b| i16::from_le_bytes([b[0], b[1]]))
}

/// Read a little-endian `u32` from the front of `buf`.
#[must_use]
#[inline]
pub fn read_u32_le(buf: &[u8]) -> Option<u32> {
    buf.get(..4).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
}

/// Read a little-endian `i32` from the front of `buf`.
///
/// This is the *raw* form used inside packed arrays. A bare `Int32` **field** is a compressed
/// integer instead - see [`decode_varint`]. liblcf's
/// `LcfWriter::Write<int32_t>(const std::vector<int32_t>&)` carries a comment claiming it writes a
/// compressed integer; it does not (`src/writer_lcf.cpp:101`).
#[must_use]
#[inline]
pub fn read_i32_le(buf: &[u8]) -> Option<i32> {
    buf.get(..4).map(|b| i32::from_le_bytes([b[0], b[1], b[2], b[3]]))
}

/// Read a little-endian `f64` from the front of `buf`.
#[must_use]
#[inline]
pub fn read_f64_le(buf: &[u8]) -> Option<f64> {
    buf.get(..8)
        .map(|b| f64::from_le_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]))
}