Struct PointerBuf

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

An owned, mutable Pointer (akin to String).

This type provides methods like PointerBuf::push_back and PointerBuf::replace that mutate the pointer in place. It also implements core::ops::Deref to Pointer, meaning that all methods on Pointer slices are available on PointerBuf values as well.

Implementations

impl PointerBuf

pub fn root() -> Self

Creates a new PointerBuf pointing to a document root.

This is an alias to Self::new.

pub fn new() -> Self

Creates a new PointerBuf pointing to a document root.

pub unsafe fn new_unchecked(s: impl Into<String>) -> Self

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

Safety

The provided string must adhere to RFC 6901.

pub fn parse(s: impl Into<String>) -> Result<Self, RichParseError>

Attempts to parse a string into a PointerBuf.

Errors

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

pub fn from_tokens<'t>(tokens: impl IntoIterator<Item: Into<Token<'t>>>) -> Self

Creates a new PointerBuf from a slice of non-encoded strings.

pub fn as_ptr(&self) -> &Pointer

Coerces to a Pointer slice.

pub fn push_front<'t>(&mut self, token: impl Into<Token<'t>>)

Pushes a Token onto the front of this Pointer.

pub fn push_back<'t>(&mut self, token: impl Into<Token<'t>>)

Pushes a Token onto the back of this Pointer.

pub fn pop_back(&mut self) -> Option<Token<'static>>

Removes and returns the last Token in the Pointer if it exists.

pub fn pop_front(&mut self) -> Option<Token<'static>>

Removes and returns the first Token in the Pointer if it exists.

pub fn append<P: AsRef<Pointer>>(&mut self, other: P) -> &PointerBuf

Merges two Pointers by appending other onto self.

pub fn replace<'t>( &mut self, index: usize, token: impl Into<Token<'t>>, ) -> Result<Option<Token<'_>>, ReplaceError>

Attempts to replace a Token by the index, returning the replaced Token if it already exists. Returns None otherwise.

Errors

A [ReplaceError] is returned if the index is out of bounds.

pub fn clear(&mut self)

Clears the Pointer, setting it to root ("").

Methods from Deref<Target = Pointer>

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());

Trait Implementations

impl AsRef<Pointer> for PointerBuf

fn as_ref(&self) -> &Pointer

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 Clone for PointerBuf

fn clone(&self) -> PointerBuf

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PointerBuf

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

Formats the value using the given formatter.

impl Default for PointerBuf

fn default() -> PointerBuf

Returns the “default value” for a type.

impl Deref for PointerBuf

type Target = Pointer

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for PointerBuf

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for PointerBuf

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

Formats the value using the given formatter.

impl From<PointerBuf> for Box<Pointer>

fn from(value: PointerBuf) -> Self

Converts to this type from the input type.

impl From<PointerBuf> for Cow<'static, Pointer>

fn from(value: PointerBuf) -> Self

Converts to this type from the input type.

impl From<Token<'_>> for PointerBuf

fn from(t: Token<'_>) -> Self

Converts to this type from the input type.

impl From<usize> for PointerBuf

fn from(value: usize) -> Self

Converts to this type from the input type.

impl FromStr for PointerBuf

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for PointerBuf

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

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> IntoIterator for &'a PointerBuf

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 PointerBuf

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

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 PointerBuf

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 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<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 &str

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 PartialEq<PointerBuf> for String

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 str

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<String> for PointerBuf

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 PointerBuf

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 PointerBuf

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 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 PointerBuf

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 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<'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 &str

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<PointerBuf> for String

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 str

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 PointerBuf

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 PointerBuf

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 Serialize for PointerBuf

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&str> for PointerBuf

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<String> for PointerBuf

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for PointerBuf

impl StructuralPartialEq for PointerBuf