pub struct Pointer(/* private fields */);Expand description
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§
Source§impl Pointer
impl Pointer
Sourcepub fn parse<S>(s: &S) -> Result<&Pointer, ParseError>
pub fn parse<S>(s: &S) -> Result<&Pointer, 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.
Sourcepub const fn from_static(s: &'static str) -> &'static Pointer
pub const fn from_static(s: &'static str) -> &'static Pointer
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");Sourcepub fn to_buf(&self) -> PointerBuf
pub fn to_buf(&self) -> PointerBuf
Converts into an owned PointerBuf
Sourcepub fn to_json_value(&self) -> Value
pub fn to_json_value(&self) -> Value
Returns a serde_json::Value representation of this Pointer
Sourcepub fn first(&self) -> Option<Token<'_>>
pub fn first(&self) -> Option<Token<'_>>
Returns the first Token in the Pointer.
alias for front
Sourcepub fn split_front(&self) -> Option<(Token<'_>, &Pointer)>
pub fn split_front(&self) -> Option<(Token<'_>, &Pointer)>
Splits the Pointer into the first Token and a remainder Pointer.
Sourcepub fn split_at(&self, offset: usize) -> Option<(&Pointer, &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 8All 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);Sourcepub fn split_back(&self) -> Option<(&Pointer, Token<'_>)>
pub fn split_back(&self) -> Option<(&Pointer, Token<'_>)>
Splits the Pointer into the parent path and the last Token.
Sourcepub fn strip_suffix<'a>(&'a self, suffix: &Pointer) -> Option<&'a Pointer>
pub fn strip_suffix<'a>(&'a self, suffix: &Pointer) -> Option<&'a Pointer>
Returns the pointer stripped of the given suffix.
Sourcepub fn strip_prefix<'a>(&'a self, prefix: &Pointer) -> Option<&'a Pointer>
pub fn strip_prefix<'a>(&'a self, prefix: &Pointer) -> Option<&'a Pointer>
Returns the pointer stripped of the given prefix.
Sourcepub fn get(&self, index: usize) -> Option<Token<'_>>
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);Sourcepub fn resolve<'v, R>(
&self,
value: &'v R,
) -> Result<&'v <R as Resolve>::Value, <R as Resolve>::Error>where
R: Resolve,
pub fn resolve<'v, R>(
&self,
value: &'v R,
) -> Result<&'v <R as Resolve>::Value, <R as Resolve>::Error>where
R: Resolve,
Sourcepub fn resolve_mut<'v, R>(
&self,
value: &'v mut R,
) -> Result<&'v mut <R as ResolveMut>::Value, <R as ResolveMut>::Error>where
R: ResolveMut,
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:
Sourcepub fn intersection<'a>(&'a self, other: &Pointer) -> &'a Pointer
pub fn intersection<'a>(&'a self, other: &Pointer) -> &'a Pointer
Finds the commonality between this and another Pointer.
Sourcepub fn delete<D>(&self, value: &mut D) -> Option<<D as Delete>::Value>where
D: Delete,
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
Pointercan be resolved, theValueis deleted and returned. - If the
Pointerfails to resolve for any reason,Ok(None)is returned. - If the
Pointeris root,valueis 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());Sourcepub fn assign<D, V>(
&self,
dest: &mut D,
src: V,
) -> Result<Option<<D as Assign>::Value>, <D as Assign>::Error>
pub fn assign<D, V>( &self, dest: &mut D, src: V, ) -> Result<Option<<D as Assign>::Value>, <D as Assign>::Error>
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.
Sourcepub fn components(&self) -> Components<'_>
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);Sourcepub fn with_trailing_token<'t>(&self, token: impl Into<Token<'t>>) -> PointerBuf
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");Sourcepub fn with_leading_token<'t>(&self, token: impl Into<Token<'t>>) -> PointerBuf
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");Sourcepub fn concat(&self, other: &Pointer) -> PointerBuf
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");Sourcepub fn len(&self) -> usize
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);