Skip to main content

nosj/
pointer.rs

1//! RFC 6901 JSON Pointer resolution: partial parsing's front door.
2//!
3//! Resolution is a forward byte cursor: it tokenizes only the navigation
4//! levels it walks through and steps over everything else. Sibling
5//! containers are skipped by [`crate::stage1::container_end`] (64-byte
6//! blocks classified exactly like indexing, but consuming only bracket
7//! bits, stopping at the matching closer, and building no index), so the
8//! cost of a query is proportional to how far into the document the
9//! target sits, not to the document's size. The matched value comes back
10//! as its raw text, ready to feed to any nosj entry point, or to keep
11//! as a lazy value.
12//!
13//! Miss semantics match `serde_json::Value::pointer`: a missing key, an
14//! out-of-range index, or a token that is not valid array-index syntax
15//! (`-`, `01`, non-digits) resolves to `Ok(None)`. Only malformed pointer
16//! *syntax* (a non-empty pointer without a leading `/`) is an error.
17//!
18//! Duplicate keys resolve to the **first** occurrence (streaming
19//! semantics; a last-wins map like serde's sees the last).
20//!
21//! The `_with` variants walk the grammar extensions of [`ParseOptions`],
22//! so documents accepted by [`crate::parse_with`] resolve too.
23
24use crate::cursor::ParseOptions;
25use crate::reader::{Buffers, ErrorKind, ParseError};
26use crate::scalars::{self, StrPart};
27use crate::stage1;
28
29/// Resolve `pointer` against `input`, returning the raw text of the
30/// matched value (`None` if the pointer doesn't match anything).
31///
32/// ```
33/// let mut bufs = nosj::Buffers::new();
34/// let doc = r#"{"users":[{"name":"ada"},{"name":"grace"}]}"#;
35/// let raw = nosj::pointer(doc, "/users/1/name", &mut bufs).unwrap();
36/// assert_eq!(raw, Some("\"grace\""));
37/// ```
38#[doc(alias = "get")]
39#[doc(alias = "dig")]
40#[doc(alias = "json_pointer")]
41pub fn pointer<'j>(
42    input: &'j str,
43    pointer: &str,
44    bufs: &mut Buffers,
45) -> Result<Option<&'j str>, ParseError> {
46    // SAFETY: &str is valid UTF-8.
47    unsafe { pointer_utf8_unchecked(input.as_bytes(), pointer, bufs) }
48}
49
50/// Like [`pointer()`], with grammar extensions from [`ParseOptions`].
51pub fn pointer_with<'j>(
52    input: &'j str,
53    pointer: &str,
54    bufs: &mut Buffers,
55    opts: ParseOptions,
56) -> Result<Option<&'j str>, ParseError> {
57    // SAFETY: &str is valid UTF-8.
58    unsafe { pointer_utf8_unchecked_with(input.as_bytes(), pointer, bufs, opts) }
59}
60
61/// Like [`pointer()`], for callers whose runtime vouches for UTF-8.
62///
63/// # Safety
64///
65/// `input` must be valid UTF-8.
66pub unsafe fn pointer_utf8_unchecked<'j>(
67    input: &'j [u8],
68    pointer: &str,
69    bufs: &mut Buffers,
70) -> Result<Option<&'j str>, ParseError> {
71    // SAFETY: forwarded contract.
72    unsafe { pointer_utf8_unchecked_with(input, pointer, bufs, ParseOptions::default()) }
73}
74
75/// Like [`pointer_utf8_unchecked`], with grammar extensions from
76/// [`ParseOptions`].
77///
78/// # Safety
79///
80/// `input` must be valid UTF-8.
81pub unsafe fn pointer_utf8_unchecked_with<'j>(
82    input: &'j [u8],
83    pointer: &str,
84    bufs: &mut Buffers,
85    opts: ParseOptions,
86) -> Result<Option<&'j str>, ParseError> {
87    if !pointer.is_empty() && !pointer.starts_with('/') {
88        return Err(ParseError {
89            offset: 0,
90            kind: ErrorKind::InvalidPointer,
91        });
92    }
93    // SAFETY: forwarded contract; the caller vouches `input` is UTF-8.
94    let range = unsafe { resolve(input, pointer, &mut bufs.scratch, opts) }?;
95    // SAFETY: `input` is valid UTF-8 and the range falls on token edges
96    // (ASCII boundaries).
97    Ok(range.map(|(start, end)| unsafe { std::str::from_utf8_unchecked(&input[start..end]) }))
98}
99
100#[inline(always)]
101fn skip_ws(input: &[u8], mut i: usize) -> usize {
102    while let Some(&b) = input.get(i) {
103        if matches!(b, b' ' | b'\t' | b'\n' | b'\r') {
104            i += 1;
105        } else {
106            break;
107        }
108    }
109    i
110}
111
112/// End offset of the value starting at `i` (whitespace already skipped).
113/// Scalars run their tokenizer (fully validated); containers are skipped
114/// structurally by [`stage1::container_end`].
115///
116/// # Safety
117///
118/// `input` must be valid UTF-8.
119unsafe fn value_end(
120    input: &[u8],
121    i: usize,
122    scratch: &mut Vec<u8>,
123    opts: ParseOptions,
124) -> Result<usize, ParseError> {
125    let eof = || ParseError::unexpected_end(input.len());
126    match *input.get(i).ok_or_else(eof)? {
127        // SAFETY: UTF-8 per this function's contract; `i` holds the `"`.
128        b'"' => unsafe { scalars::parse_string(input, i, scratch) }
129            .map(|(_, end)| end)
130            .map_err(|e| ParseError::scalar(e, i)),
131        b'-' | b'0'..=b'9' => scalars::parse_number(input, i)
132            .map(|(_, end)| end)
133            // `-Infinity` fails the number grammar first.
134            .or_else(|e| nan_keyword_end(input, i, opts, ParseError::scalar(e, i))),
135        b't' | b'f' | b'n' => scalars::parse_literal(input, i)
136            .map(|(_, end)| end)
137            .map_err(|e| ParseError::scalar(e, i)),
138        b'{' | b'[' => stage1::container_end(input, i).ok_or_else(eof),
139        _ => nan_keyword_end(input, i, opts, ParseError::unexpected_character(i)),
140    }
141}
142
143/// End offset of the `allow_nan` keyword at `i`, or the error the strict
144/// grammar reports there.
145#[cold]
146fn nan_keyword_end(
147    input: &[u8],
148    i: usize,
149    opts: ParseOptions,
150    strict: ParseError,
151) -> Result<usize, ParseError> {
152    if opts.allow_nan
153        && let Some((_, end)) = scalars::parse_nan_keyword(input, i)
154    {
155        return Ok(end);
156    }
157    Err(strict)
158}
159
160/// After a member's `,` (whitespace skipped, `i` on the next token):
161/// true when `opts` allow a trailing comma and `closer` ends the
162/// container right here.
163#[inline(always)]
164fn trailing_close(input: &[u8], i: usize, opts: ParseOptions, closer: u8) -> bool {
165    opts.allow_trailing_comma && input.get(i) == Some(&closer)
166}
167
168/// Walk the pointer tokens, returning the byte range of the match.
169///
170/// # Safety
171///
172/// `input` must be valid UTF-8.
173unsafe fn resolve(
174    input: &[u8],
175    pointer: &str,
176    scratch: &mut Vec<u8>,
177    opts: ParseOptions,
178) -> Result<Option<(usize, usize)>, ParseError> {
179    let mut i = skip_ws(input, 0);
180
181    if pointer.is_empty() {
182        // The whole document is the match; enforce a complete document
183        // like a full parse would.
184        // SAFETY: forwarded UTF-8 contract.
185        let end = unsafe { value_end(input, i, scratch, opts) }?;
186        let trail = skip_ws(input, end);
187        if trail != input.len() {
188            return Err(ParseError::trailing_characters(trail));
189        }
190        return Ok(Some((i, end)));
191    }
192
193    let mut tokens = pointer.split('/').skip(1).peekable();
194    while let Some(token) = tokens.next() {
195        let is_last = tokens.peek().is_none();
196        let value_pos = match input.get(i).copied() {
197            None => return Err(ParseError::unexpected_end(input.len())),
198            Some(b'{') => {
199                // SAFETY: forwarded UTF-8 contract.
200                unsafe { descend_object(input, i, token, scratch, opts) }?
201            }
202            Some(b'[') => {
203                // SAFETY: forwarded UTF-8 contract.
204                unsafe { descend_array(input, i, token, scratch, opts) }?
205            }
206            // A scalar cannot be descended into.
207            Some(_) => None,
208        };
209        let Some(value_pos) = value_pos else {
210            return Ok(None);
211        };
212        i = value_pos;
213        if is_last {
214            // SAFETY: forwarded UTF-8 contract.
215            let end = unsafe { value_end(input, i, scratch, opts) }?;
216            return Ok(Some((i, end)));
217        }
218    }
219    unreachable!("the token loop returns on its last iteration");
220}
221
222/// Resolve many pointers in **one forward pass**, returning raw slices
223/// positionally aligned with `pointers` (`None` where a pointer doesn't
224/// match). Sequential [`pointer()`] calls re-scan the document prefix per
225/// query; this walks it once, descending only into members some pointer
226/// still needs and skipping everything else at block speed.
227///
228/// Duplicate keys resolve first-match, like [`pointer()`]. The walk stops
229/// as soon as every pointer is resolved.
230///
231/// On **valid** JSON the result is exactly what resolving each pointer
232/// individually would produce. On *malformed* documents the batch may
233/// report an error where an individual [`pointer()`] call would return
234/// `Ok(None)`: one pass scans every byte *some* pointer needs, so it can
235/// reach malformed content that a lone query (which aborts at its first
236/// missing key) never would.
237///
238/// ```
239/// let mut bufs = nosj::Buffers::new();
240/// let doc = r#"{"a":1,"b":{"c":2},"d":[3,4]}"#;
241/// let got = nosj::pointers(doc, &["/d/1", "/a", "/x"], &mut bufs).unwrap();
242/// assert_eq!(got, [Some("4"), Some("1"), None]);
243/// ```
244#[doc(alias = "get_many")]
245pub fn pointers<'j>(
246    input: &'j str,
247    pointers: &[&str],
248    bufs: &mut Buffers,
249) -> Result<Vec<Option<&'j str>>, ParseError> {
250    // SAFETY: &str is valid UTF-8.
251    unsafe { pointers_utf8_unchecked(input.as_bytes(), pointers, bufs) }
252}
253
254/// Like [`pointers()`], with grammar extensions from [`ParseOptions`].
255pub fn pointers_with<'j>(
256    input: &'j str,
257    pointers: &[&str],
258    bufs: &mut Buffers,
259    opts: ParseOptions,
260) -> Result<Vec<Option<&'j str>>, ParseError> {
261    // SAFETY: &str is valid UTF-8.
262    unsafe { pointers_utf8_unchecked_with(input.as_bytes(), pointers, bufs, opts) }
263}
264
265/// Like [`pointers()`], for callers whose runtime vouches for UTF-8.
266///
267/// # Safety
268///
269/// `input` must be valid UTF-8.
270pub unsafe fn pointers_utf8_unchecked<'j>(
271    input: &'j [u8],
272    pointers: &[&str],
273    bufs: &mut Buffers,
274) -> Result<Vec<Option<&'j str>>, ParseError> {
275    // SAFETY: forwarded contract.
276    unsafe { pointers_utf8_unchecked_with(input, pointers, bufs, ParseOptions::default()) }
277}
278
279/// Like [`pointers_utf8_unchecked`], with grammar extensions from
280/// [`ParseOptions`].
281///
282/// # Safety
283///
284/// `input` must be valid UTF-8.
285pub unsafe fn pointers_utf8_unchecked_with<'j>(
286    input: &'j [u8],
287    pointers: &[&str],
288    bufs: &mut Buffers,
289    opts: ParseOptions,
290) -> Result<Vec<Option<&'j str>>, ParseError> {
291    // Tokenize (and unescape) every pointer up front: once per token,
292    // not once per level visit. The arena owns the tokens; queries borrow.
293    let arena: Vec<Vec<Token<'_>>> = pointers
294        .iter()
295        .map(|ptr| {
296            if ptr.is_empty() {
297                Vec::new()
298            } else {
299                ptr.split('/').skip(1).map(Token::parse).collect()
300            }
301        })
302        .collect();
303    let mut queries: Vec<Query<'_>> = Vec::with_capacity(pointers.len());
304    for (id, ptr) in pointers.iter().enumerate() {
305        if !ptr.is_empty() && !ptr.starts_with('/') {
306            return Err(ParseError {
307                offset: 0,
308                kind: ErrorKind::InvalidPointer,
309            });
310        }
311        queries.push(Query {
312            id,
313            tokens: &arena[id],
314        });
315    }
316
317    let mut results: Vec<Option<(usize, usize)>> = vec![None; pointers.len()];
318    let mut remaining = queries.len();
319    let start = skip_ws(input, 0);
320    // SAFETY: forwarded UTF-8 contract.
321    unsafe {
322        resolve_set(
323            input,
324            start,
325            &queries,
326            &mut results,
327            &mut remaining,
328            &mut bufs.scratch,
329            opts,
330        )
331    }?;
332    // Root pointers keep the single-pointer contract of validating a
333    // complete document; a root query always resolves, so its recorded
334    // end is always available.
335    if let Some(root) = pointers.iter().position(|p| p.is_empty()) {
336        let (_, end) = results[root].expect("the root pointer always matches");
337        let trail = skip_ws(input, end);
338        if trail != input.len() {
339            return Err(ParseError::trailing_characters(trail));
340        }
341    }
342    Ok(results
343        .into_iter()
344        // SAFETY: `input` is valid UTF-8 and the ranges fall on token
345        // edges (ASCII boundaries).
346        .map(|r| r.map(|(s, e)| unsafe { std::str::from_utf8_unchecked(&input[s..e]) }))
347        .collect())
348}
349
350/// One pre-tokenized pointer still being resolved: its slot in the
351/// results and the tokens below the current level.
352#[derive(Clone, Copy)]
353struct Query<'p> {
354    id: usize,
355    tokens: &'p [Token<'p>],
356}
357
358/// One pointer token, unescaped once, with its array-index reading
359/// precomputed.
360struct Token<'p> {
361    text: std::borrow::Cow<'p, str>,
362    /// `Some` when the raw token is valid index syntax (digits, no
363    /// leading zeros).
364    index: Option<usize>,
365}
366
367impl<'p> Token<'p> {
368    fn parse(raw: &'p str) -> Token<'p> {
369        let valid_index = !raw.is_empty()
370            && raw.bytes().all(|b| b.is_ascii_digit())
371            && (raw == "0" || !raw.starts_with('0'));
372        Token {
373            // `~1` -> `/`, then `~0` -> `~` (RFC 6901 order).
374            text: if raw.contains('~') {
375                raw.replace("~1", "/").replace("~0", "~").into()
376            } else {
377                raw.into()
378            },
379            index: if valid_index { raw.parse().ok() } else { None },
380        }
381    }
382}
383
384/// Resolve `queries` against the value at `i`. Returns `Some(end)` of the
385/// value, or `None` when every pointer in the whole batch has been
386/// resolved (the abort signal; no caller needs positions after that).
387///
388/// # Safety
389///
390/// `input` must be valid UTF-8.
391unsafe fn resolve_set(
392    input: &[u8],
393    i: usize,
394    queries: &[Query<'_>],
395    results: &mut Vec<Option<(usize, usize)>>,
396    remaining: &mut usize,
397    scratch: &mut Vec<u8>,
398    opts: ParseOptions,
399) -> Result<Option<usize>, ParseError> {
400    let deeper: Vec<Query<'_>> = queries
401        .iter()
402        .copied()
403        .filter(|q| !q.tokens.is_empty())
404        .collect();
405
406    let end = match input.get(i).copied() {
407        None => return Err(ParseError::unexpected_end(input.len())),
408        Some(b'{') if !deeper.is_empty() => {
409            // SAFETY: forwarded UTF-8 contract.
410            let walked =
411                unsafe { walk_object(input, i, &deeper, results, remaining, scratch, opts) }?;
412            match walked {
413                Some(end) => end,
414                None => return Ok(None),
415            }
416        }
417        Some(b'[') if !deeper.is_empty() => {
418            // SAFETY: forwarded UTF-8 contract.
419            let walked =
420                unsafe { walk_array(input, i, &deeper, results, remaining, scratch, opts) }?;
421            match walked {
422                Some(end) => end,
423                None => return Ok(None),
424            }
425        }
426        // Scalar, or a container no pointer descends into: one skip.
427        // SAFETY: forwarded UTF-8 contract.
428        _ => unsafe { value_end(input, i, scratch, opts) }?,
429    };
430
431    for q in queries {
432        if q.tokens.is_empty() {
433            results[q.id] = Some((i, end));
434            *remaining -= 1;
435        }
436    }
437    if *remaining == 0 {
438        return Ok(None);
439    }
440    Ok(Some(end))
441}
442
443/// Walk one object once, recursing into members some query names.
444///
445/// # Safety
446///
447/// `input` must be valid UTF-8.
448unsafe fn walk_object(
449    input: &[u8],
450    mut i: usize,
451    deeper: &[Query<'_>],
452    results: &mut Vec<Option<(usize, usize)>>,
453    remaining: &mut usize,
454    scratch: &mut Vec<u8>,
455    opts: ParseOptions,
456) -> Result<Option<usize>, ParseError> {
457    i = skip_ws(input, i + 1);
458    if input.get(i) == Some(&b'}') {
459        return Ok(Some(i + 1)); // empty object
460    }
461    // First-match-wins, hit or miss: the first member with a matching key
462    // consumes the query, so a later duplicate key can never re-resolve
463    // it (parity with single [`pointer()`] resolution).
464    let mut live: Vec<Query<'_>> = deeper.to_vec();
465    loop {
466        if input.get(i) != Some(&b'"') {
467            // Past the first member, so a `}` here follows a comma.
468            if trailing_close(input, i, opts, b'}') {
469                return Ok(Some(i + 1));
470            }
471            return Err(ParseError::expected("'\"'", i));
472        }
473        // SAFETY: forwarded UTF-8 contract; `i` holds a `"`.
474        let (part, key_end) = unsafe { scalars::parse_string(input, i, scratch) }
475            .map_err(|e| ParseError::scalar(e, i))?;
476        // WTF-8 keys cannot equal a &str pointer token.
477        let mut advanced: Vec<Query<'_>> = Vec::new();
478        if let StrPart::Borrowed(k) | StrPart::Decoded(k) = part {
479            live.retain(|q| {
480                let hit = q.tokens[0].text == k;
481                if hit {
482                    advanced.push(Query {
483                        id: q.id,
484                        tokens: &q.tokens[1..],
485                    });
486                }
487                !hit
488            });
489        }
490        i = skip_ws(input, key_end);
491        if input.get(i) != Some(&b':') {
492            return Err(ParseError::expected("':'", i));
493        }
494        i = skip_ws(input, i + 1);
495        let value_past = if advanced.is_empty() {
496            // SAFETY: forwarded UTF-8 contract.
497            unsafe { value_end(input, i, scratch, opts) }?
498        } else {
499            // SAFETY: forwarded UTF-8 contract.
500            match unsafe { resolve_set(input, i, &advanced, results, remaining, scratch, opts) }? {
501                Some(end) => end,
502                None => return Ok(None),
503            }
504        };
505        i = skip_ws(input, value_past);
506        match input.get(i) {
507            Some(b',') => i = skip_ws(input, i + 1),
508            Some(b'}') => return Ok(Some(i + 1)),
509            Some(_) => return Err(ParseError::expected("',' or '}'", i)),
510            None => return Err(ParseError::unexpected_end(input.len())),
511        }
512    }
513}
514
515/// Walk one array once, recursing at indices some query names.
516///
517/// # Safety
518///
519/// `input` must be valid UTF-8.
520unsafe fn walk_array(
521    input: &[u8],
522    mut i: usize,
523    deeper: &[Query<'_>],
524    results: &mut Vec<Option<(usize, usize)>>,
525    remaining: &mut usize,
526    scratch: &mut Vec<u8>,
527    opts: ParseOptions,
528) -> Result<Option<usize>, ParseError> {
529    i = skip_ws(input, i + 1);
530    if input.get(i) == Some(&b']') {
531        return Ok(Some(i + 1)); // empty array
532    }
533    // Elements past the largest queried index are skipped, not walked.
534    let max_wanted = deeper.iter().filter_map(|q| q.tokens[0].index).max();
535    let mut element = 0usize;
536    loop {
537        let advanced: Vec<Query<'_>> = deeper
538            .iter()
539            .filter(|q| q.tokens[0].index == Some(element))
540            .map(|q| Query {
541                id: q.id,
542                tokens: &q.tokens[1..],
543            })
544            .collect();
545        let value_past = if advanced.is_empty() {
546            // SAFETY: forwarded UTF-8 contract.
547            unsafe { value_end(input, i, scratch, opts) }?
548        } else {
549            // SAFETY: forwarded UTF-8 contract.
550            match unsafe { resolve_set(input, i, &advanced, results, remaining, scratch, opts) }? {
551                Some(end) => end,
552                None => return Ok(None),
553            }
554        };
555        i = skip_ws(input, value_past);
556        match input.get(i) {
557            Some(b',') => {
558                i = skip_ws(input, i + 1);
559                if trailing_close(input, i, opts, b']') {
560                    return Ok(Some(i + 1));
561                }
562            }
563            Some(b']') => return Ok(Some(i + 1)),
564            Some(_) => return Err(ParseError::expected("',' or ']'", i)),
565            None => return Err(ParseError::unexpected_end(input.len())),
566        }
567        element += 1;
568        // Nothing deeper wants later elements; no caller needs this
569        // array's end if the whole batch resolves inside it, but the
570        // parent still might, so skip the remainder structurally.
571        if max_wanted.is_some_and(|m| element > m) {
572            // Rewind to the opener is impossible; finish by skipping
573            // element-by-element (cheap: container_end per element).
574            loop {
575                // SAFETY: forwarded UTF-8 contract.
576                let past = unsafe { value_end(input, i, scratch, opts) }?;
577                i = skip_ws(input, past);
578                match input.get(i) {
579                    Some(b',') => {
580                        i = skip_ws(input, i + 1);
581                        if trailing_close(input, i, opts, b']') {
582                            return Ok(Some(i + 1));
583                        }
584                    }
585                    Some(b']') => return Ok(Some(i + 1)),
586                    Some(_) => return Err(ParseError::expected("',' or ']'", i)),
587                    None => return Err(ParseError::unexpected_end(input.len())),
588                }
589            }
590        }
591    }
592}
593
594/// One object level: find `token`'s value, skipping non-matching members.
595/// `i` is at the `{`; returns the matched value's position, or `None`
596/// when the key is absent.
597///
598/// # Safety
599///
600/// `input` must be valid UTF-8.
601unsafe fn descend_object(
602    input: &[u8],
603    mut i: usize,
604    token: &str,
605    scratch: &mut Vec<u8>,
606    opts: ParseOptions,
607) -> Result<Option<usize>, ParseError> {
608    // Unescape once per level: `~1` -> `/`, then `~0` -> `~` (RFC 6901
609    // order). Clean tokens compare borrowed.
610    let unescaped: std::borrow::Cow<'_, str> = if token.contains('~') {
611        token.replace("~1", "/").replace("~0", "~").into()
612    } else {
613        token.into()
614    };
615    i = skip_ws(input, i + 1);
616    if input.get(i) == Some(&b'}') {
617        return Ok(None); // empty object
618    }
619    loop {
620        if input.get(i) != Some(&b'"') {
621            // Past the first member, so a `}` here follows a comma.
622            if trailing_close(input, i, opts, b'}') {
623                return Ok(None); // key not present
624            }
625            return Err(ParseError::expected("'\"'", i));
626        }
627        // SAFETY: forwarded UTF-8 contract; `i` holds a `"`.
628        let (part, key_end) = unsafe { scalars::parse_string(input, i, scratch) }
629            .map_err(|e| ParseError::scalar(e, i))?;
630        let matched = match part {
631            StrPart::Borrowed(k) | StrPart::Decoded(k) => k == unescaped,
632            // WTF-8 keys cannot equal a &str pointer token.
633            StrPart::DecodedRaw(_) => false,
634        };
635        i = skip_ws(input, key_end);
636        if input.get(i) != Some(&b':') {
637            return Err(ParseError::expected("':'", i));
638        }
639        i = skip_ws(input, i + 1);
640        if matched {
641            return Ok(Some(i)); // the value at `i` is this level's match
642        }
643        // SAFETY: forwarded UTF-8 contract.
644        let value_past = unsafe { value_end(input, i, scratch, opts) }?;
645        i = skip_ws(input, value_past);
646        match input.get(i) {
647            Some(b',') => i = skip_ws(input, i + 1),
648            Some(b'}') => return Ok(None), // key not present
649            Some(_) => return Err(ParseError::expected("',' or '}'", i)),
650            None => return Err(ParseError::unexpected_end(input.len())),
651        }
652    }
653}
654
655/// One array level: find element `token`'s position, skipping earlier
656/// elements. `i` is at the `[`; returns `None` for out-of-range indices
657/// or tokens that are not valid index syntax.
658///
659/// # Safety
660///
661/// `input` must be valid UTF-8.
662unsafe fn descend_array(
663    input: &[u8],
664    mut i: usize,
665    token: &str,
666    scratch: &mut Vec<u8>,
667    opts: ParseOptions,
668) -> Result<Option<usize>, ParseError> {
669    // Array-index tokens are digits without leading zeros; anything else
670    // ("-", "01", "1x", "") cannot match.
671    let valid = !token.is_empty()
672        && token.bytes().all(|b| b.is_ascii_digit())
673        && (token == "0" || !token.starts_with('0'));
674    let target = if valid {
675        token.parse::<usize>().ok()
676    } else {
677        None
678    };
679    let Some(target) = target else {
680        return Ok(None);
681    };
682    i = skip_ws(input, i + 1);
683    if input.get(i) == Some(&b']') {
684        return Ok(None); // empty array
685    }
686    for _ in 0..target {
687        // SAFETY: forwarded UTF-8 contract.
688        let value_past = unsafe { value_end(input, i, scratch, opts) }?;
689        i = skip_ws(input, value_past);
690        match input.get(i) {
691            Some(b',') => {
692                i = skip_ws(input, i + 1);
693                if trailing_close(input, i, opts, b']') {
694                    return Ok(None); // out of range
695                }
696            }
697            Some(b']') => return Ok(None), // out of range
698            Some(_) => return Err(ParseError::expected("',' or ']'", i)),
699            None => return Err(ParseError::unexpected_end(input.len())),
700        }
701    }
702    Ok(Some(i))
703}
704
705#[cfg(test)]
706mod tests {
707    use super::*;
708
709    fn get<'j>(doc: &'j str, ptr: &str) -> Option<&'j str> {
710        let mut bufs = Buffers::new();
711        pointer(doc, ptr, &mut bufs).unwrap()
712    }
713
714    /// The RFC 6901 §5 example document and pointer set.
715    #[test]
716    fn rfc6901_examples() {
717        let doc = r#"{
718            "foo": ["bar", "baz"],
719            "": 0,
720            "a/b": 1,
721            "c%d": 2,
722            "e^f": 3,
723            "g|h": 4,
724            "i\\j": 5,
725            "k\"l": 6,
726            " ": 7,
727            "m~n": 8
728        }"#;
729        assert_eq!(get(doc, ""), Some(doc.trim()));
730        assert_eq!(get(doc, "/foo"), Some(r#"["bar", "baz"]"#));
731        assert_eq!(get(doc, "/foo/0"), Some("\"bar\""));
732        assert_eq!(get(doc, "/"), Some("0"));
733        assert_eq!(get(doc, "/a~1b"), Some("1"));
734        assert_eq!(get(doc, "/c%d"), Some("2"));
735        assert_eq!(get(doc, "/e^f"), Some("3"));
736        assert_eq!(get(doc, "/g|h"), Some("4"));
737        assert_eq!(get(doc, "/i\\j"), Some("5"));
738        assert_eq!(get(doc, "/k\"l"), Some("6"));
739        assert_eq!(get(doc, "/ "), Some("7"));
740        assert_eq!(get(doc, "/m~0n"), Some("8"));
741    }
742
743    #[test]
744    fn misses_are_none() {
745        let doc = r#"{"a":[10,20],"b":{"c":true}}"#;
746        assert_eq!(get(doc, "/missing"), None);
747        assert_eq!(get(doc, "/a/2"), None); // out of range
748        assert_eq!(get(doc, "/a/-"), None); // past-the-end token
749        assert_eq!(get(doc, "/a/01"), None); // leading zero
750        assert_eq!(get(doc, "/a/x"), None); // not an index
751        assert_eq!(get(doc, "/a/0/deeper"), None); // scalar descent
752        assert_eq!(get(doc, "/b/c/d"), None);
753        assert_eq!(get("[]", "/0"), None); // empty array
754    }
755
756    #[test]
757    fn nested_and_escaped() {
758        let doc = r#"{"a":{"b":[{"deep":[1,{"x":"found"}]}]},"z":9}"#;
759        assert_eq!(get(doc, "/a/b/0/deep/1/x"), Some("\"found\""));
760        assert_eq!(get(doc, "/z"), Some("9"));
761        // Keys with escapes in the document decode before comparing.
762        let doc = r#"{"k\ney": 42}"#;
763        assert_eq!(get(doc, "/k\ney"), Some("42"));
764        // Duplicate keys: first occurrence wins.
765        let doc = r#"{"d":1,"d":2}"#;
766        assert_eq!(get(doc, "/d"), Some("1"));
767        // Brackets and quotes inside skipped strings don't confuse the
768        // structural skip.
769        let doc = r#"{"skip":["}{][", "a\"b", {"x":"]"}],"hit":1}"#;
770        assert_eq!(get(doc, "/hit"), Some("1"));
771    }
772
773    #[test]
774    fn errors() {
775        let mut bufs = Buffers::new();
776        // Malformed pointer syntax.
777        assert_eq!(
778            pointer("{}", "no-slash", &mut bufs).unwrap_err().kind,
779            ErrorKind::InvalidPointer
780        );
781        // Malformed document still errors even when skipping.
782        assert!(pointer("{\"a\":", "/a", &mut bufs).is_err());
783        assert!(pointer("[1,2", "/5", &mut bufs).is_err());
784    }
785
786    /// The batch resolver must agree with sequential single resolution
787    /// on every pointer, in every combination.
788    #[test]
789    fn batch_matches_sequential() {
790        let doc = r#"{
791            "users": [{"name":"ada","tags":[1,2]},{"name":"grace"}],
792            "a/b": 5, "m~n": {"deep": true}, "empty": {}, "arr": []
793        }"#;
794        let ptrs = [
795            "/users/1/name",
796            "/users/0/tags/1",
797            "/users/0/name",
798            "/missing",
799            "/users/5",
800            "/a~1b",
801            "/m~0n/deep",
802            "/empty/x",
803            "/arr/0",
804            "/users/0/tags",
805            "",
806        ];
807        let mut bufs = Buffers::new();
808        let batch = pointers(doc, &ptrs, &mut bufs).unwrap();
809        for (ptr, got) in ptrs.iter().zip(&batch) {
810            let single = pointer(doc, ptr, &mut bufs).unwrap();
811            assert_eq!(*got, single, "pointer {ptr:?}");
812        }
813        // Duplicate pointers each get their own aligned answer.
814        let batch = pointers(doc, &["/a~1b", "/a~1b"], &mut bufs).unwrap();
815        assert_eq!(batch, [Some("5"), Some("5")]);
816        // Empty batch is a no-op.
817        assert_eq!(
818            pointers(doc, &[], &mut bufs).unwrap(),
819            Vec::<Option<&str>>::new()
820        );
821        // Malformed pointer syntax errors the whole call.
822        assert!(pointers(doc, &["/ok", "bad"], &mut bufs).is_err());
823    }
824
825    /// A duplicate key must not re-resolve a query its first match
826    /// already consumed, even when the first match was a dead end.
827    #[test]
828    fn batch_duplicate_keys_first_match_wins() {
829        let mut bufs = Buffers::new();
830        let doc = r#"{"a":8,"a":{"b":9}}"#;
831        assert_eq!(pointer(doc, "/a/b", &mut bufs), Ok(None));
832        assert_eq!(
833            pointers(doc, &["/a/b", "/a"], &mut bufs).unwrap(),
834            [None, Some("8")]
835        );
836    }
837
838    /// Documented asymmetry: on malformed documents the batch resolver
839    /// may error where single resolution misses, because one pass scans
840    /// every byte some pointer needs.
841    #[test]
842    fn batch_validates_what_it_scans() {
843        let mut bufs = Buffers::new();
844        assert_eq!(pointer("-", "/", &mut bufs), Ok(None));
845        assert!(pointers("-", &["/"], &mut bufs).is_err());
846    }
847
848    /// The matched slice re-parses to the same thing a full walk sees.
849    #[test]
850    fn slice_reparses() {
851        let doc = r#"{"list":[{"n":1.5},{"n":"two"},{"n":[3]}]}"#;
852        for (ptr, expected) in [
853            ("/list/0", r#"{"n":1.5}"#),
854            ("/list/1/n", "\"two\""),
855            ("/list/2/n", "[3]"),
856        ] {
857            let raw = get(doc, ptr).unwrap();
858            assert_eq!(raw, expected);
859            let mut bufs = Buffers::new();
860            let mut p = crate::Reader::new(raw, &mut bufs);
861            p.skip_value().unwrap();
862            p.finish().unwrap();
863        }
864    }
865
866    /// Hits, misses past the extension, and whole-document pointers
867    /// resolve under the matching option, single and batched alike,
868    /// while the default resolvers keep rejecting what they walk into.
869    #[test]
870    fn parse_options_extend_resolution() {
871        let trailing = ParseOptions {
872            allow_trailing_comma: true,
873            ..ParseOptions::default()
874        };
875        let nan = ParseOptions {
876            allow_nan: true,
877            ..ParseOptions::default()
878        };
879        let cases: &[(&str, ParseOptions, &str, Option<&str>)] = &[
880            (r#"{"a":1,"b":[3,],}"#, trailing, "/b", Some("[3,]")),
881            (r#"{"a":1,"b":[3,],}"#, trailing, "/z", None),
882            (r#"{"a":1,"b":[3,],}"#, trailing, "/b/0", Some("3")),
883            (r#"{"a":1,"b":[3,],}"#, trailing, "/b/1", None),
884            ("[1,2,]", trailing, "/1", Some("2")),
885            ("[1,2,]", trailing, "/2", None),
886            ("[1, 2 , ]", trailing, "/5", None),
887            ("[[1,],[2,],]", trailing, "/1/0", Some("2")),
888            ("[1,2,]", trailing, "", Some("[1,2,]")),
889            (r#"{"a":NaN,"b":1}"#, nan, "/b", Some("1")),
890            (r#"{"a":NaN,"b":1}"#, nan, "/a", Some("NaN")),
891            (r#"{"a":NaN,"b":1}"#, nan, "/z", None),
892            ("[-Infinity,Infinity]", nan, "/1", Some("Infinity")),
893            ("[-Infinity,Infinity]", nan, "/0", Some("-Infinity")),
894            ("-Infinity", nan, "", Some("-Infinity")),
895        ];
896        let mut bufs = Buffers::new();
897        for &(doc, opts, ptr, want) in cases {
898            assert_eq!(
899                pointer_with(doc, ptr, &mut bufs, opts).unwrap(),
900                want,
901                "{doc} {ptr}"
902            );
903            assert_eq!(
904                pointers_with(doc, &[ptr], &mut bufs, opts).unwrap(),
905                [want],
906                "{doc} {ptr} batch"
907            );
908        }
909        // Default resolvers stay strict wherever they walk the extension.
910        for (doc, ptr) in [
911            (r#"{"a":1,}"#, "/z"),
912            ("[1,2,]", "/2"),
913            (r#"{"a":NaN,"b":1}"#, "/b"),
914            ("[NaN]", "/0"),
915        ] {
916            assert!(pointer(doc, ptr, &mut bufs).is_err(), "{doc} {ptr}");
917            assert!(
918                pointers(doc, &[ptr], &mut bufs).is_err(),
919                "{doc} {ptr} batch"
920            );
921        }
922        // Options never loosen anything else.
923        for (doc, ptr) in [("[1,,]", "/5"), (r#"{"a":1,,}"#, "/z"), ("[,]", "/0")] {
924            assert!(
925                pointer_with(doc, ptr, &mut bufs, trailing).is_err(),
926                "{doc} {ptr}"
927            );
928        }
929        assert!(pointer_with("[Nan,1]", "/1", &mut bufs, nan).is_err());
930    }
931}