Trait JsonValueExt

pub trait JsonValueExt {
    // Required methods
    fn x_new_object() -> Value;
    fn x_contains<T: DeserializeOwned>(&self, name_or_pointer: &str) -> bool;
    fn x_get<T: DeserializeOwned>(
        &self,
        name_or_pointer: &str,
    ) -> Result<T, JsonValueExtError>;
    fn x_get_as<'a, T: AsType<'a>>(
        &'a self,
        name_or_pointer: &str,
    ) -> Result<T, JsonValueExtError>;
    fn x_take<T: DeserializeOwned>(
        &mut self,
        name_or_pointer: &str,
    ) -> Result<T, JsonValueExtError>;
    fn x_insert<T: Serialize>(
        &mut self,
        name_or_pointer: &str,
        value: T,
    ) -> Result<(), JsonValueExtError>;
    fn x_walk<F>(&mut self, callback: F) -> bool
       where F: FnMut(&mut Map<String, Value>, &str) -> bool;
    fn x_pretty(&self) -> Result<String, JsonValueExtError>;

    // Provided methods
    fn x_get_str(
        &self,
        name_or_pointer: &str,
    ) -> Result<&str, JsonValueExtError> { ... }
    fn x_get_i64(&self, name_or_pointer: &str) -> Result<i64, JsonValueExtError> { ... }
    fn x_get_f64(&self, name_or_pointer: &str) -> Result<f64, JsonValueExtError> { ... }
    fn x_get_bool(
        &self,
        name_or_pointer: &str,
    ) -> Result<bool, JsonValueExtError> { ... }
}

Extension trait for working with JSON values in a more convenient way.

JsonValueExt offers convenient methods for interacting with serde_json::Value objects, simplifying tasks like getting, taking, inserting, traversing, and pretty-printing JSON data while ensuring type safety with Serde’s serialization and deserialization.

Provided Methods

• x_get: Returns a value of a specified type T from a JSON object using either a direct name or a pointer path. (will do a new allocation)
• x_get_as: Returns a reference of a specified type T from a JSON object using either a direct name or a pointer path.
• x_get_str: Returns a &str from a JSON object using either a direct name or a pointer path.
• x_get_i64: Returns an i64 from a JSON object using either a direct name or a pointer path.
• x_get_f64: Returns an f64 from a JSON object using either a direct name or a pointer path.
• x_get_bool: Returns a bool from a JSON object using either a direct name or a pointer path.
• x_take: Takes a value from a JSON object using a specified name or pointer path, replacing it with Null.
• x_insert: Inserts a value of type T into a JSON object at the specified name or pointer path, creating any missing objects along the way.
• x_walk: Traverses all properties within the JSON value tree, applying a user-provided callback function on each property.
• x_pretty: Returns a pretty-printed string representation of the JSON value.

Usage

This trait is intended to be used with serde_json::Value objects. It is particularly useful when you need to manipulate JSON structures dynamically or when the structure of the JSON is not known at compile time.

use serde_json::{Value, Map};
use serde::de::DeserializeOwned;
use serde::Serialize;
use your_crate::JsonValueExt;

fn example_usage(json: &mut Value) -> Result<(), Box<dyn std::error::Error>> {
    // Get a value from JSON
    let name: String = json.x_get("/name")?;

    // Take a value from JSON, replacing it with `Null`
    let age: u32 = json.x_take("age")?;

    // Insert a new value into JSON
    json.x_insert("city", "New York")?;

    // Walk through the JSON properties
    json.x_walk(|parent_map, property_name| {
        println!("Property: {}", property_name);
        true // Continue traversal
    });

    // Get a pretty-printed JSON string
    let pretty_json = json.x_pretty()?;
    println!("{}", pretty_json);

    Ok(())
}

This trait enhances the serde_json::Value API by adding more type-safe and convenient methods for manipulating JSON data in Rust.

Required Methods

fn x_new_object() -> Value

fn x_contains<T: DeserializeOwned>(&self, name_or_pointer: &str) -> bool

fn x_get<T: DeserializeOwned>( &self, name_or_pointer: &str, ) -> Result<T, JsonValueExtError>

Returns an owned type T for a given name or pointer path.

• name_or_pointer: Can be a direct name or a pointer path (if it starts with ‘/’).

fn x_get_as<'a, T: AsType<'a>>( &'a self, name_or_pointer: &str, ) -> Result<T, JsonValueExtError>

Returns a reference of type T (or value for copy type) for a given name or pointer path. Use this one over x_get to avoid string allocation and get only the &str

• name_or_pointer: Can be a direct name or a pointer path (if it starts with ‘/’).

fn x_take<T: DeserializeOwned>( &mut self, name_or_pointer: &str, ) -> Result<T, JsonValueExtError>

Takes the value at the specified name or pointer path and replaces it with Null.

• name_or_pointer: Can be a direct name or a pointer path (if it starts with ‘/’).

fn x_insert<T: Serialize>( &mut self, name_or_pointer: &str, value: T, ) -> Result<(), JsonValueExtError>

Inserts a new value of type T at the specified name or pointer path. This method creates missing Value::Object entries as needed.

• name_or_pointer: Can be a direct name or a pointer path (if it starts with ‘/’).

fn x_walk<F>(&mut self, callback: F) -> bool

where F: FnMut(&mut Map<String, Value>, &str) -> bool,

Walks through all properties in the JSON value tree and calls the callback function on each.

• The callback signature is (parent_map, property_name) -> bool.
  • Returns false to stop the traversal; returns true to continue.

Returns:

• true if the traversal completes without stopping early.
• false if the traversal is stopped early because the callback returned false.

fn x_pretty(&self) -> Result<String, JsonValueExtError>

Returns a pretty-printed string representation of the JSON value.

Provided Methods

fn x_get_str(&self, name_or_pointer: &str) -> Result<&str, JsonValueExtError>

Returns a &str if present (shortcut for x_get_as::<&str>(...))

fn x_get_i64(&self, name_or_pointer: &str) -> Result<i64, JsonValueExtError>

Returns an i64 if present (shortcut for x_get_as::<i64>(...))

fn x_get_f64(&self, name_or_pointer: &str) -> Result<f64, JsonValueExtError>

Returns an f64 if present (shortcut for x_get_as::<f64>(...))

fn x_get_bool(&self, name_or_pointer: &str) -> Result<bool, JsonValueExtError>

Returns a bool if present (shortcut for x_get_as::<bool>(...))

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl JsonValueExt for Value

fn x_walk<F>(&mut self, callback: F) -> bool

where F: FnMut(&mut Map<String, Value>, &str) -> bool,

Walks through all properties of a JSON value tree and calls the callback function on each property.

• The callback signature is (parent_map, property_name) -> bool.
  • Return false from the callback to stop the traversal; return true to continue.

Returns:

• true if the traversal completed to the end without being stopped early.
• false if the traversal was stopped early because the callback returned false.

fn x_new_object() -> Value

fn x_contains<T: DeserializeOwned>(&self, name_or_pointer: &str) -> bool

fn x_get<T: DeserializeOwned>( &self, name_or_pointer: &str, ) -> Result<T, JsonValueExtError>

fn x_get_as<'a, T: AsType<'a>>( &'a self, name_or_pointer: &str, ) -> Result<T, JsonValueExtError>

fn x_take<T: DeserializeOwned>( &mut self, name_or_pointer: &str, ) -> Result<T, JsonValueExtError>

fn x_insert<T: Serialize>( &mut self, name_or_pointer: &str, value: T, ) -> Result<(), JsonValueExtError>

fn x_pretty(&self) -> Result<String, JsonValueExtError>

Implementors