json_syntax/

tracing.rs

//! Allocation-free source-location tracking ("backtraces") for [`JsonValue`].
//!
//! Pairs a value or error with a precise position in a JSON document, or
//! across several documents, without allocating until a location is
//! actually needed:
//!
//! - [`JsonBacktraceBuilder`] incrementally builds a location as a
//!   borrow-chain stack while walking a document; call
//!   [`JsonBacktraceBuilder::build`] to turn it into an owned
//!   [`JsonBacktraceBuf`].
//! - A [`JsonBacktraceBuf`]/[`JsonBacktrace`] is a sequence of
//!   [`JsonBacktraceFrame`]s, one per file crossed, each holding a
//!   [`JsonFragmentPathBuf`]/[`JsonFragmentPath`] of
//!   [`JsonFragmentPathSegment`]/[`JsonFragmentPathItemRef`] navigation
//!   steps within that file.
//! - [`JsonLocated`] (and the [`JsonAt`]/[`JsonErrorAt`] helper traits)
//!   pairs a value or error with its [`JsonBacktraceBuf`].
//! - [`JsonValue::locate_fragment`] resolves a path back to a byte offset,
//!   given the [`JsonCodeMap`] produced when the document was parsed.

use core::fmt;
use std::error::Error;

use into_owned_trait::IntoOwned;

use crate::{JsonCodeMap, JsonValue, array::JsonArrayExt, code_map::JsonMapped};

impl JsonValue {
	/// Returns the [`JsonCodeMap`] index of the fragment described by `path`.
	///
	/// The returned index can be used to look up the byte span of the fragment
	/// in the `code_map` produced by parsing the same document.
	///
	/// Returns `None` if the path does not exist in this value (e.g., the key
	/// is missing, the array index is out of range, or a path segment tries to
	/// navigate into a fragment that has no sub-fragments).
	///
	/// # Segment semantics
	///
	/// - [`JsonFragmentPathSegment::ArrayIndex`]: navigates into the *i*-th
	///   element of an array.
	/// - [`JsonFragmentPathSegment::ObjectKey`]: navigates to the **key** string
	///   fragment of the *n*-th occurrence of the named key.  This is a terminal
	///   step; further path segments after this will return `None`.
	/// - [`JsonFragmentPathSegment::ObjectValue`]: navigates to the **value**
	///   of the *n*-th occurrence of the named key.
	pub fn locate_fragment(
		&self,
		code_map: &JsonCodeMap,
		path: &JsonFragmentPath,
	) -> Option<usize> {
		self.locate_fragment_at(code_map, path, 0)
	}

	fn locate_fragment_at(
		&self,
		code_map: &JsonCodeMap,
		path: &JsonFragmentPath,
		offset: usize,
	) -> Option<usize> {
		match path.split_first() {
			Some((segment, rest)) => match segment {
				JsonFragmentPathSegment::ArrayItem(i) => {
					let array = self.as_array()?;
					for (j, JsonMapped(item, item_offset)) in
						array.iter_mapped(code_map, offset).enumerate()
					{
						if j == *i {
							return item.locate_fragment_at(code_map, rest, item_offset);
						}
					}

					None
				}
				JsonFragmentPathSegment::ObjectEntry(k, occurrence, part) => {
					let object = self.as_object()?;
					let mut occ_count = 0usize;
					for JsonMapped(
						(JsonMapped(key, key_offset), JsonMapped(value, value_offset)),
						entry_offset,
					) in object.iter_mapped(code_map, offset)
					{
						if k.as_str() == key.as_str() {
							if occ_count == *occurrence {
								return match *part {
									JsonObjectEntryPart::All => {
										if rest.is_empty() {
											Some(entry_offset)
										} else {
											None
										}
									}
									JsonObjectEntryPart::Key => {
										if rest.is_empty() {
											Some(key_offset)
										} else {
											None
										}
									}
									JsonObjectEntryPart::Value => {
										value.locate_fragment_at(code_map, rest, value_offset)
									}
								};
							}

							occ_count += 1;
						}
					}

					None
				}
			},
			None => Some(offset),
		}
	}
}

impl JsonValue {
	/// Recursively searches this value, including nested arrays and objects,
	/// for the first object containing a duplicate key.
	///
	/// Many JSON-based formats (such as JSON-LD) require object keys to be
	/// unique throughout a document, even though JSON itself only recommends
	/// it; this can be used to validate a whole document in one pass before
	/// processing it, rather than checking every object individually as it is
	/// encountered.
	///
	/// Returns the path to the first object found with a duplicate key
	/// (relative to `self`), together with the duplicated key itself, or
	/// `None` if no object anywhere in this value has a duplicate key. The
	/// returned path can be passed to [`JsonValue::locate_fragment`] (with an
	/// empty final segment, or combined with
	/// [`JsonBacktraceBuilder`](crate::tracing::JsonBacktraceBuilder) methods)
	/// to locate the offending object in a parsed document.
	pub fn find_duplicate_key_recursive(&self) -> Option<(JsonFragmentPathBuf, &str)> {
		let (mut path, key) = self.find_duplicate_key_recursive_reversed()?;
		path.reverse();
		Some((path, key))
	}

	/// Helper for [`Self::find_duplicate_key_recursive`].
	///
	/// Builds the path from the duplicate-key object back up to `self`,
	/// i.e. in reverse order, since appending a segment as each stack frame
	/// unwinds is cheaper than repeatedly inserting one at the front. The
	/// public method reverses the result before returning it.
	fn find_duplicate_key_recursive_reversed(&self) -> Option<(JsonFragmentPathBuf, &str)> {
		match self {
			Self::Array(items) => {
				for (i, item) in items.iter().enumerate() {
					if let Some((mut path, key)) = item.find_duplicate_key_recursive_reversed() {
						path.push(JsonFragmentPathSegment::ArrayItem(i));
						return Some((path, key));
					}
				}

				None
			}
			Self::Object(object) => {
				// This object's own entries take priority: if it has a
				// duplicate key itself, there's no need to look deeper.
				if let Some(key) = object.find_duplicate_key() {
					return Some((Vec::new(), key));
				}

				// No duplicates among this object's own keys, so every key
				// here maps to exactly one entry: occurrence `0` is always
				// correct when descending into any of them.
				for (key, value) in object.iter() {
					if let Some((mut path, duplicate_key)) =
						value.find_duplicate_key_recursive_reversed()
					{
						path.push(JsonFragmentPathSegment::ObjectEntry(
							key.to_string(),
							0,
							JsonObjectEntryPart::Value,
						));
						return Some((path, duplicate_key));
					}
				}

				None
			}
			_ => None,
		}
	}
}

/// Describes the exact location of a JSON fragment within a document, or
/// across several documents.
///
/// A backtrace is a sequence of [`JsonBacktraceFrame`]s, ordered from the
/// outermost file to the innermost. A single frame is enough to describe a
/// fragment's position within one file (an object key/value, an array
/// item, etc., accumulated as a [`JsonFragmentPathBuf`]). Multiple frames
/// are needed when resolving that fragment required crossing into another
/// file along the way.
///
/// A `JsonBacktraceBuf` is normally not built by hand: use
/// [`JsonBacktraceBuilder`] to accumulate navigation steps cheaply while
/// walking a document, then call [`JsonBacktraceBuilder::build`] to
/// produce the final, owned value. Pair it with a value or error using
/// [`JsonLocated`] (or the [`JsonAt`]/[`JsonErrorAt`] helper traits).
pub type JsonBacktraceBuf<T> = Vec<JsonBacktraceFrame<T>>;

/// Borrowed form of a [`JsonBacktraceBuf`].
pub type JsonBacktrace<T> = [JsonBacktraceFrame<T>];

/// A single frame of a [`JsonBacktraceBuf`]: the file a fragment was found
/// in, and the path to that fragment within it.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct JsonBacktraceFrame<T> {
	/// File in which the error occurred.
	pub file: T,

	/// Path to the exact fragment that caused the error.
	pub fragment: JsonFragmentPathBuf,
}

impl<T> JsonBacktraceFrame<T> {
	/// Creates a new frame for `file`, with an empty fragment path.
	pub fn new(file: T) -> Self {
		Self {
			file,
			fragment: Vec::new(),
		}
	}
}

/// Incrementally builds a [`JsonBacktraceBuf`] as a borrow-chain stack,
/// without allocating until [`Self::build`] is called.
///
/// Each variant borrows the previous step (`&'a Self`), so a complete chain
/// lives on the stack across nested calls; use [`Self::build`] to turn it
/// into an owned [`JsonBacktraceBuf`].
#[derive(Debug)]
pub enum JsonBacktraceBuilder<'a, T: IntoOwned, O = <T as IntoOwned>::Owned> {
	/// Empty backtrace with no frames.
	Root,

	/// Starts a new file frame, extending the previous chain.
	File(&'a Self, T),

	/// Pushes one navigation step onto the last file frame's fragment path.
	Item(&'a Self, JsonFragmentPathItemRef<'a>),

	/// Pushes every segment of a path onto the last file frame's fragment
	/// path, in a single step.
	Path(&'a Self, &'a JsonFragmentPathBuf),

	/// Appends the frames of a previously-built backtrace onto the chain.
	Backtrace(&'a Self, &'a JsonBacktrace<O>),
}

impl<T: IntoOwned + Clone> Clone for JsonBacktraceBuilder<'_, T> {
	fn clone(&self) -> Self {
		match *self {
			Self::Root => Self::Root,
			Self::File(parent, ref file) => Self::File(parent, file.clone()),
			Self::Item(parent, item) => Self::Item(parent, item),
			Self::Path(parent, path) => Self::Path(parent, path),
			Self::Backtrace(parent, b) => Self::Backtrace(parent, b),
		}
	}
}

impl<T: IntoOwned + Copy> Copy for JsonBacktraceBuilder<'_, T> {}

impl<T: IntoOwned> JsonBacktraceBuilder<'_, T> {
	/// Creates an empty stack with no items.
	pub fn new() -> &'static Self {
		&Self::Root
	}

	/// Starts a new file frame, extending this chain.
	pub fn file<'a>(&'a self, file: T) -> JsonBacktraceBuilder<'a, T> {
		JsonBacktraceBuilder::File(self, file)
	}

	/// Pushes a single navigation step onto this chain.
	pub fn push<'a>(&'a self, item: JsonFragmentPathItemRef<'a>) -> JsonBacktraceBuilder<'a, T> {
		JsonBacktraceBuilder::Item(self, item)
	}

	/// Pushes every segment of `path`, in order, in a single step.
	///
	/// Equivalent to calling [`Self::push`] once per segment of `path`, but
	/// without building an intermediate chain node for each one.
	pub fn push_path<'a>(&'a self, path: &'a JsonFragmentPathBuf) -> JsonBacktraceBuilder<'a, T> {
		JsonBacktraceBuilder::Path(self, path)
	}

	/// Appends the frames of a previously-built backtrace onto this chain,
	/// in a single step.
	///
	/// Useful to "jump back" to a location recorded earlier (e.g. where a
	/// value was originally defined), while still preserving how the
	/// current chain got there.
	pub fn push_backtrace<'a>(
		&'a self,
		backtrace: &'a JsonBacktrace<T::Owned>,
	) -> JsonBacktraceBuilder<'a, T> {
		JsonBacktraceBuilder::Backtrace(self, backtrace)
	}

	/// Push a navigation step to the `index`-th element of an array.
	pub fn array_index(&self, index: usize) -> JsonBacktraceBuilder<'_, T> {
		self.push(JsonFragmentPathItemRef::ArrayItem(index))
	}

	/// Push a navigation step to the whole entry (key + value) for the first occurrence of `key`.
	///
	/// Equivalent to `object_entry_at(key, 0)`. For objects with duplicate keys, use
	/// [`object_entry_at`](Self::object_entry_at) to specify the occurrence index.
	pub fn object_entry<'b>(&'b self, key: impl Into<&'b str>) -> JsonBacktraceBuilder<'b, T> {
		self.push(JsonFragmentPathItemRef::ObjectEntry(
			key.into(),
			0,
			JsonObjectEntryPart::All,
		))
	}

	/// Push a navigation step to the whole entry (key + value) for the `occurrence`-th occurrence of `key`.
	///
	/// `0` selects the first occurrence, `1` the second, etc.
	pub fn object_entry_at<'b>(
		&'b self,
		key: impl Into<&'b str>,
		occurrence: usize,
	) -> JsonBacktraceBuilder<'b, T> {
		self.push(JsonFragmentPathItemRef::ObjectEntry(
			key.into(),
			occurrence,
			JsonObjectEntryPart::All,
		))
	}

	/// Push a navigation step to the key string of the first occurrence of `key`.
	///
	/// Equivalent to `object_key_at(key, 0)`. For objects with duplicate keys, use
	/// [`object_key_at`](Self::object_key_at) to specify the occurrence index.
	pub fn object_key<'b>(&'b self, key: impl Into<&'b str>) -> JsonBacktraceBuilder<'b, T> {
		self.push(JsonFragmentPathItemRef::ObjectEntry(
			key.into(),
			0,
			JsonObjectEntryPart::Key,
		))
	}

	/// Push a navigation step to the key string of the `occurrence`-th occurrence of `key`.
	///
	/// `0` selects the first occurrence, `1` the second, etc.
	pub fn object_key_at<'b>(
		&'b self,
		key: impl Into<&'b str>,
		occurrence: usize,
	) -> JsonBacktraceBuilder<'b, T> {
		self.push(JsonFragmentPathItemRef::ObjectEntry(
			key.into(),
			occurrence,
			JsonObjectEntryPart::Key,
		))
	}

	/// Push a navigation step to the value of the first occurrence of `key`.
	///
	/// Equivalent to `object_value_at(key, 0)`. For objects with duplicate keys, use
	/// [`object_value_at`](Self::object_value_at) to specify the occurrence index.
	pub fn object_value<'b>(&'b self, key: impl Into<&'b str>) -> JsonBacktraceBuilder<'b, T> {
		self.push(JsonFragmentPathItemRef::ObjectEntry(
			key.into(),
			0,
			JsonObjectEntryPart::Value,
		))
	}

	/// Push a navigation step to the value of the `occurrence`-th occurrence of `key`.
	///
	/// `0` selects the first occurrence, `1` the second, etc.
	pub fn object_value_at<'b>(
		&'b self,
		key: impl Into<&'b str>,
		occurrence: usize,
	) -> JsonBacktraceBuilder<'b, T> {
		self.push(JsonFragmentPathItemRef::ObjectEntry(
			key.into(),
			occurrence,
			JsonObjectEntryPart::Value,
		))
	}

	/// Consumes this chain and produces the equivalent owned
	/// [`JsonBacktraceBuf`].
	pub fn build(self) -> JsonBacktraceBuf<T::Owned>
	where
		T: Clone,
		T::Owned: Clone,
	{
		match self {
			Self::Root => JsonBacktraceBuf::new(),
			Self::File(parent, file) => {
				let mut backtrace = parent.clone().build();
				backtrace.push(JsonBacktraceFrame::new(file.into_owned()));
				backtrace
			}
			Self::Item(parent, item) => {
				let mut backtrace = parent.clone().build();

				if let Some(last) = backtrace.last_mut() {
					last.fragment.push(item.into_owned());
				}

				backtrace
			}
			Self::Path(parent, path) => {
				let mut backtrace = parent.clone().build();

				if let Some(last) = backtrace.last_mut() {
					last.fragment.extend(path.iter().cloned());
				}

				backtrace
			}
			Self::Backtrace(parent, b) => {
				let mut backtrace = parent.clone().build();
				backtrace.extend(b.iter().cloned());
				backtrace
			}
		}
	}
}

impl<T: Clone + IntoOwned> From<JsonBacktraceBuilder<'_, T>> for JsonBacktraceBuf<T::Owned>
where
	T::Owned: Clone,
{
	fn from(value: JsonBacktraceBuilder<'_, T>) -> Self {
		value.build()
	}
}

/// A value paired with a source location.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct JsonLocated<T, F> {
	/// The located value.
	pub value: T,

	/// Backtrace describing where `value` was found.
	pub location: JsonBacktraceBuf<F>,
}

impl<T, F> JsonLocated<T, F> {
	/// Pairs `value` with its `location`.
	pub fn new(value: T, location: JsonBacktraceBuf<F>) -> Self {
		Self { value, location }
	}

	/// Maps the located value, keeping its location unchanged.
	pub fn map<U>(self, f: impl FnOnce(T) -> U) -> JsonLocated<U, F> {
		JsonLocated {
			value: f(self.value),
			location: self.location,
		}
	}

	/// Converts the located value into another type, keeping its location
	/// unchanged.
	pub fn cast<U>(self) -> JsonLocated<U, F>
	where
		T: Into<U>,
	{
		self.map(Into::into)
	}
}

impl<T: fmt::Display, F> fmt::Display for JsonLocated<T, F> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.value.fmt(f)
	}
}

impl<T: 'static + Error, F: fmt::Debug> Error for JsonLocated<T, F> {
	fn source(&self) -> Option<&(dyn Error + 'static)> {
		Some(&self.value)
	}
}

/// Owned form of a single path navigation step, as recorded in a
/// [`JsonBacktraceFrame`].
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum JsonFragmentPathSegment {
	/// Navigates into the element at this index of an array.
	ArrayItem(usize),

	/// Navigates into the `occurrence`-th entry with this key in an
	/// object, targeting the part given by [`JsonObjectEntryPart`].
	ObjectEntry(String, usize, JsonObjectEntryPart),
}

/// Which part of an object entry a [`JsonFragmentPathSegment::ObjectEntry`]
/// (or [`JsonFragmentPathItemRef::ObjectEntry`]) targets.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum JsonObjectEntryPart {
	/// The whole entry (key and value).
	All,

	/// Just the key string.
	Key,

	/// Just the value.
	Value,
}

/// Borrowed form of [`JsonFragmentPathSegment`], used while building a
/// backtrace to avoid allocating until [`JsonBacktraceBuilder::build`] is
/// called.
#[derive(Debug, Clone, Copy)]
pub enum JsonFragmentPathItemRef<'a> {
	/// See [`JsonFragmentPathSegment::ArrayItem`].
	ArrayItem(usize),

	/// See [`JsonFragmentPathSegment::ObjectEntry`].
	ObjectEntry(&'a str, usize, JsonObjectEntryPart),
}

impl JsonFragmentPathItemRef<'_> {
	/// Converts this borrowed path segment into its owned
	/// [`JsonFragmentPathSegment`] form.
	pub fn into_owned(self) -> JsonFragmentPathSegment {
		match self {
			Self::ArrayItem(i) => JsonFragmentPathSegment::ArrayItem(i),
			Self::ObjectEntry(k, n, part) => {
				JsonFragmentPathSegment::ObjectEntry(k.to_owned(), n, part)
			}
		}
	}
}

/// Owned sequence of path segments, from outermost to innermost.
pub type JsonFragmentPathBuf = Vec<JsonFragmentPathSegment>;

/// Borrowed form of a [`JsonFragmentPathBuf`].
pub type JsonFragmentPath = [JsonFragmentPathSegment];

/// Pairs any value with a location, producing a [`JsonLocated`].
pub trait JsonAt: Sized {
	/// Pairs `self` with `location`.
	fn json_at<F>(self, location: impl Into<JsonBacktraceBuf<F>>) -> JsonLocated<Self, F>;
}

impl<T> JsonAt for T {
	fn json_at<F>(self, location: impl Into<JsonBacktraceBuf<F>>) -> JsonLocated<Self, F> {
		JsonLocated::new(self, location.into())
	}
}

/// Pairs the error of a `Result`, if any, with a location.
pub trait JsonErrorAt<T, E> {
	/// Pairs this result's error, if any, with `location`.
	fn json_err_at<F>(
		self,
		location: impl Into<JsonBacktraceBuf<F>>,
	) -> Result<T, JsonLocated<E, F>>;
}

impl<T, E> JsonErrorAt<T, E> for Result<T, E> {
	fn json_err_at<F>(
		self,
		location: impl Into<JsonBacktraceBuf<F>>,
	) -> Result<T, JsonLocated<E, F>> {
		self.map_err(|e| e.json_at(location))
	}
}

#[cfg(test)]
mod tests {
	use crate::{JsonParse, JsonValue};

	use super::*;

	#[test]
	fn locate_01() {
		// { "a": 0, "b": [1, 2] }
		// index 0: object          (volume 9)
		// index 1: entry "a": 0   (volume 3)
		// index 2: key "a"         (volume 1)
		// index 3: value 0         (volume 1)
		// index 4: entry "b": [...](volume 5)
		// index 5: key "b"         (volume 1)
		// index 6: array [1, 2]    (volume 3)
		// index 7: value 1         (volume 1)
		// index 8: value 2         (volume 1)
		let (value, code_map) = JsonValue::parse_str(r#"{ "a": 0, "b": [1, 2] }"#).unwrap();

		// empty path → root (the object itself)
		assert_eq!(value.locate_fragment(&code_map, &[]), Some(0));

		// entry fragments (All)
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					0,
					JsonObjectEntryPart::All
				)]
			),
			Some(1)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"b".into(),
					0,
					JsonObjectEntryPart::All
				)]
			),
			Some(4)
		);

		// key fragments
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					0,
					JsonObjectEntryPart::Key
				)]
			),
			Some(2)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"b".into(),
					0,
					JsonObjectEntryPart::Key
				)]
			),
			Some(5)
		);

		// value fragments
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					0,
					JsonObjectEntryPart::Value
				)]
			),
			Some(3)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"b".into(),
					0,
					JsonObjectEntryPart::Value
				)]
			),
			Some(6)
		);

		// array elements inside "b"
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[
					JsonFragmentPathSegment::ObjectEntry("b".into(), 0, JsonObjectEntryPart::Value),
					JsonFragmentPathSegment::ArrayItem(0),
				]
			),
			Some(7)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[
					JsonFragmentPathSegment::ObjectEntry("b".into(), 0, JsonObjectEntryPart::Value),
					JsonFragmentPathSegment::ArrayItem(1),
				]
			),
			Some(8)
		);

		// missing key
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"z".into(),
					0,
					JsonObjectEntryPart::Value
				)]
			),
			None
		);

		// array index out of bounds
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[
					JsonFragmentPathSegment::ObjectEntry("b".into(), 0, JsonObjectEntryPart::Value),
					JsonFragmentPathSegment::ArrayItem(2),
				]
			),
			None
		);

		// All and Key are terminal – further segments after them return None
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[
					JsonFragmentPathSegment::ObjectEntry("b".into(), 0, JsonObjectEntryPart::All),
					JsonFragmentPathSegment::ArrayItem(0),
				]
			),
			None
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[
					JsonFragmentPathSegment::ObjectEntry("b".into(), 0, JsonObjectEntryPart::Key),
					JsonFragmentPathSegment::ArrayItem(0),
				]
			),
			None
		);
	}

	#[test]
	fn locate_duplicate_keys() {
		// { "a": 1, "a": 2 }
		// index 0: object                        (volume 7)
		// index 1: entry "a": 1, occurrence 0   (volume 3)
		// index 2: key "a",   occurrence 0       (volume 1)
		// index 3: value 1,   occurrence 0       (volume 1)
		// index 4: entry "a": 2, occurrence 1   (volume 3)
		// index 5: key "a",   occurrence 1       (volume 1)
		// index 6: value 2,   occurrence 1       (volume 1)
		let (value, code_map) = JsonValue::parse_str(r#"{ "a": 1, "a": 2 }"#).unwrap();

		// first occurrence
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					0,
					JsonObjectEntryPart::All
				)]
			),
			Some(1)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					0,
					JsonObjectEntryPart::Key
				)]
			),
			Some(2)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					0,
					JsonObjectEntryPart::Value
				)]
			),
			Some(3)
		);

		// second occurrence
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					1,
					JsonObjectEntryPart::All
				)]
			),
			Some(4)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					1,
					JsonObjectEntryPart::Key
				)]
			),
			Some(5)
		);
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					1,
					JsonObjectEntryPart::Value
				)]
			),
			Some(6)
		);

		// non-existent third occurrence
		assert_eq!(
			value.locate_fragment(
				&code_map,
				&[JsonFragmentPathSegment::ObjectEntry(
					"a".into(),
					2,
					JsonObjectEntryPart::Value
				)]
			),
			None
		);
	}
}