importcjj / rust-ajson

Rust port of gjson，get JSON value by dotpath syntax

A-JSON

Read JSON values quickly - Rust JSON Parser

change name to AJSON, see issue

Inspiration comes from gjson in golang

Installation

Add it to your Cargo.toml file:

[dependencies]
ajson = "0.3"

Todo

• Add documentation
• Follow api-guidelines
• Update benchmark
• Optimize

A simple example

AJSON get json value with specified path, such as project.name or project.version. When the path matches, it returns immediately!

let data = r#"
{
  "project": {
    "name": "ajson",
    "maintainer": "importcjj",
    "version": 0.1,
    "rusts": ["stable", "nightly"]
  }
}
"#;

let name = ajson::get(data, "project.name").unwrap().unwrap();
println!("{}", name.as_str()); // ajson

Path Syntax

JSON example

{
    "name": {"first": "Tom", "last": "Anderson"},
    "age":37,
    "children": ["Sara","Alex","Jack"],
    "fav.movie": "Deer Hunter",
    "friends": [
        {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
        {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
        {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
    ]
}

basic

Below is a quick overview of the path syntax, for more complete information please check out GJSON Syntax.

A path is a series of keys separated by a dot. A key may contain special wildcard characters '*' and '?'. To access an array value use the index as the key. To get the number of elements in an array or to access a child path, use the '#' character. The dot and wildcard characters can be escaped with ''.

name.last        >> "Anderson"
age              >> 37
children         >> ["Sara","Alex","Jack"]
children.#       >> 3
children.1       >> "Alex"
child*.2         >> "Jack"
c?ildren.0       >> "Sara"
fav\.movie       >> "Deer Hunter"
friends.#.first  >> ["Dale","Roger","Jane"]
friends.1.last   >> "Craig"

Escape character

Special purpose characters, such as ., *, and ? can be escaped with .

fav\.movie             "Deer Hunter"

Arrays

The # character allows for digging into JSON Arrays.To get the length of an array you'll just use the # all by itself.

friends.#              3
friends.#.age         [44,68,47]

queries

You can also query an array for the first match by using #(...), or find all matches with #(...)#. Queries support the ==, !=, <, <=, >, >= comparison operators and the simple pattern matching % (like) and !% (not like) operators.

friends.#(last=="Murphy").first   >> "Dale"
friends.#(last=="Murphy")#.first  >> ["Dale","Jane"]
friends.#(age>45)#.last           >> ["Craig","Murphy"]
friends.#(first%"D*").last        >> "Murphy"
friends.#(nets.#(=="fb"))#.first  >> ["Dale","Roger"]

construct

Basically, you can use selectors to assemble whatever you want, and of course, the result is still a json ;)

{name.first,age,"murphys":friends.#(last="Murphy")#.first}
[name.first,age,children.0]

ajson::get(json, "name.[first,last]").unwrap().unwrap().to_vec();
ajson::get(json, "name.first").unwrap().unwrap(); 
ajson::get(json, "name.last").unwrap().unwrap();

Value

Value types.

enum Value {
    String(String),
    Number(Number),
    Object(String),
    Array(String),
    Boolean(bool),
    Null,
}

Value has a number of methods that meet your different needs.

value.get(&str) -> Option<Value>
value.as_str() -> &str
value.as_u64() -> u64
value.as_i64() -> i64
value.as_f64() -> f64
value.as_bool() -> bool
value.as_vec() -> Vec<Value>
value.as_object() -> HashMap<String, Value>

value.is_number() -> bool
value.is_string() -> bool
value.is_bool() -> bool
value.is_object() -> bool
value.is_array() -> bool
value.is_null() -> bool

Performance

$ cargo bench

• ajson
• serde_json
• rust-json

ajson benchmark         time:   [2.0816 us 2.0865 us 2.0917 us]                             
                        change: [+0.6172% +0.9272% +1.2430%] (p = 0.00 < 0.05)
                        Change within noise threshold.
Found 11 outliers among 100 measurements (11.00%)
  7 (7.00%) high mild
  4 (4.00%) high severe

serde_json benchmark    time:   [23.033 us 23.076 us 23.119 us]                                  
                        change: [-0.7185% -0.3455% +0.0230%] (p = 0.07 > 0.05)
                        No change in performance detected.
Found 7 outliers among 100 measurements (7.00%)
  6 (6.00%) high mild
  1 (1.00%) high severe

json-rust benchmark     time:   [12.225 us 12.289 us 12.381 us]                                 
                        change: [-2.6200% -1.1789% +0.8442%] (p = 0.19 > 0.05)
                        No change in performance detected.
Found 9 outliers among 100 measurements (9.00%)
  5 (5.00%) high mild
  4 (4.00%) high severe

ajson selector          time:   [1.1523 us 1.1561 us 1.1604 us]                            
                        change: [+0.1567% +0.7278% +1.2945%] (p = 0.01 < 0.05)
                        Change within noise threshold.
Found 3 outliers among 100 measurements (3.00%)
  3 (3.00%) high mild

ajson multi query       time:   [559.19 ns 559.96 ns 560.77 ns]                               
                        change: [-1.4268% -1.0380% -0.6698%] (p = 0.00 < 0.05)
                        Change within noise threshold.
Found 3 outliers among 100 measurements (3.00%)
  3 (3.00%) high mild

serde derive            time:   [4.5301 us 4.5403 us 4.5507 us]                          
                        change: [-2.3423% -1.9438% -1.5697%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 2 outliers among 100 measurements (2.00%)
  2 (2.00%) high mild

serde derive multi query                        
                        time:   [956.86 ns 962.64 ns 970.05 ns]
                        change: [-1.7069% -1.0299% -0.2924%] (p = 0.01 < 0.05)
                        Change within noise threshold.
Found 9 outliers among 100 measurements (9.00%)
  3 (3.00%) high mild
  6 (6.00%) high severe

nom json bench          time:   [2.9468 us 2.9515 us 2.9566 us]
Found 5 outliers among 100 measurements (5.00%)
  4 (4.00%) high mild
  1 (1.00%) high severe

• MacBook Pro (14-inch, 2021)
• Apple M1 Pro
• 16 GB

License

MIT License.

rust-ajson's Issues

Project ownership

hi @importcjj

I don't know how else to get in contact with you. Could you help me with this issue importcjj/mobc#68

Multiple conditions in queries

Hello!
First of all, thanks for this project.

Could you please add conditions operators AND, OR for using multiple conditions in one query?

For example:

let json_string = r#"
{
    "customFields": [
        {
            "projectCustomField": {
                "id": "1",
                "$type": "EnumProjectCustomField"
            },
            "value": {
                "localizedName": null,
                "description": null,
                "name": "High",
                "id": "3",
                "$type": "EnumBundleElement"
            },
            "name": "Priority",
            "id": "1",
            "$type": "SingleEnumIssueCustomField"
        },
        {
            "projectCustomField": {
                "id": "2",
                "$type": "EnumProjectCustomField"
            },
            "value": {
                "localizedName": null,
                "description": null,
                "name": "Bug",
                "id": "3",
                "$type": "EnumBundleElement"
            },
            "name": "Type",
            "id": "2",
            "$type": "SingleEnumIssueCustomField"
        },
    ]
}"#;

let prioroty= ajson::get(json_string, r#"customFields.#($type == "SingleEnumIssueCustomField" && name == "Priority").value.name"#).map(|s| s.to_string());

Some([]) using get_from_read

Hello! I have a json that looks like this:

{
  "ids":[1, 2, 3,4, 5]
}

When I run this:

extern crate ajson;
use std::fs::File;

fn main() {
	let f = File::open("ids.json").unwrap();
	let value = ajson::get_from_read(f, "ids.#.1");
	println!("{:?}", value);
}

I simply get Some([]) as a result. Have I done anything wrong?

Thank you for this library by the way :)

bracket in array value

Hi,

There is a bug when a bracket sits in array's value.

#[test]
fn test_bracket_in_array() {
let json = r##"{
"children": ["Sara","Alex]","Jack"],
"##;
let r = parse(json).unwrap();
assert_eq!(r.get("children.#").unwrap().to_i64(), 3);
assert_eq!(r.get("children").unwrap().to_vec(), vec!["Sara", "Alex]", "Jack"]);
assert_eq!(r.get("children.1").unwrap(), "Alex]");
assert_eq!(r.get("child*.2").unwrap(), "Jack");
assert_eq!(r.get("c?ildren.0").unwrap(), "Sara");
}

---- test_bracket_in_array stdout ----
thread 'test_bracket_in_array' panicked at 'assertion failed: (left == right)
left: ["Sara", "Alex]"],
right: ["Sara", "Alex]", "Jack"]', tests/test_ajson.rs:590:5
note: run with RUST_BACKTRACE=1 environment variable to display a backtrace.

Crate name on Crates.io

Hi, nice work on porting gjson from Go to Rust.

I'm the creator and maintainer of the official gjson project and the gjson specification.

I noticed that you chose to use the crate name gjson in crates.io. It so happens that the official Rust version of gjson is currently in development.

I'm asking you if you could assign the ownership of the name to me as I believe the Rust community would benefit from having the gjson crate name point to the official project.
https://crates.io/policies#package-ownership

Opening this issue to raise the concern as early as possible, because changing the crate name is easier at the early stage of the project.

Handle unicode character in json object keys

Thanks for writing a very useful library.

I think currently library doesn't handle unicode characters in object keys.

    let data = r#"{"sample_unicode\u0041": "abc\u0041\u0042"}"#;

    let name = ajson::parse(data).unwrap();
    dbg!(name);

    {
        dbg!(ajson::get(data, "sample_unicodeA"));

        dbg!(ajson::get(data, "sample_unicode\\u0041"));
    }

    {
        let v: Value = serde_json::from_str(data).unwrap();
        dbg!(&v["sample_unicodeA"]);
    }

Output:

[src/main.rs:10] name = {"sample_unicode\u0041": "abc\u0041\u0042"}
[src/main.rs:13] ajson::get(data, "sample_unicodeA") = None
[src/main.rs:15] ajson::get(data, "sample_unicode\\u0041") = Some(
    "abcAB",
)
[src/main.rs:20] &v["sample_unicodeA"] = String(
    "abcAB",
)

If you willing to accept PRs, I will try to fix this issue and add necessary test cases.

performance comparison between rust-ajson with gjson.rs

I forked your benches to test the speed of ajson and gjson.rs. Below is the result::

ajson benchmark         time:   [9.1979 us 9.2489 us 9.3066 us]
                        change: [-10.706% -9.1719% -7.6992%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 2 outliers among 100 measurements (2.00%)
  2 (2.00%) high mild

gjson benchmark         time:   [3.6221 us 3.6413 us 3.6623 us]
                        change: [-15.350% -12.966% -10.873%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 6 outliers among 100 measurements (6.00%)
  3 (3.00%) high mild
  3 (3.00%) high severe

serde_json benchmark    time:   [59.616 us 59.876 us 60.162 us]
                        change: [-14.793% -12.771% -10.900%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 9 outliers among 100 measurements (9.00%)
  1 (1.00%) low mild
  2 (2.00%) high mild
  6 (6.00%) high severe

json-rust benchmark     time:   [29.568 us 29.729 us 29.894 us]
                        change: [-15.512% -14.014% -12.561%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 5 outliers among 100 measurements (5.00%)
  1 (1.00%) low mild
  3 (3.00%) high mild
  1 (1.00%) high severe

ajson selector          time:   [3.0875 us 3.1000 us 3.1139 us]
                        change: [-11.651% -10.079% -8.4826%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 5 outliers among 100 measurements (5.00%)
  5 (5.00%) high mild

gjson selector          time:   [2.0724 us 2.0882 us 2.1050 us]
                        change: [-5.7071% -3.8407% -1.9520%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 4 outliers among 100 measurements (4.00%)
  4 (4.00%) high severe

ajson multi query       time:   [2.6245 us 2.6365 us 2.6492 us]
                        change: [-9.4889% -8.3135% -7.1778%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 9 outliers among 100 measurements (9.00%)
  1 (1.00%) low mild
  5 (5.00%) high mild
  3 (3.00%) high severe

gjson multi query       time:   [858.23 ns 861.61 ns 865.37 ns]
                        change: [-10.479% -8.6397% -6.8407%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 5 outliers among 100 measurements (5.00%)
  3 (3.00%) high mild
  2 (2.00%) high severe

serde derive            time:   [9.1830 us 9.2368 us 9.2964 us]
                        change: [-10.407% -8.5730% -6.7286%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 5 outliers among 100 measurements (5.00%)
  4 (4.00%) high mild
  1 (1.00%) high severe

serde derive multi query
                        time:   [1.9318 us 1.9421 us 1.9542 us]
                        change: [-5.3005% -4.0650% -2.8234%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 3 outliers among 100 measurements (3.00%)
  3 (3.00%) high mild

nom json bench          time:   [1.2689 us 1.2735 us 1.2783 us]
                        change: [-4.7747% -3.7796% -2.8171%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 5 outliers among 100 measurements (5.00%)
  2 (2.00%) high mild
  3 (3.00%) high severe

Fork: gjson-bench

It seems that ajson is a little bit slower than gsjon.rs :)

Support for serde::Deserialize

Does ajson have serde Deserialize compatible API, so that I can fill in every field in my struct automatically?