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
stardust_document_builder_create	Status. builder through output	Create an owned document builder.
add	Unavailable	builder.add(node) appends one node and returns its preorder ID.
stardust_document_builder_add_many	Status. none through output	builder.add_many(nodes) appends nodes in order in one native call.
stardust_document_builder_seal	Status. document through output	builder.seal() transfers the constructed document into an independent owned document.
stardust_document_builder_release	`void`	Release the builder handle.

stardust_document_builder_create

78 B

uint32_t stardust_document_builder_create(stardust_document_builder **output);

Parameters

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_document_builder **`	Owned output	Required	Receives a library-owned handle. Release it after use.

Errors

Status	When
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Notes

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

Examples

builder

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

TRON

33 B

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

Call stardust_document_builder_add_many with one node.

Examples

Add a typed integer node

452 B

stardust_node_input input = {.parent=STARDUST_DOCUMENT_NO_NODE, .kind=STARDUST_NUMBER, .number=STARDUST_NUMBER_INTEGER, .integer=41};
stardust_document_builder *builder = NULL;
uint32_t status = stardust_document_builder_create(&builder);
if (status == STARDUST_OK) status = stardust_document_builder_add_many(builder, &input, 1);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) return status;
stardust_node_input result = input;

TRON

158 B

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

Also calls: stardust_document_builder_add_many, stardust_document_builder_error

stardust_document_builder_add_many

129 B

uint32_t stardust_document_builder_add_many(stardust_document_builder *builder, const stardust_node_input *nodes, int64_t count);

117 B

uint32_t stardust_document_builder_error(const stardust_document_builder *builder, stardust_diagnostic_view *output);

Requires exclusive use of the receiver handle.

Parameters

stardust_document_builder_add_many

Parameter	Type	Ownership	Default	Meaning
`builder`	`stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`nodes`	`const stardust_node_input *`	Borrowed array	NULL	Nodes in depth-first preorder to append together.
`count`	`int64_t`	Value	Required	Value passed to the call.

stardust_document_builder_error

Parameter	Type	Ownership	Default	Meaning
`builder`	`const stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	a node breaks the preorder rules or has an invalid kind or number
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted

Examples

builder/add_many

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

TRON

33 B

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

builder/add_many

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

TRON

33 B

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

Also calls: stardust_document_builder_error

stardust_document_builder_seal

104 B

uint32_t stardust_document_builder_seal(stardust_document_builder *builder, stardust_document **output);

117 B

uint32_t stardust_document_builder_error(const stardust_document_builder *builder, stardust_diagnostic_view *output);

Requires exclusive use of the receiver handle.

Parameters

stardust_document_builder_seal

Parameter	Type	Ownership	Default	Meaning
`builder`	`stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_document_builder_error

Parameter	Type	Ownership	Default	Meaning
`builder`	`const stardust_document_builder *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	the builder has no root or a container is still open
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted

Notes

The builder accepts no more nodes after sealing.

Examples

builder/seal

692 B

stardust_document_builder *builder = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_node_input nodes[] = {
    {.parent = STARDUST_DOCUMENT_NO_NODE, .kind = STARDUST_OBJECT},
    {.parent = 0, .kind = STARDUST_NUMBER, .key = {(const uint8_t *)"x", 1},
     .number = STARDUST_NUMBER_INTEGER, .integer = 41},
};
if (status == STARDUST_OK)
    status = stardust_document_builder_add_many(builder, nodes, 2);
if (status == STARDUST_OK)
    status = stardust_document_builder_seal(builder, &result);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) {
    stardust_document_release(result);
    return status;
}

TRON

33 B

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

Also calls: stardust_document_builder_error

stardust_document_builder_release

75 B

void stardust_document_builder_release(stardust_document_builder *builder);

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`builder`	`stardust_document_builder *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Examples

builder/close

input_text holds this document:

TRON

33 B

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

364 B

stardust_document_builder *builder = NULL;
uint32_t status = stardust_document_builder_create(&builder);
stardust_document_builder_release(builder);
if (status != STARDUST_OK) return status;
stardust_document *result = NULL;
status = stardust_parse(input_text, STARDUST_TRON, &result);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

33 B

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