arcly-stream 0.1.7

//! Annex-B start-code scanning — the single canonical implementation shared by
//! the codec NAL utilities ([`codec::nal`](crate::codec::nal)) and the ingest
//! packetizers ([`protocol`](crate::protocol)).
//!
//! Both layers need to locate `00 00 01` / `00 00 00 01` start codes; they
//! differ only in whether a code's leading zeros may sit *before* the search
//! origin (the `floor`). Parameterizing that one difference keeps a single,
//! `memchr`-accelerated scanner instead of two near-copies whose subtly
//! different boundary semantics are easy to drift apart.

/// Find the next Annex-B start code, searching for its trailing `0x01` at or
/// after `from` and requiring the whole code to lie at or after `floor`.
///
/// Returns `(offset, len)`, where `offset` is the index of the start code's
/// first byte and `len` is 3 (`00 00 01`) or 4 (`00 00 00 01`).
///
/// `floor` bounds how far back the leading zeros may reach:
/// - pass `from` to require the start code to *begin* at/after the origin
///   (the NAL-iterator contract, where each scan resumes past prior content);
/// - pass `0` to allow a code that straddles `from` (the resume-from-offset
///   ingest contract, where `from` can land mid-`00 00`).
pub(crate) fn scan_start_code(buf: &[u8], from: usize, floor: usize) -> Option<(usize, usize)> {
    let mut search = from;
    // Jump directly between candidate `0x01` bytes rather than scanning each
    // byte — significant on the ingest hot path, where every H.264 packet is
    // split into NAL units.
    while let Some(rel) = memchr::memchr(0x01, buf.get(search..)?) {
        let one = search + rel;
        // Require `00 00` immediately before the `01`, no earlier than `floor`.
        if one >= floor + 2 && buf[one - 1] == 0 && buf[one - 2] == 0 {
            // Prefer the 4-byte form when a third leading zero is in range.
            if one >= floor + 3 && buf[one - 3] == 0 {
                return Some((one - 3, 4));
            }
            return Some((one - 2, 3));
        }
        search = one + 1;
    }
    None
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn floor_from_requires_code_to_begin_at_or_after_origin() {
        // `00 00 01` whose body starts before `from`: floored scan skips it.
        let buf = [0, 0, 1, 9];
        assert_eq!(scan_start_code(&buf, 1, 1), None);
        // floor 0 finds it, reaching back past `from`.
        assert_eq!(scan_start_code(&buf, 1, 0), Some((0, 3)));
    }

    #[test]
    fn classifies_three_and_four_byte_codes() {
        let buf = [0, 0, 0, 1, 9, 0, 0, 1, 7];
        assert_eq!(scan_start_code(&buf, 0, 0), Some((0, 4)));
        assert_eq!(scan_start_code(&buf, 4, 4), Some((5, 3)));
    }

    #[test]
    fn out_of_range_origin_is_none_not_panic() {
        let buf = [0, 0, 1];
        assert_eq!(scan_start_code(&buf, 99, 0), None);
    }
}