Struct Pointer

pub struct Pointer(/* private fields */);

A JSON Pointer is a string containing a sequence of zero or more reference Tokens, each prefixed by a '/' character.

See RFC 6901 for more information.

Example

use jsonptr::{Pointer, resolve::Resolve};
use serde_json::{json, Value};

let data = json!({ "foo": { "bar": "baz" } });
let ptr = Pointer::from_static("/foo/bar");
let bar = data.resolve(&ptr).unwrap();
assert_eq!(bar, "baz");

Implementations

impl Pointer

pub unsafe fn new_unchecked<S: AsRef<str> + ?Sized>(s: &S) -> &Self

Create a Pointer from a string that is known to be correctly encoded.

This is a cost-free conversion.

Safety

The provided string must adhere to RFC 6901:

• The pointer must start with '/' (%x2F) unless empty
• Tokens must be properly encoded:
  • '~' (%x7E) must be escaped as "~0"
  • '/' (%x2F) must be escaped as "~1"

For potentially fallible parsing, see Pointer::parse.

pub const fn root() -> &'static Self

Constant reference to a root pointer

pub fn parse<S: AsRef<str> + ?Sized>(s: &S) -> Result<&Self, ParseError>

Attempts to parse a string into a Pointer.

If successful, this does not allocate.

Errors

Returns a ParseError if the string is not a valid JSON Pointer.

pub const fn from_static(s: &'static str) -> &'static Self

Creates a static Pointer from a string.

Panics

Will panic if the string does not represent a valid pointer.

Examples

use jsonptr::{Pointer, resolve::Resolve};
use serde_json::{json, Value};

const POINTER: &Pointer = Pointer::from_static("/foo/bar");
let data = json!({ "foo": { "bar": "baz" } });
let bar = data.resolve(POINTER).unwrap();
assert_eq!(bar, "baz");

pub fn as_str(&self) -> &str

The encoded string representation of this Pointer

pub fn to_buf(&self) -> PointerBuf

Converts into an owned PointerBuf

pub fn tokens(&self) -> Tokens<'_>

Returns an iterator of Tokens in the Pointer.

pub fn count(&self) -> usize

Returns the number of tokens in the Pointer.

pub fn is_root(&self) -> bool

Returns true if the JSON Pointer equals "".

pub fn to_json_value(&self) -> Value

Returns a serde_json::Value representation of this Pointer

pub fn back(&self) -> Option<Token<'_>>

Returns the last Token in the Pointer.

pub fn last(&self) -> Option<Token<'_>>

Returns the last token in the Pointer.

alias for back

pub fn front(&self) -> Option<Token<'_>>

Returns the first Token in the Pointer.

pub fn first(&self) -> Option<Token<'_>>

Returns the first Token in the Pointer.

alias for front

pub fn split_front(&self) -> Option<(Token<'_>, &Self)>

Splits the Pointer into the first Token and a remainder Pointer.

pub fn split_at(&self, offset: usize) -> Option<(&Self, &Self)>

Splits the Pointer at the given index if the character at the index is a separator slash ('/'), returning Some((head, tail)). Otherwise, returns None.

For the following JSON Pointer, the following splits are possible (0, 4, 8):

/foo/bar/baz
↑   ↑   ↑
0   4   8

All other indices will return None.

Example

let ptr = Pointer::from_static("/foo/bar/baz");
let (head, tail) = ptr.split_at(4).unwrap();
assert_eq!(head, Pointer::from_static("/foo"));
assert_eq!(tail, Pointer::from_static("/bar/baz"));
assert_eq!(ptr.split_at(3), None);

pub fn split_back(&self) -> Option<(&Self, Token<'_>)>

Splits the Pointer into the parent path and the last Token.

pub fn parent(&self) -> Option<&Self>

A pointer to the parent of the current path.

pub fn strip_suffix<'a>(&'a self, suffix: &Self) -> Option<&'a Self>

Returns the pointer stripped of the given suffix.

pub fn strip_prefix<'a>(&'a self, prefix: &Self) -> Option<&'a Self>

Returns the pointer stripped of the given prefix.

pub fn ends_with(&self, other: &Self) -> bool

Returns whether self has a suffix of other.

Note that Pointer::root is only a valid suffix of itself.

pub fn starts_with(&self, other: &Self) -> bool

Returns whether self has a prefix of other.

Note that Pointer::root is a valid prefix of any Pointer (including itself).

pub fn get<'p, I>(&'p self, index: I) -> Option<I::Output>

where I: PointerIndex<'p>,

Attempts to get a Token by the index. Returns None if the index is out of bounds.

Example

use jsonptr::{Pointer, Token};

let ptr = Pointer::from_static("/foo/bar/qux");
assert_eq!(ptr.get(0), Some("foo".into()));
assert_eq!(ptr.get(1), Some("bar".into()));
assert_eq!(ptr.get(3), None);
assert_eq!(ptr.get(..), Some(Pointer::from_static("/foo/bar/qux")));
assert_eq!(ptr.get(..1), Some(Pointer::from_static("/foo")));
assert_eq!(ptr.get(1..3), Some(Pointer::from_static("/bar/qux")));
assert_eq!(ptr.get(1..=2), Some(Pointer::from_static("/bar/qux")));

let ptr = Pointer::root();
assert_eq!(ptr.get(0), None);
assert_eq!(ptr.get(..), Some(Pointer::root()));

pub fn resolve<'v, R: Resolve>( &self, value: &'v R, ) -> Result<&'v R::Value, R::Error>

Attempts to resolve a R::Value based on the path in this Pointer.

Errors

Returns R::Error if an error occurs while resolving.

The rules of such are determined by the R’s implementation of Resolve but provided implementations return ResolveError if:

• The path is unreachable (e.g. a scalar is encountered prior to the end of the path)
• The path is not found (e.g. a key in an object or an index in an array does not exist)
• A Token cannot be parsed as an array Index
• An array Index is out of bounds

pub fn resolve_mut<'v, R: ResolveMut>( &self, value: &'v mut R, ) -> Result<&'v mut R::Value, R::Error>

Attempts to resolve a mutable R::Value based on the path in this Pointer.

Errors

Returns R::Error if an error occurs while resolving.

The rules of such are determined by the R’s implementation of ResolveMut but provided implementations return ResolveError if:

• The path is unreachable (e.g. a scalar is encountered prior to the end of the path)
• The path is not found (e.g. a key in an object or an index in an array does not exist)
• A Token cannot be parsed as an array Index
• An array Index is out of bounds

pub fn intersection<'a>(&'a self, other: &Self) -> &'a Self

Finds the commonality between this and another Pointer.

pub fn delete<D: Delete>(&self, value: &mut D) -> Option<D::Value>

Attempts to delete a serde_json::Value based upon the path in this Pointer.

The rules of deletion are determined by the D’s implementation of Delete. The supplied implementations ("json" & "toml") operate as follows:

• If the Pointer can be resolved, the Value is deleted and returned.
• If the Pointer fails to resolve for any reason, Ok(None) is returned.
• If the Pointer is root, value is replaced:
  • "json": serde_json::Value::Null
  • "toml": toml::Value::Table::Default

Examples

Deleting a resolved pointer:

use jsonptr::{Pointer, delete::Delete};
use serde_json::json;

let mut data = json!({ "foo": { "bar": { "baz": "qux" } } });
let ptr = Pointer::from_static("/foo/bar/baz");
assert_eq!(data.delete(&ptr), Some("qux".into()));
assert_eq!(data, json!({ "foo": { "bar": {} } }));

Deleting a non-existent Pointer returns None:

use jsonptr::{ Pointer, delete::Delete };
use serde_json::json;

let mut data = json!({});
let ptr = Pointer::from_static("/foo/bar/baz");
assert_eq!(ptr.delete(&mut data), None);
assert_eq!(data, json!({}));

Deleting a root pointer replaces the value with Value::Null:

use jsonptr::{Pointer, delete::Delete};
use serde_json::json;

let mut data = json!({ "foo": { "bar": "baz" } });
let ptr = Pointer::root();
assert_eq!(data.delete(&ptr), Some(json!({ "foo": { "bar": "baz" } })));
assert!(data.is_null());

pub fn assign<D, V>( &self, dest: &mut D, src: V, ) -> Result<Option<D::Value>, D::Error>

where D: Assign, V: Into<D::Value>,

Attempts to assign src to dest based on the path in this Pointer.

If the path is partially available, the missing portions will be created. If the path contains a zero index, such as "/0", then an array will be created. Otherwise, objects will be utilized to create the missing path.

Example

use jsonptr::Pointer;
use serde_json::{json, Value};

let mut data = json!([]);
let mut ptr = Pointer::from_static("/0/foo");
let replaced = ptr.assign(&mut data, json!("bar")).unwrap();
assert_eq!(data, json!([{"foo": "bar"}]));
assert_eq!(replaced, None);

Errors

Returns Assign::Error if the path is invalid or if the value cannot be assigned.

pub fn components(&self) -> Components<'_>

Returns Components of this JSON Pointer.

A Component is either Token or the root location of a document.

Example

let ptr = Pointer::parse("/a/b").unwrap();
let mut components = ptr.components();
assert_eq!(components.next(), Some(Component::Root));
assert_eq!(components.next(), Some(Component::Token("a".into())));
assert_eq!(components.next(), Some(Component::Token("b".into())));
assert_eq!(components.next(), None);

pub fn with_trailing_token<'t>(&self, token: impl Into<Token<'t>>) -> PointerBuf

Creates an owned PointerBuf like self but with token appended.

See PointerBuf::push_back for more details.

Note: this method allocates. If you find yourself calling it more than once for a given pointer, consider using PointerBuf::push_back instead.

Examples

let ptr = jsonptr::Pointer::from_static("/foo");
let foobar = ptr.with_trailing_token("bar");
assert_eq!(foobar, "/foo/bar");

pub fn with_leading_token<'t>(&self, token: impl Into<Token<'t>>) -> PointerBuf

Creates an owned PointerBuf like self but with token prepended.

See PointerBuf::push_front for more details.

Note: this method allocates. If you find yourself calling it more than once for a given pointer, consider using PointerBuf::push_front instead.

Examples

let ptr = jsonptr::Pointer::from_static("/bar");
let foobar = ptr.with_leading_token("foo");
assert_eq!(foobar, "/foo/bar");

pub fn concat(&self, other: &Pointer) -> PointerBuf

Creates an owned PointerBuf like self but with other appended to the end.

See PointerBuf::append for more details.

Note: this method allocates. If you find yourself calling it more than given pointer, consider using PointerBuf::append instead.

Examples

let ptr = jsonptr::Pointer::from_static("/foo");
let other = jsonptr::Pointer::from_static("/bar/baz");
assert_eq!(ptr.concat(other), "/foo/bar/baz");

pub fn len(&self) -> usize

This length expresses the byte count of the underlying string that represents the RFC 6091 Pointer. See also [std::str::len].

Examples

let mut ptr = jsonptr::PointerBuf::parse("/foo/bar").unwrap();
assert_eq!(ptr.len(), 8);

ptr.push_back("~");
assert_eq!(ptr.len(), 11);

pub fn is_empty(&self) -> bool

Returns true if the Pointer is empty (i.e. root).

Examples

let mut ptr = jsonptr::PointerBuf::new();
assert!(ptr.is_empty());

ptr.push_back("foo");
assert!(!ptr.is_empty());

pub fn into_buf(self: Box<Pointer>) -> PointerBuf

Converts a Box<Pointer> into a PointerBuf without copying or allocating.

Trait Implementations

impl AsRef<[u8]> for Pointer

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Pointer> for Pointer

fn as_ref(&self) -> &Pointer

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Pointer> for PointerBuf

fn as_ref(&self) -> &Pointer

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<str> for Pointer

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<Pointer> for PointerBuf

fn borrow(&self) -> &Pointer

Immutably borrows from an owned value.

impl Borrow<str> for Pointer

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl Debug for Pointer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for &'static Pointer

fn default() -> Self

Returns the “default value” for a type.

impl<'de: 'p, 'p> Deserialize<'de> for &'p Pointer

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Pointer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'t> From<&'t Pointer> for Components<'t>

fn from(pointer: &'t Pointer) -> Self

Converts to this type from the input type.

impl<'p> From<&'p Pointer> for Cow<'p, Pointer>

fn from(value: &'p Pointer) -> Self

Converts to this type from the input type.

impl From<&Pointer> for Value

fn from(ptr: &Pointer) -> Self

Converts to this type from the input type.

impl From<PointerBuf> for Box<Pointer>

fn from(value: PointerBuf) -> Self

Converts to this type from the input type.

impl Hash for Pointer

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

impl<'a> IntoIterator for &'a Pointer

type Item = Token<'a>

The type of the elements being iterated over.

type IntoIter = Tokens<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Ord for Pointer

fn cmp(&self, other: &Pointer) -> Ordering

This method returns an Ordering between self and other.

impl PartialEq<&Pointer> for PointerBuf

fn eq(&self, other: &&Pointer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<&str> for Pointer

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Pointer> for &str

fn eq(&self, other: &Pointer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Pointer> for PointerBuf

fn eq(&self, other: &Pointer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Pointer> for String

fn eq(&self, other: &Pointer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Pointer> for str

fn eq(&self, other: &Pointer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<PointerBuf> for &Pointer

fn eq(&self, other: &PointerBuf) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<PointerBuf> for Pointer

fn eq(&self, other: &PointerBuf) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'p> PartialEq<String> for &'p Pointer

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<String> for Pointer

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Pointer

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Pointer

fn eq(&self, other: &Pointer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<&Pointer> for PointerBuf

fn partial_cmp(&self, other: &&Pointer) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<&str> for &Pointer

fn partial_cmp(&self, other: &&str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Pointer> for &str

fn partial_cmp(&self, other: &Pointer) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Pointer> for PointerBuf

fn partial_cmp(&self, other: &Pointer) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Pointer> for String

fn partial_cmp(&self, other: &Pointer) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Pointer> for str

fn partial_cmp(&self, other: &Pointer) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'p> PartialOrd<PointerBuf> for &'p Pointer

fn partial_cmp(&self, other: &PointerBuf) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<PointerBuf> for Pointer

fn partial_cmp(&self, other: &PointerBuf) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<String> for &Pointer

fn partial_cmp(&self, other: &String) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<String> for Pointer

fn partial_cmp(&self, other: &String) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for Pointer

fn partial_cmp(&self, other: &Pointer) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Pointer

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl ToOwned for Pointer

type Owned = PointerBuf

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl Eq for Pointer

impl StructuralPartialEq for Pointer