Building documents
These operations construct a document one node at a time. For most operations, parse a document in your selected format. Use these operations only when you cannot parse the document from text.
- Create a builder.
- Add the nodes in preorder.
- Seal the builder to create an owned document.
Operations
| Operation | Returns | Summary |
|---|---|---|
| builder | builder | Create an owned document builder. |
| Builder::add | node | builder.add(node) appends one node and returns its preorder ID. |
| Builder::add_many | none | builder.add_many(nodes) appends nodes in order in one native call. |
| Builder::seal | document | builder.seal() transfers the constructed document into an independent owned document. |
| Builder::close | none | Release the builder handle. |
builder
pub fn builder() -> Result<Builder>Errors
| Status | When |
|---|---|
Status::OUT_OF_MEMORY | native memory is exhausted |
Notes
Add nodes in depth-first preorder. An append failure makes the builder unusable.
Examples
builder
let mut builder = stardust::builder()?;
let object = builder.add(NodeInput { kind: Kind::OBJECT, ..Default::default() })?;
builder.add(NodeInput {
parent: Some(object), kind: Kind::NUMBER, key: "x", number: Number::I64(41),
..Default::default()
})?;
let result = builder.seal()?;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 1C 78 | txt "x" |
| 06 | 02 29000000000000 00 | i64 41 |
| 0F | 0F 0A 04000000 0600 0000 | map leaf, size 10: @4 → @6 |
| 19 | 0F000000 00000000 | root → @F; previous: none |
C exports: stardust_document_builder_create
Builder::add
pub fn add(&mut self, node: NodeInput<'_>) -> Result<NodeId>Requires exclusive use of the receiver handle.
Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &mut Self | Borrowed for the call | Required | The builder owner for this operation. Keep it alive during the call. |
node | NodeInput<'_> | Value | Required | The next node's kind, parent and typed value. |
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 breaks the preorder rules or has an invalid kind or number |
Status::OUT_OF_MEMORY | native memory is exhausted |
Notes
The root has no parent. Each later parent must be an open container or one of its ancestors.
Examples
builder/add
let mut builder = stardust::builder()?;
let object = builder.add(NodeInput { kind: Kind::OBJECT, ..Default::default() })?;
builder.add(NodeInput {
parent: Some(object), kind: Kind::NUMBER, key: "x", number: Number::I64(41),
..Default::default()
})?;
let result = builder.seal()?;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 1C 78 | txt "x" |
| 06 | 02 29000000000000 00 | i64 41 |
| 0F | 0F 0A 04000000 0600 0000 | map leaf, size 10: @4 → @6 |
| 19 | 0F000000 00000000 | root → @F; previous: none |
Add a typed integer node
let input = stardust::NodeInput { kind: Kind::NUMBER, number: Number::I64(41), ..Default::default() };
let mut builder = stardust::builder()?;
builder.add(input)?;
let result = input;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 3C 6B6579 | txt "key" |
| 08 | 0C | txt "" |
| 09 | 0F 0A 04000000 0800 0000 | map leaf, size 10: @4 → @8 |
| 13 | 4C 6B696E64 | txt "kind" |
| 18 | 6C 6E756D626572 | txt "number" |
| 1F | 0F 0A 13000000 1800 0000 | map leaf, size 10: @13 → @18 |
| 29 | 6C 6E756D626572 | txt "number" |
| 30 | 02 29000000000000 00 | i64 41 |
| 39 | 0F 0A 29000000 3000 0000 | map leaf, size 10: @29 → @30 |
| 43 | 6C 706172656E74 | txt "parent" |
| 4A | 00 | nil |
| 4B | 0F 0A 43000000 4A00 0000 | map leaf, size 10: @43 → @4A |
| 55 | 4C 74657874 | txt "text" |
| 5A | 0C | txt "" |
| 5B | 0F 0A 55000000 5A00 0000 | map leaf, size 10: @55 → @5A |
| 65 | 7C 626F6F6C65616E | txt "boolean" |
| 6D | 01 | bit false |
| 6E | 0F 0A 65000000 6D00 0000 | map leaf, size 10: @65 → @6D |
| 78 | 07 1E A1190000 0900 0000 1F000000 3900 0000 4B000000 5B00 0000 6E000000 | map branch, size 30, depth 0 (root), slots 0, 5, 7, 8, 11, 12: @9 → @1F → @39 → @4B → @5B → @6E |
| 96 | 78000000 00000000 | root → @78; previous: none |
C exports: stardust_document_builder_add_many, stardust_document_builder_error
Builder::add_many
pub fn add_many(&mut self, nodes: &[NodeInput<'_>]) -> Result<()>Requires exclusive use of the receiver handle.
Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | &mut Self | Borrowed for the call | Required | The builder owner for this operation. Keep it alive during the call. |
nodes | &[NodeInput<'_>] | Value | Required | Nodes in depth-first preorder to append together. |
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 | a node breaks the preorder rules or has an invalid kind or number |
Status::OUT_OF_MEMORY | native memory is exhausted |
Examples
builder/add_many
let mut builder = stardust::builder()?;
builder.add_many(&[
NodeInput { kind: Kind::OBJECT, ..Default::default() },
NodeInput { parent: Some(0), kind: Kind::NUMBER, key: "x", number: Number::I64(41), ..Default::default() },
])?;
let result = builder.seal()?;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 1C 78 | txt "x" |
| 06 | 02 29000000000000 00 | i64 41 |
| 0F | 0F 0A 04000000 0600 0000 | map leaf, size 10: @4 → @6 |
| 19 | 0F000000 00000000 | root → @F; previous: none |
C exports: stardust_document_builder_add_many, stardust_document_builder_error
Builder::seal
pub fn seal(self) -> Result<Document>Requires exclusive use of the receiver handle.
Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | Self | Borrowed for the call | Required | The builder 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.
| Status | When |
|---|---|
Status::INVALID_ARGUMENT | the builder has no root or a container is still open |
Status::OUT_OF_MEMORY | native memory is exhausted |
Notes
The builder accepts no more nodes after sealing.
Examples
builder/seal
let mut builder = stardust::builder()?;
let object = builder.add(NodeInput { kind: Kind::OBJECT, ..Default::default() })?;
builder.add(NodeInput {
parent: Some(object), kind: Kind::NUMBER, key: "x", number: Number::I64(41),
..Default::default()
})?;
let result = builder.seal()?;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 1C 78 | txt "x" |
| 06 | 02 29000000000000 00 | i64 41 |
| 0F | 0F 0A 04000000 0600 0000 | map leaf, size 10: @4 → @6 |
| 19 | 0F000000 00000000 | root → @F; previous: none |
C exports: stardust_document_builder_seal, stardust_document_builder_error
Builder::close
pub fn close(self)Consumes the receiver handle.
Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
self | Self | Consumed owner | Required | The builder 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
builder/close
input_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 1C 78 | txt "x" |
| 06 | 02 29000000000000 00 | i64 41 |
| 0F | 0F 0A 04000000 0600 0000 | map leaf, size 10: @4 → @6 |
| 19 | 0F000000 00000000 | root → @F; previous: none |
let builder = stardust::builder()?;
builder.close();
let result = stardust::parse(input_text, Format::TRON)?;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 1C 78 | txt "x" |
| 06 | 02 29000000000000 00 | i64 41 |
| 0F | 0F 0A 04000000 0600 0000 | map leaf, size 10: @4 → @6 |
| 19 | 0F000000 00000000 | root → @F; previous: none |
C exports: stardust_document_builder_release