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:

json333 B
{
  "#_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"
  }
}
odin280 B
people := stardust.parse(people_text, .JSON) or_return
defer stardust.close(&people)

root := stardust.root(people) or_return
ada := stardust.member(people, root, "#_ada") or_return
age := stardust.member(people, ada, "age") or_return
result := stardust.i64(people, age) or_return
Result / 2 B
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

OperationReturnsSummary
parsedocumentparse(text, format) returns an owned document.
rootnodedocument.root() returns the root node ID.
countcountdocument.count() returns the number of nodes.
readnode_viewdocument.read(id) returns a node view: kind, boolean, parent, position, first_child, next_sibling, key and text.
read_manynode_viewsdocument.read_many(start, capacity) reads consecutive node views.
membernodedocument.member(id, key) returns the first matching object member ID.
child_iteratornode_viewsdocument.children(id) iterates the node views of a node's children in order.
membersUnavailabledocument.members(id) iterates the members of an object node in order, each with its key.
i64integerRead an exact signed integer.
f64realRead a finite floating-point number.
closenoneRelease the document handle.

parse

odin114 B
parse :: proc(
	text: string,
	format: Source_Format,
	allocator := context.allocator,
) -> (
	Document,
	Error,
)

Parameters

ParameterTypeOwnershipDefaultMeaning
textstringValueRequiredEncoded input bytes in the selected format. TRON is binary.
formatSource_FormatValueRequiredThe codec to use for this operation.
allocatormem.AllocatorValuecontext.allocatorAllocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

StatusWhen
.Invalid_JSONJSON text is malformed
.Invalid_Argumentthe text is malformed, the format is unknown or a number is outside i64 or finite f64
.Out_Of_Memorynative memory is exhausted

Examples

Parse the shared DUST expression fixture

expression_text holds these bytes:

text278 B
// 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]
odin88 B
result := stardust.parse(expression_text, .DUST) or_return
defer stardust.close(&result)
Result / 381 B
{
  "$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:

text1 B
]
odin110 B
failed, result := stardust.parse(malformed, .DUST)
defer stardust.close(&failed)
defer stardust.close(&result)
Result / 169 B
{
  "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:

text1 B
[
odin110 B
failed, result := stardust.parse(malformed, .DUST)
defer stardust.close(&failed)
defer stardust.close(&result)
Result / 169 B
{
  "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

root

odin48 B
root :: proc(document: Document) -> (u32, Error)

Parameters

ParameterTypeOwnershipDefaultMeaning
documentDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.

Errors

StatusWhen
.Closedthe document is closed

Examples

document/root

input_text holds this document:

json14 B
{
  "x": 41
}
odin131 B
source := stardust.parse(input_text, .JSON) or_return
defer stardust.close(&source)

result := i64(stardust.root(source) or_return)
Result / 1 B
0

C exports: stardust_document_root

count

odin57 B
count :: proc(document: Document) -> (builtin.i64, Error)

Parameters

ParameterTypeOwnershipDefaultMeaning
documentDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.

Errors

StatusWhen
.Closedthe document is closed

Examples

document/count

input_text holds this document:

json14 B
{
  "x": 41
}
odin132 B
source := stardust.parse(input_text, .JSON) or_return
defer stardust.close(&source)

result := i64(stardust.count(source) or_return)
Result / 1 B
2

C exports: stardust_document_count

read

odin63 B
read :: proc(document: Document, id: u32) -> (Node_View, Error)

Parameters

ParameterTypeOwnershipDefaultMeaning
documentDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.
idu32ValueRequiredA node ID within the receiver document.

Errors

StatusWhen
.Invalid_Argumentid is not a node of the document
.Closedthe document is closed

Notes

Text contains string values. Read numbers with i64 or f64.

Examples

document/read

input_text holds this document:

json14 B
{
  "x": 41
}
odin172 B
source := stardust.parse(input_text, .JSON) or_return
defer stardust.close(&source)

root := stardust.root(source) or_return
result := stardust.read(source, root) or_return
Result / 148 B
{
  "kind": "object",
  "boolean": false,
  "parent": null,
  "position": 0,
  "first_child": 1,
  "next_sibling": null,
  "key": "",
  "text": ""
}

C exports: stardust_document_read_many

read_many

odin86 B
read_many :: proc(document: Document, start: u32, output: []Node_View) -> (int, Error)

Parameters

ParameterTypeOwnershipDefaultMeaning
documentDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.
startu32ValueRequiredThe first node ID of the consecutive read.
output[]Node_ViewValueRequiredThe maximum number of node views to read. For output slices, the call uses the caller's slice length.

Errors

StatusWhen
.Invalid_Argumentstart is past the last node or capacity is negative
.Closedthe document is closed

Examples

document/read_many

input_text holds this document:

json14 B
{
  "x": 41
}
odin229 B
source := stardust.parse(input_text, .JSON) or_return
defer stardust.close(&source)

root := stardust.root(source) or_return
views: [1]stardust.Node_View
_ = stardust.read_many(source, root, views[:]) or_return
result := views[0]
Result / 148 B
{
  "kind": "object",
  "boolean": false,
  "parent": null,
  "position": 0,
  "first_child": 1,
  "next_sibling": null,
  "key": "",
  "text": ""
}

C exports: stardust_document_read_many

member

odin72 B
member :: proc(document: Document, id: u32, key: string) -> (u32, Error)

Parameters

ParameterTypeOwnershipDefaultMeaning
documentDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.
idu32ValueRequiredA node ID within the receiver document.
keystringValueRequiredThe object member name to find.

Errors

StatusWhen
.Not_Foundthe object has no member with the key
.Invalid_Argumentid is not an object node of the document
.Closedthe document is closed

Examples

document/member

input_text holds this document:

json14 B
{
  "x": 41
}
odin197 B
source := stardust.parse(input_text, .JSON) or_return
defer stardust.close(&source)

root := stardust.root(source) or_return
node := stardust.member(source, root, "x") or_return
result := i64(node)
Result / 1 B
1

C exports: stardust_document_member

child_iterator

odin64 B
child_iterator :: proc(doc: Document, id: u32) -> Child_Iterator

Parameters

ParameterTypeOwnershipDefaultMeaning
docDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.
idu32ValueRequiredA node ID within the receiver document.

Errors

StatusWhen
.Invalid_Argumentid is not a node of the document
.Closedthe document is closed

Notes

Keep the document open during iteration. A scalar has no children. A read failure is reported once and ends iteration.

Examples

Iterate the children of a node

seed_text holds this document:

json333 B
{
  "#_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"
  }
}
odin291 B
seed := stardust.parse(seed_text, .JSON) or_return
defer stardust.close(&seed)

root := stardust.root(seed) or_return
it := stardust.child_iterator(seed, root)
result: i64 = 0
for view in stardust.iterate_children(&it) {
	if len(view.key) > 0 {result += 1}
}
if it.err != nil {return it.err}
Result / 1 B
4

C exports: stardust_document_read_many

members

child_iterator views carry each member key. Odin has no separate members iterator.

C exports: stardust_document_read_many

i64

odin64 B
i64 :: proc(document: Document, id: u32) -> (builtin.i64, Error)

Parameters

ParameterTypeOwnershipDefaultMeaning
documentDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.
idu32ValueRequiredA node ID within the receiver document.

Errors

StatusWhen
.Invalid_Argumentthe node is not an integer number
.Closedthe document is closed

Examples

document/i64

input_text holds this document:

json14 B
{
  "x": 41
}
odin224 B
source := stardust.parse(input_text, .JSON) or_return
defer stardust.close(&source)

root := stardust.root(source) or_return
node := stardust.member(source, root, "x") or_return
result := stardust.i64(source, node) or_return
Result / 2 B
41

C exports: stardust_document_i64

f64

odin64 B
f64 :: proc(document: Document, id: u32) -> (builtin.f64, Error)

Parameters

ParameterTypeOwnershipDefaultMeaning
documentDocumentBorrowed for the callRequiredThe document owner for this operation. Keep it alive during the call.
idu32ValueRequiredA node ID within the receiver document.

Errors

StatusWhen
.Invalid_Argumentthe node is not a number or its value overflows f64
.Closedthe document is closed

Notes

Integer conversion can round values outside the exact f64 integer range.

Examples

document/f64

float_text holds this document:

json4 B
1.0
odin158 B
source := stardust.parse(float_text, .JSON) or_return
defer stardust.close(&source)

result := stardust.f64(source, stardust.root(source) or_return) or_return
Result / 3 B
1.0

C exports: stardust_document_f64

close

odin34 B
close :: proc(document: ^Document)

Consumes the receiver handle.

Parameters

ParameterTypeOwnershipDefaultMeaning
document^DocumentConsumed ownerRequiredThe document owner to release. Do not use it after this call.

Examples

document/close

expression_text holds this document:

json23 B
[
  "+",
  "?x",
  1
]
odin189 B
source := stardust.parse(expression_text, .JSON) or_return
defer stardust.close(&source)

result := stardust.serialize(source, .JSON) or_return
defer delete(result)

stardust.close(&source)
Result / 32 B
{
  "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 borrow the document until it closes.

FieldTypeUnitAbsentMeaning
kindValue_KindNone——
booleanboolNone—True only for true.
parentu32NoneNO_NODE—
positionu32Count—Index within the parent container.
first_childu32NoneNO_NODE—
next_siblingu32NoneNO_NODE—
keystringNone—Member key of an object member, else empty.
textstringNone—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.

FieldTypeAbsentMeaning
parentu32NO_NODE—
kindValue_Kind——
booleanbool—Value of a boolean node.
numberNumbernilValue of a number node.
keystring—Member key when the parent is an object.
textstring—Value of a string node.