jsonb/
lib.rs

1// Copyright 2023 Datafuse Labs.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! `jsonb` is a binary format `JSON` representation inspired by [PostgreSQL](https://www.postgresql.org/docs/current/datatype-json.html) and [CockroachDB](https://www.cockroachlabs.com/docs/stable/jsonb). It provides a fast, lightweight and easy-to-use API for working with `JSON` data.
16//!
17//! ## Features
18//!
19//! - Good compatibility: `jsonb` fully supports the `JSON` standard and can be used to store complex data structures.
20//! - Fast performance: `jsonb` is designed for high performance, allowing you to work with large `JSON` data sets with ease.
21//! - Easy to use: `jsonb` provides a number of built-in functions to support various operations, and also supports the `JSONPath` syntax for selecting and extracting subset elements.
22//! - Safe and secure: `jsonb` is written in Rust, which provides memory and thread safety guarantees, making it a safe choice for handling sensitive data.
23//!
24//! ## Encoding format
25//!
26//! The `jsonb` encoding format is a tree-like structure. Each node contains a container header, a number of JEntry headers, and nested encoding values.
27//!
28//! - 32-bit container header. 3 bits identify the type of value, including `scalar`, `object` and `array`, and 29 bits identify the number of JEntries in the `array` or `object`. The root node of the `jsonb` value is always a container header.
29//!   - `scalar` container header: `0x20000000`
30//!   - `object` container header: `0x40000000`
31//!   - `array` container header: `0x80000000`
32//! - 32-bit JEntry header. 1 bit identifies whether the JEntry stores a length or an offset, 3 bits identify the type of value, including `null`, `string`, `number`, `false`, `true` and `container`, and the remaining 28 bits identify the length or offset of the encoding value.
33//!   - `null` JEntry header: `0x00000000`
34//!   - `string` JEntry header: `0x10000000`
35//!   - `number` JEntry header: `0x20000000`
36//!   - `false` JEntry header: `0x30000000`
37//!   - `true` JEntry header: `0x40000000`
38//!   - `container` JEntry header `0x50000000`
39//! - Encoding value. Different types of JEntry header have different encoding values.
40//!   - `null`, `true`, `false`: no encoding value, identified by the JEntry header.
41//!   - `string`: a normal UTF-8 string.
42//!   - `number`: an encoded number to represent uint64s, int64s and float64s.
43//!   - `container`: a nested `json` value with a recursive structure.
44//!
45//! #### An encoding example
46//!
47//! ```text
48//! // JSON value
49//! [false, 10, {"k":"v"}]
50//!
51//! // JSONB encoding
52//! 0x80000003    array container header (3 JEntries)
53//! 0x30000000    false JEntry header (no encoding value)
54//! 0x20000002    number JEntry header (encoding value length 2)
55//! 0x5000000e    container JEntry header (encoding value length 14)
56//! 0x500a        number encoding value (10)
57//! 0x40000001    object container header (1 JEntry)
58//! 0x10000001    string key JEntry header (encoding value length 1)
59//! 0x10000001    string value JEntry header (encoding value length 1)
60//! 0x6b          string encoding value ("k")
61//! 0x76          string encoding value ("v")
62//! ```
63
64#![allow(clippy::uninlined_format_args)]
65
66mod constants;
67pub mod core;
68mod error;
69mod from;
70mod functions;
71pub mod jsonpath;
72pub mod keypath;
73mod number;
74mod owned;
75mod parser;
76mod raw;
77mod util;
78mod value;
79
80pub use error::Error;
81#[allow(unused_imports)]
82pub use from::*;
83pub use number::Number;
84pub use owned::to_owned_jsonb;
85pub use owned::OwnedJsonb;
86pub use parser::from_slice;
87pub use parser::parse_value;
88pub use raw::from_raw_jsonb;
89pub use raw::RawJsonb;
90pub use value::*;
jsonb/lib.rs

jsonb/
lib.rs
