Expand description
Encoding and decoding support for YASON in Rust.
§Optional features
§serde
When this optional dependency is enabled, YasonBuf implements the serde::Serialize and
serde::Deserialize traits.
§Yason binary format
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§Usage
§Scalar
To encode a Scalar, use 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
To encode an Object, use ObjectBuilder or 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);To encode an Array, use ArrayBuilder or 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);§Nested Object / Array
To encode an Object or Array that contains nested Object or 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);Structs§
- An array in yason binary format.
- Builder for encoding an array.
- An iterator over the array’s elements.
- Builder for encoding an array.
- Invalid data type.
- An iterator over the object’s keys.
- High precision decimal.
- An object in yason binary format.
- Builder for encoding an object.
- An iterator over the object’s entries.
- Builder for encoding an object.
- This type represents a path expression.
- This type represents error that can arise during parsing path expression.
- Builder for encoding a scalar value.
- An iterator over the object’s values.
- A slice of
Yasonvalue. This can be created from aYasonBufor any type the contains valid bytes in yason binary format. - An owned
Yasonvalue, backed by a buffer of bytes in yason binary format. This can be created from a Vec.
Enums§
- Possible errors that can arise during building.
- Possible yason types.
- Possible errors that can arise during formatting.
- Possible errors that can arise during dealing with number.
- This type represents result returned by a path expression.
- Possible yason value corresponding to the data type.
- Possible errors that can arise during accessing.