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: AsRef<str> + ?Sized>(s: &S) -> Result<&Self, ParseError>
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.
sourcepub const fn from_static(s: &'static str) -> &'static Self
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");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<'_>, &Self)>
pub fn split_front(&self) -> Option<(Token<'_>, &Self)>
Splits the Pointer into the first Token and a remainder Pointer.
sourcepub fn split_at(&self, offset: usize) -> Option<(&Self, &Self)>
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 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<(&Self, Token<'_>)>
pub fn split_back(&self) -> Option<(&Self, Token<'_>)>
Splits the Pointer into the parent path and the last Token.
sourcepub fn strip_suffix<'a>(&'a self, suffix: &Self) -> Option<&'a Self>
pub fn strip_suffix<'a>(&'a self, suffix: &Self) -> Option<&'a Self>
Returns the pointer stripped of the given suffix.
sourcepub fn strip_prefix<'a>(&'a self, prefix: &Self) -> Option<&'a Self>
pub fn strip_prefix<'a>(&'a self, prefix: &Self) -> Option<&'a Self>
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: Resolve>(
&self,
value: &'v R,
) -> Result<&'v R::Value, R::Error>
pub fn resolve<'v, R: Resolve>( &self, value: &'v R, ) -> Result<&'v R::Value, R::Error>
sourcepub fn resolve_mut<'v, R: ResolveMut>(
&self,
value: &'v mut R,
) -> Result<&'v mut R::Value, R::Error>
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:
sourcepub fn intersection<'a>(&'a self, other: &Self) -> &'a Self
pub fn intersection<'a>(&'a self, other: &Self) -> &'a Self
Finds the commonality between this and another Pointer.
sourcepub fn delete<D: Delete>(&self, value: &mut D) -> Option<D::Value>
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
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::Value>, D::Error>
pub fn assign<D, V>( &self, dest: &mut D, src: V, ) -> Result<Option<D::Value>, D::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 barbaz = jsonptr::Pointer::from_static("/bar/baz");
assert_eq!(ptr.concat(&barbaz), "/foo/bar/baz");