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.

  1. Create a builder.
  2. Add the nodes in preorder.
  3. Seal the builder to create an owned document.

Operations

OperationReturnsSummary
builderbuilderCreate an owned document builder.
Builder::addnodebuilder.add(node) appends one node and returns its preorder ID.
Builder::add_manynonebuilder.add_many(nodes) appends nodes in order in one native call.
Builder::sealdocumentbuilder.seal() transfers the constructed document into an independent owned document.
Builder::closenoneRelease the builder handle.

builder

rust35 B
pub fn builder() -> Result<Builder>

Errors

StatusWhen
Status::OUT_OF_MEMORYnative memory is exhausted

Notes

Add nodes in depth-first preorder. An append failure makes the builder unusable.

Examples

builder

rust287 B
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()?;
Result / 16 B
{:value {:x 41}}

C exports: stardust_document_builder_create

Builder::add

rust60 B
pub fn add(&mut self, node: NodeInput<'_>) -> Result<NodeId>

Requires exclusive use of the receiver handle.

Parameters

ParameterTypeOwnershipDefaultMeaning
self&mut SelfBorrowed for the callRequiredThe builder owner for this operation. Keep it alive during the call.
nodeNodeInput<'_>ValueRequiredThe 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.

StatusWhen
Status::INVALID_ARGUMENTthe node breaks the preorder rules or has an invalid kind or number
Status::OUT_OF_MEMORYnative 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

rust287 B
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()?;
Result / 16 B
{:value {:x 41}}

Add a typed integer node

rust183 B
let input = stardust::NodeInput { kind: Kind::NUMBER, number: Number::I64(41), ..Default::default() };
let mut builder = stardust::builder()?;
builder.add(input)?;
let result = input;
Result / 137 B
{:value {:parent  nil
         :kind    "number"
         :boolean false
         :number  41
         :key     ""
         :text    ""}}

C exports: stardust_document_builder_add_many, stardust_document_builder_error

Builder::add_many

rust65 B
pub fn add_many(&mut self, nodes: &[NodeInput<'_>]) -> Result<()>

Requires exclusive use of the receiver handle.

Parameters

ParameterTypeOwnershipDefaultMeaning
self&mut SelfBorrowed for the callRequiredThe builder owner for this operation. Keep it alive during the call.
nodes&[NodeInput<'_>]ValueRequiredNodes 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.

StatusWhen
Status::INVALID_ARGUMENTa node breaks the preorder rules or has an invalid kind or number
Status::OUT_OF_MEMORYnative memory is exhausted

Examples

builder/add_many

rust266 B
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()?;
Result / 16 B
{:value {:x 41}}

C exports: stardust_document_builder_add_many, stardust_document_builder_error

Builder::seal

rust37 B
pub fn seal(self) -> Result<Document>

Requires exclusive use of the receiver handle.

Parameters

ParameterTypeOwnershipDefaultMeaning
selfSelfBorrowed for the callRequiredThe 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.

StatusWhen
Status::INVALID_ARGUMENTthe builder has no root or a container is still open
Status::OUT_OF_MEMORYnative memory is exhausted

Notes

The builder accepts no more nodes after sealing.

Examples

builder/seal

rust287 B
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()?;
Result / 16 B
{:value {:x 41}}

C exports: stardust_document_builder_seal, stardust_document_builder_error

Builder::close

rust18 B
pub fn close(self)

Consumes the receiver handle.

Parameters

ParameterTypeOwnershipDefaultMeaning
selfSelfConsumed ownerRequiredThe 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:

edn7 B
{:x 41}
rust108 B
let builder = stardust::builder()?;
builder.close();
let result = stardust::parse(input_text, Format::EDN)?;
Result / 16 B
{:value {:x 41}}

C exports: stardust_document_builder_release