YASON

在Rust中对YASON进行编码和解码的支持

Rust版本

此版本的yason需要Rust 1.57或更高版本。

许可

本项目采用Apache-2.0许可协议（LICENSE 或 http://www.apache.org/licenses/LICENSE-2.0）。

贡献

除非您明确声明，否则您提交的任何有意包含在yason中的贡献，均应按Apache-2.0许可，不得附加任何额外条款或条件。

lib.rs:

在Rust中对YASON进行编码和解码的支持。

可选特性

serde

当此可选依赖项启用时，YasonBuf实现了serde::Serialize和serde::Deserialize特性。

Yason二进制格式

yason ::= type value

type ::=
    object-type |
    array-type |
    scalar-type |

object-type ::= 1
array-type ::= 2
scalar-type ::=
    3 |     // string
    4 |     // number
    5 |     // bool
    6 |     // null
    7 |     // 8-bit signed integer
    8 |     // 16-bit signed integer
    9 |     // 32-bit signed integer
    10 |    // 64-bit signed integer
    11 |    // 8-bit unsigned integer
    12 |    // 16-bit unsigned integer
    13 |    // 32-bit unsigned integer
    14 |    // 64-bit unsigned integer
    15 |    // 32-bit floating point
    16 |    // 64-bit floating point
    17 |    // binary data
    18 |    // timestamp
    19 |    // date
    20 |    // short date
    21 |    // time
    22 |    // interval year-month
    23 |    // interval day-time

value ::=
    object |
    array |
    scalar |

scalar ::=
    string |            // string
    number |            // number
    bool |              // bool
    int8 |              // 8-bit signed integer
    int16 |             // 16-bit signed integer
    int32 |             // 32-bit signed integer
    int64 |             // 64-bit signed integer
    uint8 |             // 8-bit unsigned integer
    uint16 |            // 16-bit unsigned integer
    uint32 |            // 32-bit unsigned integer
    uint64 |            // 64-bit unsigned integer
    float32 |           // 32-bit floating point
    float64 |           // 64-bit floating point
    binary |            // binary data
    timestamp |         // timestamp
    date |              // date
    short-date |        // short date
    time |              // time
    interval-ym |       // interval year-month
    interval-dt         // interval day-time

string ::= data-length uint8*
number ::= uint8 uint8* // first uint8 indicates size of number
bool ::= 0 | 1
binary ::= data-length uint8*
timestamp ::= int64
date ::= int64
short-date ::= int32
time ::= int64
interval-ym ::= int32
interval-dt ::= int64

data-length ::= uint8*  // If the high bit of a byte is 1,
                        // the length field is continued in the next byte,
                        // otherwise it is the last byte of the length field.
                        // So we need 1 byte to represent lengths up to 127,
                        // 2 bytes to represent lengths up to 16383, and so on...
                        // Use 4 bytes at most.

// key-offset is ordered by key length and lexicographical order
object ::= size element-count key-offset* key-value*

array ::= size element-count value-entry* outlined-value*

size ::= int32  // size indicates total size of object or array
element-count ::= uint16 // number of members in object or array

key-offset ::= uint32
key-value ::= key type value
key ::= key-length uint8*
key-length ::= uint16    // key length must be less than 64KB

value-entry ::= type offset-or-inlined-value

// This field holds either the offset to where the value is stored,
// or the value itself if it is small enough to be inlined (that is 4 bytes).
offset-or-inlined-value ::= uint32

outlined-value ::= type value

用法

标量

要编码一个Scalar，使用Scalar

use yason::Scalar;

let yason = Scalar::string("string").unwrap();

let mut bytes = Vec::with_capacity(16);
let yason = Scalar::string_with_vec("string", &mut bytes).unwrap();

Object / Array

要编码一个Object，使用ObjectBuilder或ObjectRefBuilder

use yason::{DataType, ObjectBuilder, ObjectRefBuilder};

let mut builder = ObjectBuilder::try_new(2, false).unwrap();
builder.push_string("key1", "value").unwrap();
builder.push_bool("key2", true);
let yason = builder.finish().unwrap();
assert_eq!(yason.data_type().unwrap(), DataType::Object);

let mut bytes = Vec::with_capacity(16);
let mut builder = ObjectRefBuilder::try_new(&mut bytes, 1, false).unwrap();
builder.push_string("key", "value").unwrap();
let yason = builder.finish().unwrap();
assert_eq!(yason.data_type().unwrap(), DataType::Object);

要编码一个Array，使用ArrayBuilder或ArrayRefBuilder

use yason::{DataType, ArrayBuilder, ArrayRefBuilder};

let mut builder = ArrayBuilder::try_new(2).unwrap();
builder.push_string("string").unwrap();
builder.push_bool(true);
let yason = builder.finish().unwrap();
assert_eq!(yason.data_type().unwrap(), DataType::Array);

let mut bytes = Vec::with_capacity(16);
let mut builder = ArrayRefBuilder::try_new(&mut bytes, 1).unwrap();
builder.push_string("string").unwrap();
let yason = builder.finish().unwrap();
assert_eq!(yason.data_type().unwrap(), DataType::Array);

嵌套的Object / Array

要编码一个包含嵌套Object或Array的Object或Array

use yason::{DataType, ObjectBuilder};
let mut obj_builder = ObjectBuilder::try_new(1, true).unwrap();
let mut array_builder = obj_builder.push_array("key", 1).unwrap();
array_builder.push_bool(true).unwrap();

array_builder.finish().unwrap();
let yason = obj_builder.finish().unwrap();
assert_eq!(yason.data_type().unwrap(), DataType::Object);