1 unstable release
0.1.0 | Mar 13, 2021 |
---|
#12 in #json-text
Used in jsondata
9KB
176 lines
Why yet another JSON package in Rust ?
This crate makes several trade-offs that are tuned for big-data and document database.
- Support for 128-bit signed integers.
- Deferred conversion for JSON numbers.
- Serialization from Rust native type to JSON text.
- De-serialization from JSON text to Rust native type.
- CRUD operation on JSON documents, using JSON Pointer.
- Sorted keys in property object.
- Streaming JSON parser.
- Support JSON5 standard.
- Common arithmetic and logic operations.
- Sortable JSON.
Useful links
- API Documentation
- JSON Pointer.
- JSON5.
- Rust internal discussion on f64 -> integer.
- Json sort order.
- Json operations.
- Release notes.
Deferred conversion for numbers
Converting JSON numbers to Rust native type is not always desired. Especially in the context of big-data where data is stored in JSON format and we need to lookup, only, specific fields within the document.
This implementation provides deferred conversion for JSON numbers that leads to a performance improvement of upto 30%.
CRUD operations on JSON document
Using Json Pointer it is possible to identify a specific field nested within a JSON document. For Example, with below document:
{
"age": 26,
"eyeColor": "green",
"name": "Leon Robertson",
"gender": "male",
"company": "AEORA",
"phone": "+1 (835) 447-2960",
"tags": [ "officia", "reprehenderit", "magna" ],
"friends": [
{
"id": 0,
"name": "Glenda Chan"
}
]
}
- /age shall point to value
26
. - /tags shall point to value
[ "officia", "reprehenderit", "magna" ]
. - /tags/0 shall point to value
"officia"
. - /friends shall point to value
[{"id": 0, "name": "Glenda Chan"}]
. - /friends/name shall point to value
"Glenda Chan"
.
List of operations
- Get a field nested within a JSON document using JSON Pointer.
- Set a field nested within a JSON document.
- Delete a field nested within a JSON document.
- Append string or array field withing a JSON document.
JSON5
- Object keys may be an ECMAScript 5.1 IdentifierName.
- Objects may have a single trailing comma.
- Arrays may have a single trailing comma.
- Strings may be single quoted.
- Strings may span multiple lines by escaping new line characters.
- Strings may include character escapes.
- Numbers may be hexadecimal.
- Numbers may have a leading or trailing decimal point.
- Numbers may be IEEE 754 positive infinity, negative infinity, and NaN.
- Numbers may begin with an explicit plus sign.
- Single and multi-line comments are allowed.
- Additional white space characters are allowed.
Sortable JSON
- Null type shall sort before all other types.
- Boolean type shall sort after Null type.
- Number type shall sort after Boolean type.
- f64 values that are <= -2^127 will sort before all i128 integers.
- f64 values that are >= 2^127-1 will sort after all i128 integers.
- NaN, Not a Number, values shall sort after all i128 integers
- -Infinity shall sort before all numbers.
- +Infinity shall sort after all numbers.
- NaN shall sort after +Infinity.
- String type shall sort after Number type.
- Array type shall sort after String type.
- Object type shall sort after Array type.
- All (key,value) pairs within the object shall be presorted based on the key.
- When comparing two objects, comparison shall start from first key and proceed to the last key.
- If two keys are equal at a given position within the objects, then its corresponding values shall be compared.
- When one object is a subset of another object, as in, if one object contain all the (key,value) properties that the other object has then it shall sort before the other object.
Useful links
- A detailed description of JSON sort order.
- Rust-lang issue#46298 and issue#10184, discussing saturating cast of f64 -> integer.
- Rust internal discussion on f64 -> integer.
- Unicode collation TR10.
- ICU collation.
- Floating point Total ordering
- Total ordering for floating point in stackoverflow.
- Total ordering thread in http://users.rust-lang.org.
- A good blog on floating point, to get started.
Operations on JSON documents
- Arithmetic operations, ADD, SUB, MUL, DIV, REM, NEG.
- Bitwise operations, SHL, SHR, BITAND, BITOR, BITXOR.
- Logical operations, NOT, AND, OR.
- Index operations.
- Range operations.
Detailed description can be found here.
Contribution
- Simple workflow. Fork - Modify - Pull request.
- Before creating a PR,
- Run
make build
to confirm all versions of build is passing with 0 warnings and 0 errors. - Run
check.sh
with 0 warnings, 0 errors and all testcases passing. - Run
perf.sh
with 0 warnings, 0 errors and all testcases passing. - [Install][spellcheck] and run
cargo spellcheck
to remove common spelling mistakes.
- Run
- [Developer certificate of origin][dco] is preferred.
Dependencies
~2MB
~45K SLoC