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.
Licensing
Up till version 0.4.0, jsondata
is released under MIT license.
Subsequent releases are under AGPL-3.0 license, and going to be
the default license for all future releases. For re-licensing this
source, you can either contact the author(s) directly or post your
request here #13.
Compatibility policy
jsondata
shall officially support the latest version of rust stable
compiler and nightly builds.
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 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.