structio 0.8.0

//! The parse cursor.
//!
//! [`Parser`] walks the input directly into the destination. There is no
//! intermediate document, no token stream, and no per-value allocation: a
//! field's bytes are converted once, straight into the struct member that will
//! hold them.
//!
//! Input is always a `&str`, so the whole document is known to be valid UTF-8
//! before parsing starts, and the cursor keeps it as one. String values can
//! therefore be sliced out and handed back without revalidation, a reader
//! capturing a whole span can take it through [`Parser::rest_str`] without
//! establishing again what the input already proved, and unescaping only has
//! to produce valid UTF-8 for the escapes it expands.

use core::fmt;
use core::marker::PhantomData;

use crate::error::{ErrorCode, PResult};
use crate::json::traits::{Read, ReadArray, ReadEnum, ReadInternallyTagged, ReadObject};
use crate::num::atof::{parse_float, scan_number};
use crate::num::atoi::{
    out_of_range, parse_i64, parse_u128, parse_unsigned_u64, parse_unsigned_u128, reject_float_tail,
};
use crate::options::{Options, Standard};
use crate::swar::{escape_mask, find_byte, first_match, load_u64, needs_escape};
use crate::traits::{Fields, Keys, Variants, resolve_key, resolve_variant};

/// Nesting limit, so a hostile document cannot exhaust the stack.
pub const MAX_DEPTH: u32 = 256;

/// A cursor over a JSON document.
///
/// `O` is the [read policy](crate::Options). It decides nothing about the
/// cursor's state and is never constructed; it is read through `O::CONSTANT`
/// at the points that consult a setting, so an unselected behaviour costs no
/// code. It defaults to [`Standard`] where the type is written out.
pub struct Parser<'de, O: Options = Standard> {
    /// The document, kept as the `&str` every constructor is handed. What that
    /// buys is [`rest_str`](Parser::rest_str): the input's UTF-8 validity is
    /// established once, by whoever produced the `&str`, and a reader
    /// capturing a span of the document does not have to establish it again.
    data: &'de str,
    /// The same document as bytes, which is what every scan in here walks.
    ///
    /// Held rather than taken from `data` at each use, though `as_bytes` is a
    /// view rather than a conversion and costs nothing once the optimizer has
    /// run. It costs something before then: unoptimized, it materializes a fat
    /// pointer at every bounds test, which is about a sixth more stack per
    /// frame across the readers, and the recursive ones multiply that by the
    /// nesting limit. On the [`MAX_DEPTH`] test it is the difference between
    /// 300 KiB of a 2 MiB thread stack left over and 70 KiB, and a debug build
    /// is half of what CI runs. Holding it costs sixteen bytes and one store
    /// per parser, in the frame that owns the parser rather than in any of the
    /// ones it recurses through.
    ///
    /// The two views are set together and neither is ever reassigned, so there
    /// is no way for them to come apart.
    bytes: &'de [u8],
    idx: usize,
    depth: u32,
    /// The key to attach to the failure this parse is about to return. See
    /// [`set_error_key`](Parser::set_error_key).
    error_key: Option<&'static str>,
    /// Members of internally tagged objects that came before their tag, to
    /// be read once the ones after it are: a stack, since an object whose tag
    /// is late can hold a member whose tag is late too. Empty, and never
    /// allocated, until a late tag is found. See
    /// [`read_internally_tagged`](Parser::read_internally_tagged).
    deferred: Vec<Deferred>,
    /// `fn() -> O` rather than `O`, so the parser's auto traits follow what it
    /// actually holds rather than a policy type it never contains.
    options: PhantomData<fn() -> O>,
}

/// The members between an object's first key and a tag that was not it.
///
/// `start` is the first key's opening quote and `end` the tag's, so the run
/// is read by starting at one and stopping on reaching the other. `depth` is
/// the object's own, which is what tells its payload reader the run is its to
/// take rather than some enclosing object's.
#[derive(Clone, Copy)]
struct Deferred {
    start: usize,
    end: usize,
    depth: u32,
}

impl<'de> Parser<'de> {
    /// Wrap an input document, read under [`Standard`].
    ///
    /// This is the constructor to reach for. Hand-driving a parser is usually
    /// for reaching a document's bytes directly, where no setting applies;
    /// [`read_object`](Self::read_object) is the exception, and reads under
    /// [`Standard`] here like everything else.
    /// [`with_options`](Self::with_options) names a different policy, and is
    /// what the `_with` entry points use.
    ///
    /// ```
    /// use structio::json::Parser;
    ///
    /// let p = Parser::new("{}");
    /// assert_eq!(p.position(), 0);
    /// ```
    #[inline]
    pub fn new(input: &'de str) -> Self {
        Self::with_options(input)
    }
}

impl<'de, O: Options> Parser<'de, O> {
    /// Wrap an input document, read under the policy `O`.
    ///
    /// The policy is named once here and inferred everywhere after. A
    /// defaulted type parameter fills in a *type*; it does not tell inference
    /// what an associated function's `Self` is, which is why the default is
    /// reached through [`new`](Self::new) rather than by leaving `O` off.
    ///
    /// ```
    /// use structio::{SkipUnknown, json::Parser};
    ///
    /// let p = Parser::<SkipUnknown>::with_options("{}");
    /// assert_eq!(p.position(), 0);
    /// ```
    #[inline]
    pub fn with_options(input: &'de str) -> Self {
        Parser {
            data: input,
            bytes: input.as_bytes(),
            idx: 0,
            depth: 0,
            error_key: None,
            deferred: Vec::new(),
            options: PhantomData,
        }
    }

    /// Byte offset of the cursor, used to locate errors.
    #[inline(always)]
    pub fn position(&self) -> usize {
        self.idx
    }

    /// The key set for the failure being returned, if there is one.
    ///
    /// The companion of [`position`](Self::position): where that says which
    /// byte, this says which key. An entry point reads both when a read comes
    /// back `Err`, and they become [`Error::index`] and [`Error::key`].
    ///
    /// [`Error::index`]: crate::Error::index
    /// [`Error::key`]: crate::Error::key
    #[inline(always)]
    pub fn error_key(&self) -> Option<&'static str> {
        self.error_key
    }

    /// Name the key the failure about to be returned is about.
    ///
    /// The counterpart of [`rewind`](Self::rewind) for a hand-written [`Read`]
    /// impl, and for the same case: a reader that discovers at the end of an
    /// object that a member never arrived wants to name the object *and* to
    /// name the member, the offset alone being able to do only the first. This
    /// is what [`read_object`](Self::read_object) does for
    /// [`ErrorCode::MissingKey`], and what [`Matrix`](crate::Matrix) does by
    /// hand.
    ///
    /// **Set it after any [`rewind`](Self::rewind), on the branch that is
    /// returning `Err`.** A successful read does not clear the key, because
    /// clearing would mean a store on every object read; what clears it is
    /// [`rewind`](Self::rewind), which is how a reader abandons a read it is
    /// discarding. Setting a key and then winding back loses it, and that is
    /// the right way round.
    ///
    /// Only [`&'static str`](str) goes here, so an
    /// [`Error`](crate::Error) still outlives the document. A name read out of
    /// the input does not qualify, and does not need to: the cursor can be
    /// wound back to it instead, which is what the unknown-key and
    /// unknown-variant paths do.
    ///
    /// [`ErrorCode::MissingKey`]: crate::ErrorCode::MissingKey
    #[inline(always)]
    pub fn set_error_key(&mut self, key: &'static str) {
        self.error_key = Some(key);
    }

    /// Move the cursor back to a position it has already passed.
    ///
    /// The companion of [`position`](Self::position), and what a hand-written
    /// [`Read`] impl needs to report a failure against something it walked
    /// past. An [`Error`](crate::Error) carries no message, only a code and
    /// the offset the cursor stopped at, so pointing at the right byte is the
    /// whole of a good diagnostic: a reader that discovers at the end of an
    /// object that a member never arrived wants to name the object, not the
    /// byte that closed it. That is exactly what [`read_object`](Self::read_object)
    /// does for [`Options::ERROR_ON_MISSING_KEYS`],
    /// and what [`Matrix`](crate::Matrix) does by hand.
    ///
    /// The cursor never moves forward: a position ahead of it leaves it where
    /// it is. Winding forward would step over input without reading it, which
    /// is not something a caller could mean by "rewind".
    ///
    /// ```
    /// use structio::json::Parser;
    ///
    /// let mut p = Parser::new(r#"{"a":1}"#);
    /// let open = p.position();
    /// p.skip_value().unwrap();
    /// assert_eq!(p.position(), 7);
    ///
    /// p.rewind(open);
    /// assert_eq!(p.position(), open);
    ///
    /// // Forward is not a rewind, so nothing happens.
    /// p.rewind(4);
    /// assert_eq!(p.position(), open);
    /// ```
    /// Any key [`set_error_key`](Self::set_error_key) left is dropped,
    /// whoever set it. Winding back is how a reader abandons what it just
    /// read, and the key is part of what it read: a speculating reader that
    /// discards a failed read of a *generated* type would otherwise carry off
    /// a key the generated reader set behind its back, and have no way to know
    /// it was there. So the abandoning is what clears it, rather than a rule
    /// the abandoning reader has to remember.
    ///
    /// The other state a read keeps beside the cursor needs no winding back:
    /// a failed read releases the nesting levels it entered, and drops any
    /// late tag's members it was holding, on its way out. So a reader can fail
    /// and retry as often as it likes without the depth limit drawing nearer.
    #[inline]
    pub fn rewind(&mut self, to: usize) {
        // Clamping is also what keeps `idx <= data.len()`, which every bounds
        // test in here is written against.
        self.idx = to.min(self.idx);
        self.error_key = None;
    }

    /// Remaining input, starting at the cursor.
    #[inline(always)]
    pub fn rest(&self) -> &'de [u8] {
        // SAFETY-free: `idx` never advances past the document's length.
        &self.bytes[self.idx..]
    }

    /// Remaining input as text, starting at the cursor.
    ///
    /// [`rest`](Self::rest) for a reader that wants what the input already
    /// is. The document was a `&str` before parsing started, so a hand-written
    /// [`Read`] impl capturing a span of it can slice this and be done;
    /// capturing out of [`rest`](Self::rest) instead means running
    /// [`from_utf8`](core::str::from_utf8) over the span, which is a second
    /// walk over bytes this crate already knows are text. That is what
    /// [`Raw`](crate::json::Raw) takes, and it is the one path that type
    /// exists for.
    ///
    /// **The cursor has to be on a character boundary, and this panics if it
    /// is not.** Nothing the parser does can put it anywhere else: a
    /// multi-byte sequence only ever appears inside a string literal, every
    /// scan here crosses a literal whole, and so the cursor comes to rest
    /// between tokens rather than partway through a character. The one way
    /// past that is [`rewind`](Self::rewind), which takes an offset the caller
    /// chose and only clamps it, so a caller winding back to an index it did
    /// not get from [`position`](Self::position) can land inside one.
    ///
    /// That is why the slice is a plain index. `get(..)` with a fallback was
    /// the obvious alternative and is the wrong one: the only fallback a
    /// `&str` has is a shorter one, and handing back `""` would turn a cursor
    /// that had drifted into a caller reading an empty document, with the
    /// damage surfacing as a parse that quietly stopped early somewhere else.
    /// The unchecked slice is worse still, since it would make a safe caller's
    /// arithmetic load-bearing for soundness. The panic names the byte and the
    /// character it landed in the middle of, which is the whole diagnosis.
    #[inline(always)]
    pub fn rest_str(&self) -> &'de str {
        &self.data[self.idx..]
    }

    #[inline(always)]
    fn remaining(&self) -> usize {
        self.bytes.len() - self.idx
    }

    #[inline(always)]
    pub(crate) fn peek(&self) -> Option<u8> {
        self.bytes.get(self.idx).copied()
    }

    /// Skip JSON whitespace: space, tab, newline, carriage return.
    ///
    /// Under [`Options::ALLOW_COMMENTS`] a complete `//` or `/* */` comment is
    /// whitespace too, and runs of the two interleave freely. An incomplete
    /// one is not consumed, so the cursor stops on the `/` and whatever the
    /// caller expected there is reported against it.
    #[inline(always)]
    pub fn skip_ws(&mut self) {
        self.idx = skip_ws_at::<O>(self.bytes, self.idx);
    }

    /// Consume `b` if it is next.
    #[inline(always)]
    pub fn try_byte(&mut self, b: u8) -> bool {
        if self.idx < self.bytes.len() && self.bytes[self.idx] == b {
            self.idx += 1;
            true
        } else {
            false
        }
    }

    /// Consume `b`, or fail with `code`.
    #[inline(always)]
    pub fn expect(&mut self, b: u8, code: ErrorCode) -> PResult<()> {
        if self.idx < self.bytes.len() && self.bytes[self.idx] == b {
            self.idx += 1;
            Ok(())
        } else if self.idx >= self.bytes.len() {
            Err(ErrorCode::UnexpectedEnd)
        } else {
            Err(code)
        }
    }

    /// Whitespace, `:`, whitespace. Called once per object member.
    #[inline(always)]
    pub fn colon(&mut self) -> PResult<()> {
        self.skip_ws();
        self.expect(b':', ErrorCode::ExpectedColon)?;
        self.skip_ws();
        Ok(())
    }

    /// Consume the separator between container members: either a comma, or the
    /// closing byte that ends the container.
    ///
    /// Returns `true` to keep looping and `false` once the container is closed,
    /// leaving the cursor past whichever byte it consumed. Every object, array,
    /// map, and skip loop ends the same way, and so does each container the
    /// [prettifier](crate::prettify) lays out, so they all end here, and all
    /// report the same error when the document holds neither byte.
    #[inline(always)]
    pub(crate) fn comma_or_close(&mut self, close: u8) -> PResult<bool> {
        self.skip_ws();
        if self.try_byte(b',') {
            self.skip_ws();
            return Ok(true);
        }
        if self.try_byte(close) {
            return Ok(false);
        }
        Err(if self.idx >= self.bytes.len() {
            ErrorCode::UnexpectedEnd
        } else {
            ErrorCode::ExpectedComma
        })
    }

    /// Count one more level of nesting, or refuse it past [`MAX_DEPTH`].
    ///
    /// A refusal leaves the count where it was, so that like every other
    /// failure here it costs a reader that winds back and tries something else
    /// nothing. See [`nested`](Self::nested).
    #[inline(always)]
    pub(crate) fn enter(&mut self) -> PResult<()> {
        if self.depth >= MAX_DEPTH {
            return Err(ErrorCode::ExceededMaxDepth);
        }
        self.depth += 1;
        Ok(())
    }

    /// Run `body` one level deeper, and come back up however it exits.
    ///
    /// The depth count is state that outlives a failed read, which the cursor
    /// is not: [`rewind`](Self::rewind) puts the cursor back, but a level
    /// entered and never left would stay counted, so a reader that speculates
    /// and winds back would lose a level per failure and, some hundreds of
    /// failures on, have ordinary input refused as too deep. So a failure
    /// releases what it entered on the way out, and every container walk goes
    /// through here rather than pairing `enter` and `leave` around `?`s that
    /// would skip the `leave`.
    #[inline(always)]
    pub(crate) fn nested<R>(&mut self, body: impl FnOnce(&mut Self) -> PResult<R>) -> PResult<R> {
        self.enter()?;
        let result = body(self);
        self.leave();
        result
    }

    /// Leave a container [`enter`](Self::enter) counted.
    ///
    /// The two are balanced by the caller, on every exit, and the public
    /// `read_object_rest` / `finish_internally_tagged` pair takes its `enter`
    /// from whoever opened the object. A hand-written impl that calls one of
    /// those without having entered wraps the depth, and what that costs
    /// depends on how often it happens: once, the next `enter` wraps it back
    /// and the parse allows one extra level; repeatedly, the limit refuses
    /// input it should have taken. It stops counting altogether only when a
    /// stray `leave` cancels an `enter` at every level of a recursion, and
    /// then a hostile document has no depth limit at all. A debug build says
    /// so rather than leaving any of that to be discovered.
    #[inline(always)]
    pub(crate) fn leave(&mut self) {
        debug_assert!(
            self.depth > 0,
            "structio: `leave` without a matching `enter`, which would disable the nesting limit"
        );
        self.depth -= 1;
    }

    /// Confirm that the key at the cursor is exactly `key`, and step past it
    /// and its closing quote.
    ///
    /// Called from macro-generated code with a literal, so `key.len()` is a
    /// constant and the comparison inlines to a fixed-size compare rather than
    /// a `memcmp` call. This is the check that makes the perfect hash safe: the
    /// hash only proposes a candidate, and an unknown key that collides with an
    /// occupied bucket is rejected here.
    #[inline(always)]
    pub fn match_key(&mut self, key: &'static str) -> bool {
        let k = key.as_bytes();
        let n = k.len();
        let i = self.idx;
        // `i + n < len` covers both the key bytes and the closing quote.
        if i + n < self.bytes.len() && self.bytes[i + n] == b'"' && &self.bytes[i..i + n] == k {
            self.idx = i + n + 1;
            true
        } else {
            false
        }
    }

    // -----------------------------------------------------------------------
    // Structural
    // -----------------------------------------------------------------------

    /// Read a JSON object into a type declared with `object!`.
    ///
    /// One iteration per member: hash the key to a candidate index, let the
    /// generated dispatch confirm it and parse the value, then take the comma
    /// or the closing brace.
    pub fn read_object<T: ReadObject<'de>>(&mut self, value: &mut T) -> PResult<()> {
        self.skip_ws();
        // Where the object begins, so a member it never got to can be reported
        // against the object rather than against the byte that closed it. Dead,
        // and gone, under a policy that requires nothing.
        let open = self.idx;
        self.expect(b'{', ErrorCode::ExpectedBrace)?;
        let seen = self.nested(|p| {
            p.skip_ws();
            if p.try_byte(b'}') {
                return Ok(0);
            }
            p.object_members::<T>(value)
        })?;
        self.require_fields::<T>(seen, open)
    }

    /// Read the members of an object whose opening brace, and at least one
    /// member, are already consumed.
    ///
    /// What [`Self::read_internally_tagged`] leaves behind: the tag has been
    /// taken, and the rest of the object is the variant's payload. The cursor
    /// sits where that tag's value ended, so the first thing to settle is
    /// whether a comma follows it or the object is over.
    ///
    /// `open` is the offset of the object's opening brace, carried in because
    /// a [`MissingKey`](ErrorCode::MissingKey) is reported against the object
    /// rather than against the byte that closed it, and this is called after
    /// the caller has walked past it. `enter` is the caller's too, and so is
    /// balanced here by the `leave`, which is taken whether or not the members
    /// read.
    pub fn read_object_rest<T: ReadObject<'de>>(
        &mut self,
        value: &mut T,
        open: usize,
    ) -> PResult<()> {
        let seen = self.rest_members::<T>(value);
        self.leave();
        self.require_fields::<T>(seen?, open)
    }

    /// [`read_object_rest`](Self::read_object_rest) short of its `leave`, so
    /// that a member failing to read cannot skip it.
    #[inline(always)]
    fn rest_members<T: ReadObject<'de>>(&mut self, value: &mut T) -> PResult<u64> {
        let mut seen = if self.comma_or_close(b'}')? {
            self.object_members::<T>(value)?
        } else {
            0
        };
        if let Some(run) = self.take_deferred() {
            seen |= self.deferred_members::<T>(value, run)?;
        }
        Ok(seen)
    }

    /// Consume the rest of an object that has no fields to fill: the form an
    /// internally tagged variant carrying nothing takes.
    ///
    /// The tag was the whole value, so anything after it is an unknown member
    /// and meets the policy that governs one. `{"type":"a"}` is the ordinary
    /// case and costs a single `comma_or_close`. The `enter` is the caller's,
    /// and is balanced here, whether or not the members were acceptable.
    pub fn finish_internally_tagged(&mut self) -> PResult<()> {
        let result = self.unknown_members();
        self.leave();
        result
    }

    /// [`finish_internally_tagged`](Self::finish_internally_tagged) short of
    /// its `leave`, for [`read_object_rest`](Self::read_object_rest)'s reason.
    #[inline(always)]
    fn unknown_members(&mut self) -> PResult<()> {
        while self.comma_or_close(b'}')? {
            self.expect(b'"', ErrorCode::ExpectedQuote)?;
            if O::ERROR_ON_UNKNOWN_KEYS {
                return self.unknown_key();
            }
            self.skip_unknown_member()?;
        }
        if let Some(run) = self.take_deferred() {
            // Members before the tag are unknown ones too.
            let resume = self.idx;
            self.idx = run.start;
            while self.idx != run.end {
                self.expect(b'"', ErrorCode::ExpectedQuote)?;
                if O::ERROR_ON_UNKNOWN_KEYS {
                    return self.unknown_key();
                }
                self.skip_unknown_member()?;
                if !self.comma_or_close(b'}')? {
                    return Err(ErrorCode::ExpectedTag);
                }
            }
            self.idx = resume;
        }
        Ok(())
    }

    /// Refuse the key at the cursor, which no field claimed.
    ///
    /// `match_key` fails identically for a key that differs and for one the
    /// input ended in the middle of, so an unmatched key is not yet evidence
    /// of a schema mismatch. Walking it to its closing quote is what tells the
    /// two apart, and it reports the truncation itself. The cursor then goes
    /// back to the key's first byte, so the position this error carries names
    /// what was not recognized.
    #[inline]
    fn unknown_key(&mut self) -> PResult<()> {
        let key = self.idx;
        self.skip_string_body()?;
        self.idx = key;
        Err(ErrorCode::UnknownKey)
    }

    /// The member loop [`Self::read_object`] and [`Self::read_object_rest`]
    /// share, the cursor sitting on a member's opening quote.
    ///
    /// Returns the fields filled, for the caller to check against the ones
    /// that had to be. The closing brace is consumed here; the `leave` that
    /// balances the caller's `enter` is not, both callers having a
    /// [`require_fields`](Self::require_fields) to run after it.
    #[inline]
    fn object_members<T: ReadObject<'de>>(&mut self, value: &mut T) -> PResult<u64> {
        let mut seen = 0u64;
        loop {
            self.object_member::<T>(value, &mut seen)?;
            if !self.comma_or_close(b'}')? {
                return Ok(seen);
            }
        }
    }

    /// One member, the cursor sitting on its opening quote: hash the key to a
    /// candidate index, let the generated dispatch confirm it and parse the
    /// value, and note the field in `seen` if it was one.
    #[inline]
    fn object_member<T: ReadObject<'de>>(&mut self, value: &mut T, seen: &mut u64) -> PResult<()> {
        let map = T::MAP;
        let n = map.n as usize;
        self.expect(b'"', ErrorCode::ExpectedQuote)?;

        // The hash indexes every key, aliases included; the dispatch has an
        // arm per field, so an alias goes back to the field it fills first.
        let mut index = map.lookup(T::KEYS, self.rest());
        let matched = if index < n {
            index = resolve_key::<T>(index);
            T::read_field(value, index, self)?
        } else {
            false
        };
        if Fields::<O, T>::TRACK && matched {
            *seen |= Fields::<O, T>::seen(index);
        }
        if !matched {
            if O::ERROR_ON_UNKNOWN_KEYS {
                return self.unknown_key();
            }
            self.skip_unknown_member()?;
        }
        Ok(())
    }

    /// The members a late tag pushed aside, read into the same value once the
    /// members after the tag are done.
    ///
    /// The cursor is past the object's closing brace and goes back there
    /// afterwards. The run ends at the tag's key, which is the one member of
    /// the object that was already consumed, so a comma always follows the
    /// last member read here.
    fn deferred_members<T: ReadObject<'de>>(
        &mut self,
        value: &mut T,
        run: Deferred,
    ) -> PResult<u64> {
        let resume = self.idx;
        self.idx = run.start;
        let mut seen = 0u64;
        while self.idx != run.end {
            self.object_member::<T>(value, &mut seen)?;
            if !self.comma_or_close(b'}')? {
                return Err(ErrorCode::ExpectedTag);
            }
        }
        self.idx = resume;
        Ok(seen)
    }

    /// The deferred run, if it is this object's to read.
    ///
    /// The innermost run is the top of the stack, and only the object that
    /// pushed it is at its depth when the payload ends, so a depth match is
    /// ownership.
    #[inline(always)]
    fn take_deferred(&mut self) -> Option<Deferred> {
        match self.deferred.last() {
            Some(run) if run.depth == self.depth => self.deferred.pop(),
            _ => None,
        }
    }

    /// Scan an object whose first key was not the tag for the member that is,
    /// leaving the cursor on the tag's value and noting where the members it
    /// stepped over begin and end.
    ///
    /// The cursor starts at `first`, the first key's opening quote. A tag no
    /// member carries is [`ErrorCode::ExpectedTag`] against that first key.
    fn find_late_tag(&mut self, tag: &'static str, first: usize) -> PResult<()> {
        let mut at = first;
        loop {
            self.idx = at;
            self.expect(b'"', ErrorCode::ExpectedQuote)?;
            if self.match_key(tag) {
                self.deferred.push(Deferred {
                    start: first,
                    end: at,
                    depth: self.depth,
                });
                return Ok(());
            }
            self.skip_unknown_member()?;
            if !self.comma_or_close(b'}')? {
                self.idx = first;
                return Err(ErrorCode::ExpectedTag);
            }
            at = self.idx;
        }
    }

    /// Refuse an object that ended with a required field never filled.
    ///
    /// Compiles to nothing where nothing is required, the mask then being a
    /// constant zero and `seen` a constant zero with it.
    #[inline]
    fn require_fields<T: Keys>(&mut self, seen: u64, open: usize) -> PResult<()> {
        let mask = Fields::<O, T>::MASK;
        if seen & mask != mask {
            // Back to the opening brace: the cursor is past the object by now,
            // and what is incomplete is the object, not the byte after it. The
            // offset can therefore only name the object, so the key of the
            // member it lacks is carried alongside it.
            self.idx = open;
            self.error_key = Fields::<O, T>::missing(seen);
            return Err(ErrorCode::MissingKey);
        }
        Ok(())
    }

    /// The cursor sits just past a key's opening quote and the key is not one
    /// of ours. Discard the key and its value.
    fn skip_unknown_member(&mut self) -> PResult<()> {
        self.skip_string_body()?;
        self.colon()?;
        self.skip_value()
    }

    /// Read a JSON enum into a type declared with `unit_enum!` or
    /// `tagged_enum!`.
    ///
    /// Two forms, told apart by the first byte. A bare `"Name"` is a variant
    /// carrying nothing; a `{"Name":value}` is one carrying a value, and the
    /// object holds that single member and no other. Either way the name is
    /// hashed to a candidate variant, and the generated dispatch confirms it.
    ///
    /// A name no variant claims is an
    /// [`ErrorCode::UnknownVariant`] under every policy, including
    /// [`SkipUnknown`](crate::SkipUnknown). Stepping over an unknown object
    /// key still leaves the object readable; stepping over an unknown variant
    /// would leave the value itself undecided, so there is nothing to fall
    /// back to.
    pub fn read_enum<T: ReadEnum<'de>>(&mut self, value: &mut T) -> PResult<()> {
        self.skip_ws();
        match self.peek() {
            Some(b'"') => {
                self.idx += 1;
                self.dispatch_variant(value, T::read_name)
            }
            Some(b'{') => {
                // Where the object begins, so an object that holds no tag is
                // reported against the object rather than against the brace
                // that closed it.
                let open = self.idx;
                self.idx += 1;
                self.nested(|p| {
                    p.skip_ws();
                    // The tag is the object's whole content, so no members
                    // names no variant exactly as two do.
                    if p.peek() == Some(b'}') {
                        p.idx = open;
                        return Err(ErrorCode::ExpectedVariant);
                    }
                    p.expect(b'"', ErrorCode::ExpectedQuote)?;
                    p.dispatch_variant(value, T::read_payload)?;
                    // A comma here is that second member.
                    if p.comma_or_close(b'}')? {
                        p.idx = open;
                        return Err(ErrorCode::ExpectedVariant);
                    }
                    Ok(())
                })
            }
            // A document that ended is not a document that held the wrong
            // thing, and every other reader here tells the two apart.
            Some(_) => Err(ErrorCode::ExpectedVariant),
            None => Err(ErrorCode::UnexpectedEnd),
        }
    }

    /// The half [`Self::read_enum`]'s two arms share, and
    /// [`Self::read_internally_tagged`] with them: hash the name at the cursor,
    /// hand the candidate to `take`, and report a name nothing claimed against
    /// the name itself.
    ///
    /// Bounded on [`Variants`] rather than on [`ReadEnum`], which is all the
    /// body needs and is what lets the internally tagged reader share it.
    #[inline]
    fn dispatch_variant<T, F>(&mut self, value: &mut T, take: F) -> PResult<()>
    where
        T: Variants,
        F: FnOnce(&mut T, usize, &mut Self) -> PResult<bool>,
    {
        let map = T::MAP;
        // Where the name begins. `read_name` and `read_payload` consume it
        // only once they have matched it, but they are safe traits and nothing
        // obliges them to, so the position is restored rather than assumed.
        let at = self.idx;
        let index = map.lookup(T::VARIANTS, self.rest());
        if index < map.n as usize && take(value, resolve_variant::<T>(index), self)? {
            return Ok(());
        }
        // `match_key` fails identically for a name that differs and for one
        // the input ended in the middle of, so reaching here is not yet
        // evidence of a schema mismatch. Walking the name to its closing quote
        // is what tells the two apart, and it reports the truncation itself.
        // This is `read_object`'s step, for `read_object`'s reason.
        self.idx = at;
        self.skip_string_body()?;
        // Back to the first byte of the name, so the position this error
        // carries names what was not recognized.
        self.idx = at;
        Err(ErrorCode::UnknownVariant)
    }

    /// Read a JSON object into a type declared with a tag clause:
    /// `tagged_enum!(.. as tag "..")`.
    ///
    /// One form rather than [`read_enum`](Self::read_enum)'s two: an object
    /// one of whose members is the tag naming the variant, and whose other
    /// members are that variant's own fields.
    ///
    /// A tag that comes first costs one pass. One that comes later is found
    /// by stepping over the members before it, which are then read after
    /// the members that follow it, so a document whose keys were sorted
    /// reads the same as one that put the tag first. The members before the
    /// tag are walked twice, once to step over them and once to read them,
    /// and because they are read last, a key that appears both before and
    /// after the tag keeps the earlier value where the tag-first form keeps
    /// the later. A payload member that is itself tagged late stacks its
    /// own run on this one. An object with no tag at all is
    /// [`ErrorCode::ExpectedTag`], reported against its first key.
    ///
    /// A tag that names no variant is [`ErrorCode::UnknownVariant`] under
    /// every policy, for the reason [`read_enum`](Self::read_enum) gives.
    pub fn read_internally_tagged<T: ReadInternallyTagged<'de>>(
        &mut self,
        value: &mut T,
    ) -> PResult<()> {
        self.skip_ws();
        // Where the object begins, so a payload missing a required member is
        // reported against the object, as it is for a struct.
        let open = self.idx;
        self.expect(b'{', ErrorCode::ExpectedBrace)?;
        // The level entered below is left by the `read_object_rest` or
        // `finish_internally_tagged` the generated arm ends in, and a failure
        // may or may not have got that far. So rather than work out which,
        // a failure puts back the depth it found, and drops any late-tag run
        // it pushed: one left on the stack would be taken by the next object
        // read at its depth, which would then read another object's members.
        let depth = self.depth;
        let runs = self.deferred.len();
        let result = self.tagged_object::<T>(value, open);
        if result.is_err() {
            self.depth = depth;
            self.deferred.truncate(runs);
        }
        result
    }

    /// [`read_internally_tagged`](Self::read_internally_tagged) past the
    /// opening brace, which is `open`.
    #[inline(always)]
    fn tagged_object<T: ReadInternallyTagged<'de>>(
        &mut self,
        value: &mut T,
        open: usize,
    ) -> PResult<()> {
        self.enter()?;
        self.skip_ws();

        // No members at all: there is no tag, and so no variant. Reported
        // against the object, there being no member to point at.
        if self.peek() == Some(b'}') {
            self.idx = open;
            return Err(ErrorCode::ExpectedTag);
        }

        // Where the first member's key begins, which is what a tag that is not
        // here is reported against.
        let first = self.idx;
        self.expect(b'"', ErrorCode::ExpectedQuote)?;
        if !self.match_key(T::TAG) {
            self.find_late_tag(T::TAG, first)?;
        }
        self.colon()?;
        // The tag's value names the variant, so it is a string or it is
        // nothing this can dispatch on. Reported against the whole member: the
        // key was right and the value under it was not a name.
        match self.peek() {
            Some(b'"') => self.idx += 1,
            Some(_) => {
                self.idx = first;
                return Err(ErrorCode::ExpectedTag);
            }
            None => return Err(ErrorCode::UnexpectedEnd),
        }

        // From here the generated arm owns the rest of the object, closing
        // brace included, because only it knows the payload's type. The
        // lookup, and a name nothing claims, are `read_enum`'s exactly.
        self.dispatch_variant(value, |v, i, p| T::read_variant(v, i, p, open))
    }

    /// Read a JSON array into a type declared with `array!`.
    ///
    /// Position is the whole schema, so there is no key to hash and none to
    /// confirm: element `i` goes to field `i`, and the only thing to check is
    /// that the document held exactly as many as the struct has.
    #[inline]
    pub fn read_array<T: ReadArray<'de>>(&mut self, value: &mut T) -> PResult<()> {
        let count = self.read_seq(|p, i| value.read_element(i, p))?;
        if count != T::LEN {
            return Err(ErrorCode::ArrayLengthMismatch);
        }
        Ok(())
    }

    /// Drive a JSON array, calling `element` once per entry.
    ///
    /// `element` receives the zero-based position so container implementations
    /// can reuse storage they already hold.
    #[inline]
    pub fn read_seq<F>(&mut self, mut element: F) -> PResult<usize>
    where
        F: FnMut(&mut Self, usize) -> PResult<()>,
    {
        self.skip_ws();
        self.expect(b'[', ErrorCode::ExpectedBracket)?;
        self.nested(|p| {
            p.skip_ws();
            if p.try_byte(b']') {
                return Ok(0);
            }

            let mut count = 0usize;
            loop {
                element(p, count)?;
                count += 1;
                if !p.comma_or_close(b']')? {
                    return Ok(count);
                }
            }
        })
    }

    /// Drive a JSON object as a map, calling `entry` with each key.
    ///
    /// The key is passed as a borrowed `&'de str` when it has no escapes, which
    /// is the overwhelmingly common case, so map keys usually cost no
    /// allocation beyond the map's own.
    #[inline]
    pub fn read_map<F>(&mut self, mut entry: F) -> PResult<()>
    where
        F: FnMut(&mut Self, JsonStr<'de>) -> PResult<()>,
    {
        self.read_map_located(|p, key, _| entry(p, key))
    }

    /// [`read_map`](Self::read_map), telling the caller where each key begins.
    ///
    /// The offset is the key's first byte, just inside the opening quote. That
    /// is the same byte [`ErrorCode::UnknownKey`] reports, so a reader that
    /// refuses a key here can hand the offset straight to [`Error`] and the
    /// message will name what this callback saw.
    ///
    /// [`read_map`](Self::read_map) cannot report this, its callback running
    /// after the colon, and [`position`](Self::position) by then names the
    /// value. Nor can it be recovered by driving the object by hand: the
    /// depth counter that bounds nesting is not public, so an object of
    /// unknown shape has to be read through one of these two.
    ///
    /// ```
    /// use structio::{Error, ErrorCode, json::Parser};
    ///
    /// let doc = r#"{"a":1,"nope":2}"#;
    /// let mut refused = None;
    ///
    /// Parser::new(doc)
    ///     .read_map_located(|p, key, at| {
    ///         if key.as_str() != "a" {
    ///             refused = Some(Error::new(ErrorCode::UnknownKey, at));
    ///         }
    ///         p.skip_value()
    ///     })
    ///     .unwrap();
    ///
    /// let e = refused.unwrap();
    /// assert_eq!(e.key_in(doc).unwrap().as_str(), "nope");
    /// ```
    ///
    /// [`Error`]: crate::Error
    /// [`ErrorCode::UnknownKey`]: crate::ErrorCode::UnknownKey
    #[inline]
    pub fn read_map_located<F>(&mut self, mut entry: F) -> PResult<()>
    where
        F: FnMut(&mut Self, JsonStr<'de>, usize) -> PResult<()>,
    {
        self.skip_ws();
        self.expect(b'{', ErrorCode::ExpectedBrace)?;
        self.nested(|p| {
            p.skip_ws();
            if p.try_byte(b'}') {
                return Ok(());
            }

            loop {
                p.expect(b'"', ErrorCode::ExpectedQuote)?;
                let at = p.idx;
                let key = p.read_string_body()?;
                p.colon()?;
                entry(p, key, at)?;
                if !p.comma_or_close(b'}')? {
                    return Ok(());
                }
            }
        })
    }

    // -----------------------------------------------------------------------
    // Scalars
    // -----------------------------------------------------------------------

    /// Read `true` or `false`.
    ///
    /// Without a branch on which it is. A column of bools is the one place a
    /// branch on the value mispredicts on about every other element, and the
    /// mispredict costs more than the whole compare. The first byte picks the
    /// literal to expect, through selects rather than a branch, and the one
    /// branch left is the compare against it, which is taken only for input
    /// that is not a bool at all. Written with `|` on two compares instead,
    /// the compiler turned the pair back into a branch on each, which put the
    /// mispredict back with a bounds test on top.
    ///
    /// The test needs eight readable bytes; a literal ending within the last
    /// seven bytes of the document, and anything that is not a literal, takes
    /// the byte-at-a-time path.
    #[inline(always)]
    pub fn read_bool(&mut self) -> PResult<bool> {
        use core::hint::select_unpredictable as select;
        const TRUE: u64 = u64::from_le_bytes(*b"true\0\0\0\0");
        const FALSE: u64 = u64::from_le_bytes(*b"false\0\0\0");
        let i = self.idx;
        if i + 8 <= self.bytes.len() {
            // SAFETY: `i + 8 <= self.bytes.len()`.
            let word = unsafe { load_u64(self.bytes, i) };
            let is_f = word as u8 == b'f';
            let want = select(is_f, FALSE, TRUE);
            let mask = select(is_f, 0xFF_FFFF_FFFF, 0xFFFF_FFFF);
            if word & mask == want {
                self.idx = i + select(is_f, 5, 4);
                return Ok(!is_f);
            }
        }
        let (value, end) = read_bool_slow(self.bytes, i)?;
        self.idx = end;
        Ok(value)
    }

    #[inline(always)]
    pub(crate) fn expect_lit(&mut self, lit: &[u8], code: ErrorCode) -> PResult<()> {
        let n = lit.len();
        if self.remaining() >= n && &self.bytes[self.idx..self.idx + n] == lit {
            self.idx += n;
            Ok(())
        } else {
            Err(code)
        }
    }

    /// Consume `null`, reporting whether it was there. Non-consuming otherwise.
    #[inline(always)]
    pub fn try_null(&mut self) -> PResult<bool> {
        if self.peek() == Some(b'n') {
            self.expect_lit(b"null", ErrorCode::ExpectedNull)?;
            Ok(true)
        } else {
            Ok(false)
        }
    }

    /// Always inlined, like [`read_i64`](Self::read_i64) and for the same
    /// reason: these are what an array of integers calls per element, and the
    /// cost of a call there is not the call but the parser's cursor, which has
    /// to be spilled to the stack and reloaded around it. Left as a hint, the
    /// signed reader stops being inlined the moment anything downstream of it
    /// grows, and the array read loses about a fifth of its throughput without
    /// any source change nearby to explain it.
    ///
    /// `-0` reads as `0`, as it does into a signed type. A minus sign in front
    /// of any other number is [`NumberOutOfRange`](ErrorCode::NumberOutOfRange).
    #[inline(always)]
    pub fn read_u64(&mut self) -> PResult<u64> {
        let v = parse_unsigned_u64(self.bytes, &mut self.idx)?;
        reject_float_tail(self.bytes, self.idx)?;
        Ok(v)
    }

    #[inline(always)]
    pub fn read_i64(&mut self) -> PResult<i64> {
        let v = parse_i64(self.bytes, &mut self.idx)?;
        reject_float_tail(self.bytes, self.idx)?;
        Ok(v)
    }

    /// Always inlined, as [`read_u64`](Self::read_u64) is and for the same
    /// reason. The float path is larger than the integer one, and left as a
    /// hint it is the call an array of floats makes per element.
    #[inline(always)]
    pub fn read_f64(&mut self) -> PResult<f64> {
        parse_float::<f64>(self.bytes, &mut self.idx)
    }

    #[inline(always)]
    pub fn read_f32(&mut self) -> PResult<f32> {
        parse_float::<f32>(self.bytes, &mut self.idx)
    }

    /// Parse a 128-bit unsigned integer, taking a sign as
    /// [`read_u64`](Self::read_u64) does.
    pub fn read_u128(&mut self) -> PResult<u128> {
        let v = parse_unsigned_u128(self.bytes, &mut self.idx)?;
        reject_float_tail(self.bytes, self.idx)?;
        Ok(v)
    }

    /// Parse a 128-bit signed integer.
    pub fn read_i128(&mut self) -> PResult<i128> {
        let negative = self.peek() == Some(b'-');
        self.idx += negative as usize;
        let magnitude = parse_u128(self.bytes, &mut self.idx)?;
        let v = if negative {
            // `i128::MIN` has no positive counterpart, so compare before
            // negating.
            if magnitude > (i128::MAX as u128) + 1 {
                return Err(out_of_range(self.bytes, self.idx));
            }
            (magnitude as i128).wrapping_neg()
        } else {
            if magnitude > i128::MAX as u128 {
                return Err(out_of_range(self.bytes, self.idx));
            }
            magnitude as i128
        };
        reject_float_tail(self.bytes, self.idx)?;
        Ok(v)
    }

    /// Borrow a number's text out of the input, without converting it.
    ///
    /// The token is validated against the JSON number grammar and the cursor
    /// is left just past it, exactly as [`read_f64`](Self::read_f64) leaves
    /// it; what comes back is the literal itself, sign and exponent included.
    ///
    /// This is for a scalar none of the conversions above can hold: a
    /// fixed-point or decimal type, an arbitrary-precision integer, a
    /// rational. Reading such a value as an `f64` and converting is not an
    /// implementation of it, since the rounding is the thing the type exists
    /// to avoid; the digits are what the caller needs, so the digits are what
    /// this returns. [`Writer::write_number_str`](crate::json::Writer::write_number_str)
    /// is the other half.
    ///
    /// BEVE has no untyped number, so a type described this way has to pick a
    /// binary form of its own; there is no equivalent on
    /// [`beve::Reader`](crate::beve::Reader) to pair with.
    ///
    /// ```
    /// use structio::{ErrorCode, Options, from_str, json, to_string};
    ///
    /// /// Stands in for a decimal type. What matters is that the digits
    /// /// arrive whole; how one stores them is its own business.
    /// #[derive(Default)]
    /// struct Decimal(String);
    ///
    /// impl<'de> json::Read<'de> for Decimal {
    ///     fn read<O: Options>(&mut self, p: &mut json::Parser<'de, O>) -> Result<(), ErrorCode> {
    ///         self.0.clear();
    ///         self.0.push_str(p.read_number_str()?);
    ///         Ok(())
    ///     }
    /// }
    ///
    /// impl json::Write for Decimal {
    ///     fn write<O: Options>(&self, w: &mut json::Writer<'_, O>) {
    ///         w.write_number_str(&self.0);
    ///     }
    /// }
    ///
    /// // Past an `f64`'s range and past its precision, and rounded by neither.
    /// let text = "-1.2345678901234567890123e400";
    /// let d: Decimal = from_str(text).unwrap();
    /// assert_eq!(d.0, text);
    /// assert_eq!(to_string(&d), text);
    ///
    /// // A token, not a span: what is not a number is refused here rather
    /// // than by whoever parses the digits next.
    /// assert!(from_str::<Decimal>("01").is_err());
    /// ```
    #[inline]
    pub fn read_number_str(&mut self) -> PResult<&'de str> {
        let start = self.idx;
        scan_number(self.bytes, &mut self.idx)?;
        // SAFETY: the input was a `&str`, and the scanner accepts only ASCII
        // bytes, so both ends of this range are char boundaries and the range
        // is valid UTF-8.
        Ok(unsafe { core::str::from_utf8_unchecked(&self.bytes[start..self.idx]) })
    }

    // -----------------------------------------------------------------------
    // Strings
    // -----------------------------------------------------------------------

    /// Scan a string body starting at `from` (just past the opening quote).
    ///
    /// `Ok(Ok(text))` is the common case: no escapes, so the text is a subslice
    /// of the document and the cursor has moved past the closing quote.
    /// `Ok(Err(pos))` reports the first escape at `pos` and leaves the cursor
    /// alone, so the caller can decide whether to expand it or refuse.
    ///
    /// The three public string readers differ only in what they do with those
    /// two outcomes, so the scan, the bounds, and the one unchecked UTF-8
    /// conversion all live here.
    #[inline(always)]
    fn scan_body(&mut self, from: usize) -> PResult<::core::result::Result<&'de str, usize>> {
        match scan_string(self.bytes, from) {
            Some((pos, b'"')) => {
                self.idx = pos + 1;
                // SAFETY: the input was a `&str` and `"` is ASCII, so this
                // range starts and ends on char boundaries and is valid UTF-8.
                Ok(Ok(unsafe {
                    core::str::from_utf8_unchecked(&self.bytes[from..pos])
                }))
            }
            Some((pos, b'\\')) => Ok(Err(pos)),
            Some(_) => Err(ErrorCode::ControlCharacterInString),
            None => Err(ErrorCode::UnexpectedEnd),
        }
    }

    /// Read a complete JSON string, including its quotes.
    #[inline]
    pub fn read_string(&mut self) -> PResult<JsonStr<'de>> {
        self.expect(b'"', ErrorCode::ExpectedQuote)?;
        self.read_string_body()
    }

    /// Read a string whose opening quote has already been consumed.
    ///
    /// Returns a borrowed slice when there are no escapes. Only a string that
    /// actually contains an escape pays for an allocation.
    #[inline]
    pub fn read_string_body(&mut self) -> PResult<JsonStr<'de>> {
        let start = self.idx;
        match self.scan_body(start)? {
            Ok(s) => Ok(JsonStr::Borrowed(s)),
            Err(first) => {
                let mut out = String::new();
                self.unescape_into(start, first, &mut out)?;
                Ok(JsonStr::Owned(out))
            }
        }
    }

    /// Read a string into an existing `String`, reusing its allocation.
    ///
    /// Reusing the buffer is why repeated reads into the same value do not
    /// allocate, which is the same reason Glaze reads into an existing object
    /// rather than returning a fresh one.
    #[inline]
    pub fn read_string_into(&mut self, out: &mut String) -> PResult<()> {
        self.expect(b'"', ErrorCode::ExpectedQuote)?;
        let start = self.idx;
        match self.scan_body(start)? {
            Ok(s) => {
                out.clear();
                out.push_str(s);
                Ok(())
            }
            Err(first) => {
                out.clear();
                self.unescape_into(start, first, out)
            }
        }
    }

    /// Borrow a string slice directly out of the input, refusing to allocate.
    #[inline]
    pub fn read_str(&mut self) -> PResult<&'de str> {
        self.expect(b'"', ErrorCode::ExpectedQuote)?;
        let start = self.idx;
        match self.scan_body(start)? {
            Ok(s) => Ok(s),
            Err(_) => Err(ErrorCode::EscapeInBorrowedString),
        }
    }

    /// Expand a string containing escapes into `out`.
    ///
    /// `start` is just past the opening quote and `first` is the backslash the
    /// caller's scan already located, so the run between them is copied without
    /// being scanned a second time.
    fn unescape_into(&mut self, start: usize, first: usize, out: &mut String) -> PResult<()> {
        // SAFETY: every byte range appended below is either a slice of the
        // original `&str` delimited by ASCII bytes, or the UTF-8 encoding of a
        // `char`, so `out` stays valid UTF-8 throughout.
        let bytes = unsafe { out.as_mut_vec() };
        bytes.extend_from_slice(&self.bytes[start..first]);
        let mut i = self.expand_escape(first + 1, bytes)?;
        loop {
            let stop = match scan_string(self.bytes, i) {
                Some((pos, _)) => pos,
                None => return Err(ErrorCode::UnexpectedEnd),
            };
            bytes.extend_from_slice(&self.bytes[i..stop]);
            match self.bytes[stop] {
                b'"' => {
                    self.idx = stop + 1;
                    return Ok(());
                }
                b'\\' => {
                    i = self.expand_escape(stop + 1, bytes)?;
                }
                _ => return Err(ErrorCode::ControlCharacterInString),
            }
        }
    }

    /// Expand one escape starting at `i` (just past the backslash). Returns the
    /// index of the first byte after it.
    fn expand_escape(&self, i: usize, out: &mut Vec<u8>) -> PResult<usize> {
        let (ch, next) = self.decode_escape(i)?;
        // An ASCII character is its own one byte. Every single-character
        // escape stands for one, and with `decode_escape` inlined each of
        // those arms hands this test a constant.
        if ch.is_ascii() {
            out.push(ch as u8);
        } else {
            let mut buf = [0u8; 4];
            out.extend_from_slice(ch.encode_utf8(&mut buf).as_bytes());
        }
        Ok(next)
    }

    /// Decode one escape starting at `i` (just past the backslash): the
    /// character it stands for, and the index of the first byte after it.
    ///
    /// The one statement of which escapes JSON has and what each means. The
    /// reader expands through it and the checked walk only asks it whether an
    /// escape is one, so what [`Raw`](crate::json::Raw) accepts and what a
    /// string reader accepts cannot drift apart.
    #[inline(always)]
    fn decode_escape(&self, i: usize) -> PResult<(char, usize)> {
        let c = *self.bytes.get(i).ok_or(ErrorCode::UnexpectedEnd)?;
        let ch = match c {
            b'"' => '"',
            b'\\' => '\\',
            b'/' => '/',
            b'b' => '\u{8}',
            b'f' => '\u{c}',
            b'n' => '\n',
            b'r' => '\r',
            b't' => '\t',
            b'u' => return self.read_unicode_escape(i + 1),
            _ => return Err(ErrorCode::InvalidEscape),
        };
        Ok((ch, i + 1))
    }

    /// Decode `\uXXXX`, joining a surrogate pair when one is present.
    fn read_unicode_escape(&self, i: usize) -> PResult<(char, usize)> {
        let hi = self.read_hex4(i)?;
        let mut next = i + 4;

        if (0xD800..0xDC00).contains(&hi) {
            // High surrogate: a low surrogate must follow, as its own escape.
            if self.bytes.get(next) != Some(&b'\\') || self.bytes.get(next + 1) != Some(&b'u') {
                return Err(ErrorCode::InvalidSurrogate);
            }
            let lo = self.read_hex4(next + 2)?;
            if !(0xDC00..0xE000).contains(&lo) {
                return Err(ErrorCode::InvalidSurrogate);
            }
            next += 6;
            let cp = 0x1_0000 + ((hi - 0xD800) << 10) + (lo - 0xDC00);
            let ch = char::from_u32(cp).ok_or(ErrorCode::InvalidSurrogate)?;
            return Ok((ch, next));
        }
        if (0xDC00..0xE000).contains(&hi) {
            // An unpaired low surrogate is not a scalar value.
            return Err(ErrorCode::InvalidSurrogate);
        }
        let ch = char::from_u32(hi).ok_or(ErrorCode::InvalidSurrogate)?;
        Ok((ch, next))
    }

    #[inline]
    fn read_hex4(&self, i: usize) -> PResult<u32> {
        if i + 4 > self.bytes.len() {
            return Err(ErrorCode::UnexpectedEnd);
        }
        let mut v = 0u32;
        for k in 0..4 {
            let d = match self.bytes[i + k] {
                c @ b'0'..=b'9' => (c - b'0') as u32,
                c @ b'a'..=b'f' => (c - b'a' + 10) as u32,
                c @ b'A'..=b'F' => (c - b'A' + 10) as u32,
                _ => return Err(ErrorCode::InvalidEscape),
            };
            v = (v << 4) | d;
        }
        Ok(v)
    }

    /// Step past a string body whose opening quote is already consumed,
    /// without materializing it or looking inside its escapes.
    #[inline(always)]
    fn skip_string_body(&mut self) -> PResult<()> {
        self.walk_string_body::<false>()
    }

    /// Step past a string body whose opening quote is already consumed,
    /// without materializing it.
    ///
    /// One SWAR pass finds the closing quote, and finds a backslash or a
    /// control character on the way for free, so the escape is dealt with and
    /// the control character refused at no extra cost. The cursor stays on the
    /// body when this fails, so the error names the string rather than wherever
    /// the scan gave up inside it, which is also where a string reader leaves
    /// it.
    ///
    /// `CHECK_ESCAPES` decides what dealing with an escape means. Off, the
    /// backslash and the byte after it are stepped over, which is all it takes
    /// to keep an escaped quote from ending the scan. On, the escape is decoded
    /// by [`decode_escape`](Self::decode_escape) and the character thrown away,
    /// so it is refused exactly where and exactly as reading the string would
    /// refuse it. Only a string holding a backslash reaches either arm, so the
    /// check costs the string without one nothing.
    fn walk_string_body<const CHECK_ESCAPES: bool>(&mut self) -> PResult<()> {
        let mut i = self.idx;
        loop {
            match scan_string(self.bytes, i) {
                Some((pos, b'"')) => {
                    self.idx = pos + 1;
                    return Ok(());
                }
                Some((pos, b'\\')) if CHECK_ESCAPES => {
                    i = self.decode_escape(pos + 1)?.1;
                }
                Some((pos, b'\\')) => {
                    // Step over the backslash and whatever it escapes, so an
                    // escaped quote does not end the scan.
                    i = pos + 2;
                    if i > self.bytes.len() {
                        return Err(ErrorCode::UnexpectedEnd);
                    }
                }
                Some(_) => return Err(ErrorCode::ControlCharacterInString),
                None => return Err(ErrorCode::UnexpectedEnd),
            }
        }
    }

    // -----------------------------------------------------------------------
    // Skipping
    // -----------------------------------------------------------------------

    /// Discard the next value, whatever it is.
    ///
    /// Structure is checked and content is not: a number is stepped over by
    /// the bytes it may be spelled with rather than held to the grammar, and
    /// an escape by its backslash rather than decoded, so `01` and `"\q"` both
    /// go by unrefused. Nothing reads what this discards, and a value that is
    /// read is refused by whatever reads it.
    #[inline]
    pub fn skip_value(&mut self) -> PResult<()> {
        self.walk_value::<false>()
    }

    /// Step over the next value, refusing any escape a string reader would
    /// refuse, in any string inside it, keys included.
    ///
    /// The walk behind [`Raw`](crate::json::Raw), which keeps what it steps
    /// over and so has to know it is JSON. Everything [`skip_value`] checks is
    /// checked the same way; the escapes are the difference, and they cost only
    /// the strings that have one. See
    /// [`walk_string_body`](Self::walk_string_body).
    ///
    /// [`skip_value`]: Self::skip_value
    #[inline]
    pub(crate) fn skip_value_checked(&mut self) -> PResult<()> {
        self.walk_value::<true>()
    }

    /// [`skip_value`](Self::skip_value), with what a string's escapes are held
    /// to left to `CHECK_ESCAPES`, and passed down to every string inside.
    fn walk_value<const CHECK_ESCAPES: bool>(&mut self) -> PResult<()> {
        self.skip_ws();
        match self.peek() {
            Some(b'{') => {
                self.idx += 1;
                self.nested(|p| {
                    p.skip_ws();
                    if p.try_byte(b'}') {
                        return Ok(());
                    }
                    loop {
                        p.expect(b'"', ErrorCode::ExpectedQuote)?;
                        p.walk_string_body::<CHECK_ESCAPES>()?;
                        p.colon()?;
                        p.walk_value::<CHECK_ESCAPES>()?;
                        if !p.comma_or_close(b'}')? {
                            return Ok(());
                        }
                    }
                })
            }
            Some(b'[') => {
                self.idx += 1;
                self.nested(|p| {
                    p.skip_ws();
                    if p.try_byte(b']') {
                        return Ok(());
                    }
                    loop {
                        p.walk_value::<CHECK_ESCAPES>()?;
                        if !p.comma_or_close(b']')? {
                            return Ok(());
                        }
                    }
                })
            }
            // Everything that is not a container is a scalar, and there is one
            // skipper for those; the whitespace it assumes away is behind the
            // cursor already.
            _ => self.walk_scalar::<CHECK_ESCAPES>(),
        }
    }

    /// Step over a scalar already at the cursor: a string, a number, or one of
    /// the three literals.
    ///
    /// [`skip_value`](Self::skip_value) with the containers taken out and the
    /// leading whitespace assumed away, for a caller that has dispatched on the
    /// byte itself and skipped the whitespace to find it. `skip_value` is that
    /// caller once it has ruled out a container, so there is one scalar skipper
    /// rather than one per walk.
    ///
    /// A number is stepped over by its alphabet rather than held to the
    /// grammar. Nothing here reads its value, and the two callers both have
    /// somewhere better for a malformed one to be caught: a skipped value is
    /// discarded, and a copied one is republished for whoever reads it next to
    /// reject. See
    /// [docs/design.md](https://github.com/matrix-research-inc/structio/blob/main/docs/design.md#prettifying-is-the-writer-not-a-second-layout)
    /// for the measurement behind that. An escape is stepped over too, as
    /// [`skip_value`](Self::skip_value) steps over one.
    #[inline]
    pub(crate) fn skip_scalar(&mut self) -> PResult<()> {
        self.walk_scalar::<false>()
    }

    /// [`skip_scalar`](Self::skip_scalar), with a string's escapes held to
    /// whatever `CHECK_ESCAPES` says; see
    /// [`walk_string_body`](Self::walk_string_body).
    #[inline]
    fn walk_scalar<const CHECK_ESCAPES: bool>(&mut self) -> PResult<()> {
        match self.peek() {
            Some(b'"') => {
                self.idx += 1;
                self.walk_string_body::<CHECK_ESCAPES>()
            }
            Some(b't') => self.expect_lit(b"true", ErrorCode::ExpectedTrue),
            Some(b'f') => self.expect_lit(b"false", ErrorCode::ExpectedFalse),
            Some(b'n') => self.expect_lit(b"null", ErrorCode::ExpectedNull),
            Some(c) if c == b'-' || c.is_ascii_digit() => {
                let mut i = self.idx;
                let n = self.bytes.len();
                while i < n {
                    match self.bytes[i] {
                        b'0'..=b'9' | b'-' | b'+' | b'.' | b'e' | b'E' => i += 1,
                        _ => break,
                    }
                }
                // The guard above admits only bytes the loop accepts, so at
                // least one was taken and the token is never empty.
                self.idx = i;
                Ok(())
            }
            None => Err(ErrorCode::UnexpectedEnd),
            Some(_) => Err(ErrorCode::UnexpectedCharacter),
        }
    }

    /// After the top-level value: only trailing whitespace is allowed.
    #[inline]
    pub fn finish(&mut self) -> PResult<()> {
        self.skip_ws();
        if self.idx == self.bytes.len() {
            Ok(())
        } else {
            Err(ErrorCode::TrailingContent)
        }
    }

    /// Read any value into `T`.
    #[inline(always)]
    pub fn read<T: Read<'de>>(&mut self, value: &mut T) -> PResult<()> {
        value.read(self)
    }
}

/// [`is_ws`] as a lookup rather than a comparison.
///
/// The comparisons do not stay comparisons: a four-way `matches!` becomes a
/// shift and a mask against a 64-bit set, and that needs a range guard in
/// front of it, since a byte of 64 or more would shift out of the word. The
/// load has no such problem. This is `glz::whitespace_table`, for the same
/// reason.
const WHITESPACE: [bool; 256] = {
    let mut t = [false; 256];
    t[b' ' as usize] = true;
    t[b'\t' as usize] = true;
    t[b'\n' as usize] = true;
    t[b'\r' as usize] = true;
    t
};

/// The four bytes JSON calls whitespace.
///
/// The one definition of it in the crate. The reader and the
/// [minifier](crate::minify) share a walk over runs of it, in
/// [`skip_ws_at`]; the stream splitter has its own, because its input grows
/// under it and a run can end in the middle of nothing. What none of them may
/// do is disagree about what whitespace is.
#[inline(always)]
pub(crate) const fn is_ws(c: u8) -> bool {
    WHITESPACE[c as usize]
}

/// Could this byte be part of a number or one of the three literals?
///
/// The alphabet those are spelled from, and so the answer to "would these two
/// tokens run together": `1` beside `2` is `12`, and `true` beside `false` is
/// one long word, while punctuation and a quote delimit themselves. The stream
/// splitter uses it to find where a bare top-level value ends, and the
/// [minifier](crate::minify) to know which whitespace it must not remove.
///
/// Deliberately generous. Neither caller is deciding whether a token is spelled
/// properly, only where it stops; the real parser makes that judgement when the
/// span reaches it.
#[inline(always)]
pub(crate) const fn scalar_byte(c: u8) -> bool {
    c.is_ascii_alphanumeric() || matches!(c, b'-' | b'+' | b'.')
}

/// First byte at or after `at` that is not whitespace.
///
/// The body of [`Parser::skip_ws`], reachable without a parser so that the
/// [minifier](crate::minify), which walks its input by index rather than by
/// cursor, draws the line between whitespace and a token exactly where the
/// reader draws it.
#[inline(always)]
pub(crate) fn skip_ws_at<O: Options>(data: &[u8], at: usize) -> usize {
    let mut i = at;
    while i < data.len() {
        match data[i] {
            c if is_ws(c) => i += 1,
            b'/' if O::ALLOW_COMMENTS => match skip_comment(data, i) {
                Some(after) => i = after,
                None => break,
            },
            _ => break,
        }
    }
    i
}

/// [`Parser::read_bool`] for a literal within seven bytes of the end of the
/// document, and for everything that is not one.
///
/// Takes the cursor and gives it back by value rather than borrowing the
/// parser, because a `&mut Parser` handed to an out-of-line call makes the
/// parser addressable, and an addressable parser keeps its cursor on the
/// stack for the whole of the array loop the call sits in. Cold, so that the
/// two literals' error paths stay out of that loop.
#[cold]
#[inline(never)]
fn read_bool_slow(data: &[u8], idx: usize) -> PResult<(bool, usize)> {
    let rest = &data[idx.min(data.len())..];
    match rest.first() {
        Some(b't') if rest.starts_with(b"true") => Ok((true, idx + 4)),
        Some(b't') => Err(ErrorCode::ExpectedTrue),
        Some(b'f') if rest.starts_with(b"false") => Ok((false, idx + 5)),
        Some(b'f') => Err(ErrorCode::ExpectedFalse),
        Some(_) => Err(ErrorCode::UnexpectedCharacter),
        None => Err(ErrorCode::UnexpectedEnd),
    }
}

/// Step over one comment, `data[at]` being its `/`.
///
/// `data` is the whole of the input, which is what lets a `//` running to the
/// end of it be a comment that ended: there is no newline to come. The
/// streaming splitter, whose input grows, has to answer that differently.
///
/// `Some(end)` is the first byte after it: for `//` the newline that ended it,
/// which the whitespace loop takes next, and for `/* */` the byte past the
/// closing slash. `None` means there is no complete comment here, either
/// because the `/` begins nothing or because a block comment was never closed,
/// and the cursor is left on the `/` so that the error names it.
///
/// Out of line so that [`Parser::skip_ws`], which is inlined at every token
/// boundary, stays the small loop it was.
#[inline]
pub(crate) fn skip_comment(data: &[u8], at: usize) -> Option<usize> {
    let body = at + 2;
    match data.get(at + 1)? {
        b'/' => Some(find_byte(data, body, b'\n').unwrap_or(data.len())),
        // A pair at a time. A comment is a rare, short thing next to the
        // document around it, and a two-byte terminator is not what the
        // word-at-a-time search in `swar` is shaped for.
        b'*' => {
            let end = data.get(body..)?.windows(2).position(|w| w == b"*/")?;
            Some(body + end + 2)
        }
        _ => None,
    }
}

/// A string read from the input, borrowed when it contained no escapes.
///
/// Deliberately not `Cow`: the borrowed case is the overwhelmingly common one,
/// and giving it a type of our own keeps that visible at every call site.
///
/// The variant is how the text got here, not what the text is. Both hold the
/// string the document meant, with the escapes already resolved, so equality,
/// hashing and [`Display`](core::fmt::Display) all go through
/// [`as_str`](Self::as_str) and ignore which one it is.
#[derive(Clone, Debug)]
pub enum JsonStr<'de> {
    Borrowed(&'de str),
    Owned(String),
}

impl<'de> JsonStr<'de> {
    #[inline(always)]
    pub fn as_str(&self) -> &str {
        match self {
            JsonStr::Borrowed(s) => s,
            JsonStr::Owned(s) => s,
        }
    }

    #[inline]
    pub fn into_string(self) -> String {
        match self {
            JsonStr::Borrowed(s) => s.to_owned(),
            JsonStr::Owned(s) => s,
        }
    }
}

/// The text, whichever variant carries it.
///
/// Deriving this would compare the variants first, so a document that wrote
/// `"a"` and one that wrote `"\u0061"` would come out holding different
/// strings. They wrote the same string, and spelled it differently.
impl PartialEq for JsonStr<'_> {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.as_str() == other.as_str()
    }
}

impl Eq for JsonStr<'_> {}

/// The text, for the same reason and by the same route as [`PartialEq`].
///
/// Hand-written rather than derived so that it agrees with that impl: a
/// derived `Hash` folds in the discriminant, and two keys that compare equal
/// across the variants would then hash apart and miss each other in a
/// `HashMap`. Looking a key up in the set of names a schema knows is the
/// obvious thing to do with what [`Error::key_in`](crate::Error::key_in) hands
/// back, so this type is a map key whether or not it was meant to be one.
impl core::hash::Hash for JsonStr<'_> {
    #[inline]
    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
        self.as_str().hash(state);
    }
}

impl fmt::Display for JsonStr<'_> {
    /// The string the document meant, with no quotes around it.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// First byte at or after `from` that ends or complicates a string: `"`, `\`,
/// or a control character. Returns it with its index.
///
/// One SWAR pass tests all three conditions over eight bytes at a time.
#[inline(always)]
fn scan_string(data: &[u8], from: usize) -> Option<(usize, u8)> {
    let n = data.len();
    let mut i = from;
    while i + 8 <= n {
        // SAFETY: `i + 8 <= n`, so the eight bytes read are in bounds.
        let m = escape_mask(unsafe { load_u64(data, i) });
        if m != 0 {
            let pos = i + first_match(m);
            return Some((pos, data[pos]));
        }
        i += 8;
    }
    while i < n {
        let c = data[i];
        if needs_escape(c) {
            return Some((i, c));
        }
        i += 1;
    }
    None
}