json_pointer_simd/
lib.rs

1//! A crate for parsing and using JSON pointers with [simd_json] and [serde_json] values.
2//! 
3//! The functionality is specified in [RFC 6901](https://tools.ietf.org/html/rfc6901). 
4//! 
5//! In the case of [serde_json], unlike nlike the `pointer` method, this handles both 
6//! validating JSON Pointers before use and the URI Fragment Identifier Representation.
7//! 
8//! In the case of [simd_json], this crate provides that missing functionality.
9//!
10//! ## Creating a JSON Pointer
11//! 
12//! JSON pointers can be parsed from any thing that can interpreted a s string slice 
13//! expressed in standard JSON Pointer syntax, or created from anything that can be 
14//! loosely represented as a vector or array of `&str`.
15//! 
16//! ```rust
17//! use json_pointer_simd::{JsonPointer,JsonPointerTarget};
18//!
19//! let from_strs = JsonPointer::new([
20//!     "foo",
21//!     "bar",
22//! ]);
23//! let parsed = "/foo/bar".parse::<JsonPointer<_, _>>().unwrap();
24//! let from_dotted_notation = JsonPointer::new("foo.bar".split('.').collect::<Vec<&str>>());
25//! 
26//! assert_eq!(from_strs.to_string(), parsed.to_string());
27//! assert_eq!(from_strs.to_string(), from_dotted_notation.to_string());
28//! ```
29//! 
30//! ## Using a JSON Pointer
31//! 
32//! The `JsonPointerTarget` trait provides `.get()` and `.get_mut()`, to get references
33//! and mutable references to the appropriate value, respectively.
34//! 
35//! As delivered, this is implemented on [serde_json] values and [simd_json] values, though
36//! the former is a little more verbose to use than the latter due to the pre-existence of
37//! these methods on [serde_json] values 
38//! 
39//! For [simd_json]:
40//! 
41//! ```rust
42//! use simd_json::json;
43//! use json_pointer_simd::{JsonPointer,JsonPointerTarget};
44//!
45//! let ptr = "/foo/bar".parse::<JsonPointer<_, _>>().unwrap();
46//! 
47//! let document = json!({
48//!     "foo": {
49//!         "bar": 0,
50//!         "baz": 1,
51//!     },
52//!     "quux": "xyzzy"
53//! });
54//! let indexed = document.get(&ptr).unwrap();
55//! 
56//! assert_eq!(indexed, &json!(0));
57//! ```
58//! 
59//! For [serde_json]:
60//! 
61//! ```rust
62//! use serde_json::{json, Value};
63//! use json_pointer_simd::{JsonPointer,JsonPointerTarget};
64//!
65//! let ptr = "/foo/bar".parse::<JsonPointer<_, _>>().unwrap();
66//! 
67//! let document = json!({
68//!     "foo": {
69//!         "bar": 0,
70//!         "baz": 1,
71//!     },
72//!     "quux": "xyzzy"
73//! });
74//! let indexed = <Value as JsonPointerTarget>::get(&document,&ptr).unwrap();
75//! 
76//! assert_eq!(indexed, &json!(0));
77//! ```
78//! 
79//! ## URI Fragment Identifier Representation
80//! 
81//! JSON Pointers can be embedded in the fragment portion of a URI. This is the
82//! reason why most JSON pointer libraries require a `#` character at the beginning
83//! of a JSON pointer. The crate will detect the leading `#` as an indicator to
84//! parse in URI Fragment Identifier Representation. Note that this means that this
85//! crate does not support parsing full URIs.
86//! 
87//! ```rust
88//! use json_pointer_simd::{JsonPointer,JsonPointerTarget};
89//!
90//! let str_ptr = "/f%o".parse::<JsonPointer<_, _>>().unwrap();
91//! let uri_ptr = "#/f%25o".parse::<JsonPointer<_, _>>().unwrap();
92//! 
93//! assert_eq!(str_ptr, uri_ptr);
94//! ```
95
96#![deny(missing_docs)]
97
98mod parser;
99mod owned;
100mod borrowed;
101mod value;
102mod ptr;
103
104pub use parser::ParseError;
105pub use ptr::IndexError;
106pub use ptr::JsonPointer;
107
108///
109/// The trait that provides access to the data referenced by the JsonPointer.
110///
111pub trait JsonPointerTarget 
112    where Self: Sized{
113
114    /// Attempts to get a reference to a value from self,
115    /// returning an error if it can't be found.
116	fn get<'json,S: AsRef<str>, C: AsRef<[S]>>(&'json self, ptr: &JsonPointer<S,C>) -> Result<&'json Self, IndexError>;
117    /// Attempts to get a mutable reference to a value from self
118    /// returning an error if it can't be found.
119	fn get_mut<'json,S: AsRef<str>, C: AsRef<[S]>>(&'json mut self, ptr: &JsonPointer<S,C>) -> Result<&'json mut Self, IndexError>;
120    /// Attempts to get an owned value from self, returning an
121    /// error if it can't be found.
122	fn get_owned<S: AsRef<str>, C: AsRef<[S]>>(self, ptr: &JsonPointer<S,C>) -> Result<Self, IndexError>;
123}
json_pointer_simd/lib.rs

json_pointer_simd/
lib.rs
