Documents
The example parses the people document in your selected format. It then reads Ada's age through the document nodes. Typed reads give you these values without serializing the document.
Example
Read Ada's age
people_text holds this document:
{
"#_ada": {
"name": "Ada",
"role": "engineer",
"age": 36
},
"#_bob": {
"name": "Bob",
"role": "engineer",
"age": 41,
"mentor": {
"#link": "#_ada"
}
},
"#_cy": {
"name": "Cy",
"role": "designer",
"age": 29
},
"#_tx": {
"author": "smoke",
"reason": "seed"
}
}
let people = stardust::parse(people_text, Format::JSON)?;
let ada = people.member(people.root()?, "#_ada")?;
let age = people.member(ada, "age")?;
let result = people.i64(age)?;36
Numbers
A document number is an i64 integer or a finite f64 value. The number type defines both.
- An integer read requires an integer node. A floating-point node can cause the read to fail.
- Choose the typed read that matches the node that you read.
Operations
| Operation | Returns | Summary |
|---|---|---|
| parse | document | parse(text, format) returns an owned document. |
| Document::root | node | document.root() returns the root node ID. |
| Document::count | count | document.count() returns the number of nodes. |
| Document::read | node_view | document.read(id) returns a node view: kind, boolean, parent, position, first_child, next_sibling, key and text. |
| Document::read_many | node_views | document.read_many(start, capacity) reads consecutive node views. |
| Document::member | node | document.member(id, key) returns the first matching object member ID. |
| Document::children | node_views | document.children(id) iterates the node views of a node's children in order. |
| Document::members | node_views | document.members(id) iterates the members of an object node in order, each with its key. |
| Document::i64 | integer | Read an exact signed integer. |
| Document::f64 | real | Read a finite floating-point number. |
| Document::close | none | Release the document handle. |
parse
pub fn parse(text: impl AsRef<[u8]>, format: Format) -> Result<Document>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
text | impl AsRef<[u8]> | Value | Required | Encoded input bytes in the selected format. TRON is binary. |
format | Format | Value | Required | The codec to use for this operation. |
Errors
| Status | When |
|---|---|
Status::INVALID_JSON | JSON text is malformed |
Status::INVALID_ARGUMENT | the text is malformed, the format is unknown or a number is outside i64 or finite f64 |
Status::OUT_OF_MEMORY | native memory is exhausted |
Examples
Parse the shared DUST expression fixture
expression holds these bytes:
// One expression built once and evaluated against several inputs. The
// evaluate examples load this file, build `expression`, evaluate it with each
// of `inputs` in order and compare each result with `expected`.
expression [+ ?x 1]
inputs [{x 1} {x 41}]
expected [2 42]let result = stardust::parse(expression, Format::DUST)?;{
"$comment": "One expression built once and evaluated against several inputs. The\nevaluate examples load this file, build `expression`, evaluate it with each\nof `inputs` in order and compare each result with `expected`.",
"expression": [
"+",
"?x",
1
],
"inputs": [
{
"x": 1
},
{
"x": 41
}
],
"expected": [
2,
42
]
}Report a malformed byte at offset zero
malformed holds these bytes:
]
let result = stardust::parse(malformed, Format::DUST).err();{
"code": "invalid_dust",
"message": "Invalid_Syntax at offset 0",
"path": null,
"field": null,
"entity": null,
"offset": 0,
"status": "invalid_argument"
}Report malformed DUST
malformed holds these bytes:
[
let result = stardust::parse(malformed, Format::DUST).err();{
"code": "invalid_dust",
"message": "Unexpected_End at offset 2",
"path": null,
"field": null,
"entity": null,
"offset": 2,
"status": "invalid_argument"
}C exports: stardust_parse, stardust_document_error
Document::root
pub fn root(&self) -> Result<NodeId>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
Examples
document/root
input_text holds this document:
{
"x": 41
}
let input = stardust::parse(input_text, Format::JSON)?;
let result = input.root()? as i64;0
C exports: stardust_document_root
Document::count
pub fn count(&self) -> Result<i64>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
Examples
document/count
input_text holds this document:
{
"x": 41
}
let input = stardust::parse(input_text, Format::JSON)?;
let result = input.count()? as i64;2
C exports: stardust_document_count
Document::read
pub fn read(&self, id: NodeId) -> Result<NodeView<'_>>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
id | NodeId | Value | Required | A node ID within the receiver document. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
| Status | When |
|---|---|
Status::INVALID_ARGUMENT | id is not a node of the document |
Notes
Text contains string values. Read numbers with i64 or f64.
Examples
document/read
input_text holds this document:
{
"x": 41
}
let input = stardust::parse(input_text, Format::JSON)?;
let result = input.read(input.root()?)?;{
"kind": "object",
"boolean": false,
"parent": null,
"position": 0,
"first_child": 1,
"next_sibling": null,
"key": "",
"text": ""
}C exports: stardust_document_read_many
Document::read_many
pub fn read_many(&self, start: NodeId, capacity: i64) -> Result<Vec<NodeView<'_>>>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
start | NodeId | Value | Required | The first node ID of the consecutive read. |
capacity | i64 | Value | Required | The maximum number of node views to read. For output slices, the call uses the caller's slice length. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
| Status | When |
|---|---|
Status::INVALID_ARGUMENT | start is past the last node or capacity is negative |
Examples
document/read_many
input_text holds this document:
{
"x": 41
}
let input = stardust::parse(input_text, Format::JSON)?;
let views = input.read_many(input.root()?, 1)?;
let result = views.into_iter().next().ok_or("missing node view")?;{
"kind": "object",
"boolean": false,
"parent": null,
"position": 0,
"first_child": 1,
"next_sibling": null,
"key": "",
"text": ""
}C exports: stardust_document_read_many
Document::member
pub fn member(&self, id: NodeId, key: &str) -> Result<NodeId>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
id | NodeId | Value | Required | A node ID within the receiver document. |
key | &str | Value | Required | The object member name to find. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
| Status | When |
|---|---|
Status::NOT_FOUND | the object has no member with the key |
Status::INVALID_ARGUMENT | id is not an object node of the document |
Examples
document/member
input_text holds this document:
{
"x": 41
}
let input = stardust::parse(input_text, Format::JSON)?;
let result = input.member(input.root()?, "x")? as i64;1
C exports: stardust_document_member
Document::children
pub fn children(&self, id: NodeId) -> Children<'_>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
id | NodeId | Value | Required | A node ID within the receiver document. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
| Status | When |
|---|---|
Status::INVALID_ARGUMENT | id is not a node of the document |
Notes
Keep the document open during iteration. A scalar has no children. A read failure is reported once and ends iteration.
Examples
document/children
seed_text holds this document:
{
"#_ada": {
"name": "Ada",
"role": "engineer",
"age": 36
},
"#_bob": {
"name": "Bob",
"role": "engineer",
"age": 41,
"mentor": {
"#link": "#_ada"
}
},
"#_cy": {
"name": "Cy",
"role": "designer",
"age": 29
},
"#_tx": {
"author": "smoke",
"reason": "seed"
}
}
let seed = stardust::parse(seed_text, Format::JSON)?;
let mut result = 0i64;
let mut children = seed.children(seed.root()?);
while let Some(child) = children.next() {
child?;
result += 1;
}4
C exports: stardust_document_read_many
Document::members
pub fn members(&self, id: NodeId) -> Members<'_>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
id | NodeId | Value | Required | A node ID within the receiver document. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
| Status | When |
|---|---|
Status::INVALID_ARGUMENT | id is not an object node of the document |
Notes
Duplicate keys appear in document order. Keep the document open during iteration. A read failure is reported once and ends iteration.
Examples
document/members
seed_text holds this document:
{
"#_ada": {
"name": "Ada",
"role": "engineer",
"age": 36
},
"#_bob": {
"name": "Bob",
"role": "engineer",
"age": 41,
"mentor": {
"#link": "#_ada"
}
},
"#_cy": {
"name": "Cy",
"role": "designer",
"age": 29
},
"#_tx": {
"author": "smoke",
"reason": "seed"
}
}
let seed = stardust::parse(seed_text, Format::JSON)?;
let (key, _view) = seed.members(seed.root()?).next().ok_or("no members")??;
let result = key.as_bytes().to_vec();{
"text": "#_ada"
}C exports: stardust_document_read_many
Document::i64
pub fn i64(&self, id: NodeId) -> Result<i64>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
id | NodeId | Value | Required | A node ID within the receiver document. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
| Status | When |
|---|---|
Status::INVALID_ARGUMENT | the node is not an integer number |
Examples
document/i64
input_text holds this document:
{
"x": 41
}
let input = stardust::parse(input_text, Format::JSON)?;
let x = input.member(input.root()?, "x")?;
let result = input.i64(x)?;41
C exports: stardust_document_i64
Document::f64
pub fn f64(&self, id: NodeId) -> Result<f64>Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &Self | Borrowed for the call | Required | The document owner for this operation. Keep it alive during the call. |
id | NodeId | Value | Required | A node ID within the receiver document. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
| Status | When |
|---|---|
Status::INVALID_ARGUMENT | the node is not a number or its value overflows f64 |
Notes
Integer conversion can round values outside the exact f64 integer range.
Examples
document/f64
float_text holds this document:
1.0
let float = stardust::parse(float_text, Format::JSON)?;
let result = float.f64(float.root()?)?;1.0
C exports: stardust_document_f64
Document::close
pub fn close(self)Consumes the receiver handle.
Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | Self | Consumed owner | Required | The document owner to release. Do not use it after this call. |
Errors
Close consumes this owner. Rust ownership prevents later access. Thus, the safe API does not report closed for this receiver.
Examples
document/close
expression_text holds this document:
[
"+",
"?x",
1
]
let expression = stardust::parse(expression_text, Format::JSON)?;
let result = expression.serialize(Format::JSON, 0)?;
expression.close();{
"text": "[\"+\",\"?x\",1]"
}C exports: stardust_document_release
node_view
This record contains the result of read and read_many. The key and text fields are owned strings and remain valid after the document closes.
| Field | Type | Unit | Absent | Meaning |
|---|---|---|---|---|
kind | Kind | None | — | — |
boolean | bool | None | — | True only for true. |
parent | Option<NodeId> | None | None | — |
position | u32 | Count | — | Index within the parent container. |
first_child | Option<NodeId> | None | None | — |
next_sibling | Option<NodeId> | None | None | — |
key | &'a str | None | — | Member key of an object member, else empty. |
text | &'a str | None | — | Value of a string, else empty. It can contain NUL. |
node_input
This record supplies a node for add and add_many. The number field holds a typed i64 or f64 value. Go uses I64/F64, Rust and Odin use Number, Clojure uses long or double, and Python uses int or float. This value sets the ABI number kind and the integer or real field.
| Field | Type | Absent | Meaning |
|---|---|---|---|
parent | Option<NodeId> | None | — |
kind | Kind | — | — |
boolean | bool | — | Value of a boolean node. |
number | Number | — | Value of a number node. |
key | &'a str | — | Member key when the parent is an object. |
text | &'a str | — | Value of a string node. |