[−][src]Trait json_dotpath::DotPaths

pub trait DotPaths {
    fn dot_get<T>(&self, path: &str) -> Result<Option<T>>
    where
        T: DeserializeOwned;

    fn dot_get_mut(&mut self, path: &str) -> Result<&mut Value>;

    fn dot_set<T>(&mut self, path: &str, value: T) -> Result<()>
    where
        T: Serialize;

    fn dot_replace<NEW, OLD>(
        &mut self, 
        path: &str, 
        value: NEW
    ) -> Result<Option<OLD>>
    where
        NEW: Serialize,
        OLD: DeserializeOwned;

    fn dot_take<T>(&mut self, path: &str) -> Result<Option<T>>
    where
        T: DeserializeOwned;

    fn dot_get_or<T>(&self, path: &str, def: T) -> Result<T>
    where
        T: DeserializeOwned,
    { ... }

    fn dot_get_or_default<T>(&self, path: &str) -> Result<T>
    where
        T: DeserializeOwned + Default,
    { ... }

    fn dot_remove(&mut self, path: &str) -> Result<()> { ... }
}

Access and mutate nested JSON elements by dotted paths

The path is composed of keys separated by dots, e.g. foo.bar.1.

All symbols in a path may be escaped by backslash (\) to have them treated literally, e.g. to access a key containing a period.

Arrays are indexed by numeric strings or special keys (see dot_get() and dot_set()).

This trait is implemented for serde_json::Value, specifically the Map, Array, and Null variants. Empty path can also be used to access a scalar.

Methods on this trait do not panic, errors are passed to the caller.

Required methods

fn dot_get<T>(&self, path: &str) -> Result<Option<T>> where
    T: DeserializeOwned, 

Get an item by path, if present.

If the element does not exist or is null, None is returned. Accessing array index out of range raises Err(BadIndex).

The path does not need to reach a leaf node, i.e. it is possible to extract a subtree of a JSON object this way.

Special symbols

  • > ... last element of an array
  • < ... first element of an array (same as 0)

fn dot_get_mut(&mut self, path: &str) -> Result<&mut Value>

Get a mutable reference to an item

If the path does not exist but a value on the path can be created (i.e. because the path reaches null, array or object), a null value is inserted in that location (creating its parent nodes as needed) and a mutable reference to this new null node is returned.

The path does not need to reach a leaf node, i.e. it is possible to extract a subtree of a JSON object this way.

Special keys

  • > ... last element of an array
  • < ... first element of an array (same as 0)

fn dot_set<T>(&mut self, path: &str, value: T) -> Result<()> where
    T: Serialize, 

Insert an item by path. The original value is dropped, if any.

Special symbols

Arrays can be modified using special keys in the path:

  • + or >> ... append
  • - or << ... prepend
  • >n ... insert after an index n
  • <n ... insert before an index n
  • > ... last element of an array
  • < ... first element of an array (same as 0)

fn dot_replace<NEW, OLD>(
    &mut self,
    path: &str,
    value: NEW
) -> Result<Option<OLD>> where
    NEW: Serialize,
    OLD: DeserializeOwned, 

Replace a value by path with a new value. The value types do not have to match.

Returns Ok(None) if the path was previously empty or null.

Special keys

  • > ... last element of an array
  • < ... first element of an array (same as 0)

fn dot_take<T>(&mut self, path: &str) -> Result<Option<T>> where
    T: DeserializeOwned, 

Get an item using a path, removing it from the object.

Value becomes null when taken by an empty path, map entry is removed, and array item is extracted, shifting the remainder forward.

Returns Ok(None) if the path was previously empty or null.

Special keys

  • > ... last element of an array
  • < ... first element of an array (same as 0)
Loading content...

Provided methods

fn dot_get_or<T>(&self, path: &str, def: T) -> Result<T> where
    T: DeserializeOwned, 

Get an item by path, or a default value if it does not exist.

This method is best suited for JSON objects (Map) or nullable fields.

See dot_get() for more details.

fn dot_get_or_default<T>(&self, path: &str) -> Result<T> where
    T: DeserializeOwned + Default, 

Get an item, or a default value using the Default trait

This method is best suited for JSON objects (Map) or nullable fields.

See dot_get() for more details.

fn dot_remove(&mut self, path: &str) -> Result<()>

Remove and drop an item matching a key. Returns true if any item was removed.

Special keys

  • > ... last element of an array
  • < ... first element of an array (same as 0)
Loading content...

Implementations on Foreign Types

impl DotPaths for Value[src]

impl DotPaths for Map<String, Value>[src]

impl DotPaths for Vec<Value>[src]

Loading content...

Implementors

Loading content...