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 new() -> PointerBuf

Creates a new PointerBuf pointing to a document root.

pub fn parse<S>(s: &S) -> Result<PointerBuf, ParseError>

where S: AsRef<str> + ?Sized,

Attempts to parse a string into a PointerBuf.

Errors

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

pub fn from_tokens<'a, T>(tokens: impl IntoIterator<Item = T>) -> PointerBuf

where T: Into<Token<'a>>,

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>(&mut self, other: P) -> &PointerBuf

where P: AsRef<Pointer>,

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<'_>, &Pointer)>

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

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

Splits the Pointer at the given index if the character at the index is a separator backslash ('/'), 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<(&Pointer, Token<'_>)>

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

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

A pointer to the parent of the current path.

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

Returns the pointer stripped of the given suffix.

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

Returns the pointer stripped of the given prefix.

pub fn get(&self, index: usize) -> Option<Token<'_>>

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");
assert_eq!(ptr.get(0), Some("foo".into()));
assert_eq!(ptr.get(1), Some("bar".into()));
assert_eq!(ptr.get(2), None);

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

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

where R: Resolve,

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>( &self, value: &'v mut R, ) -> Result<&'v mut <R as ResolveMut>::Value, <R as ResolveMut>::Error>

where R: ResolveMut,

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: &Pointer) -> &'a Pointer

Finds the commonality between this and another Pointer.

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

where D: Delete,

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 as Assign>::Value>, <D as Assign>::Error>

where D: Assign, V: Into<<D as Assign>::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 once for a 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::Pointer::from_static("/foo/bar").to_buf();
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 copy 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<(), Error>

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) -> &<PointerBuf as Deref>::Target

Dereferences the value.

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

fn deserialize<D>( deserializer: D, ) -> Result<PointerBuf, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for PointerBuf

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

Formats the value using the given formatter.

impl From<Token<'_>> for PointerBuf

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

Converts to this type from the input type.

impl From<usize> for PointerBuf

fn from(value: usize) -> PointerBuf

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<PointerBuf, <PointerBuf as FromStr>::Err>

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

impl Hash for PointerBuf

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

where __H: Hasher,

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) -> <&'a PointerBuf as IntoIterator>::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 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 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 as Serializer>::Ok, <S as Serializer>::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<PointerBuf, <PointerBuf as TryFrom<&str>>::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<PointerBuf, <PointerBuf as TryFrom<String>>::Error>

Performs the conversion.

impl Eq for PointerBuf

impl StructuralPartialEq for PointerBuf