Types and units
The document operations use typed values, and the database operations add time values. The tables use the type names of your selected language. Use it to find the unit, range, default, and absent value of a field.
Text uses UTF-8. This includes string values, object keys, and JSON, DUST, and EDN input and output. The document builders reject invalid UTF-8 strings and keys. TRON is binary, but its strings and keys also use UTF-8. Byte lengths count encoded bytes, rather than characters.
This matches JSON's UTF-8 requirement for interchange (RFC 8259, section 8.1).
Evaluation and database read results recursively omit object fields containing empty objects or arrays. This includes objects emptied by nested omissions. Null, empty strings, false, zero and array positions stay intact. Input documents and expanded programs preserve their contents.
- Time and units defines the tick, its range and resolution, and the host conversion.
- Value types defines documents, formats, node IDs, transactions, entities, instants, durations, numbers, and bytes.
- Other kinds defines the remaining parameter and result kinds, such as text and counts.
Time and units
The ABI uses one time unit: the 100 ns tick, stored as an i64 count.
- A duration is a signed tick count.
- An instant is the tick count since the Unix epoch,
1970-01-01T00:00:00Z. It is in UTC, with no leap seconds and no time zone. - DUST durations and UTC values use the same unit, so database data and API parameters need no unit conversion.
Range
An i64 tick count holds approximately 29,227 years on each side of the Unix epoch:
| Quantity | Value |
|---|---|
| Largest positive count | 2^63 - 1 = 9,223,372,036,854,775,807 ticks |
| Ticks per second | 10,000,000 |
| Largest positive duration | Approximately 922,337,203,685 seconds, or 29,227.7 Gregorian years |
| Instant range from the Unix epoch | Approximately 27,258 BCE to 31,197 CE |
This covers all written history, including cuneiform from approximately 3400 BCE.
Note
It also covers these fictional settings:
- The Butlerian Jihad: approximately 13,000 CE in The Dune Encyclopedia.
- The Horus Heresy: 30,005 to 30,014 CE (
005.M31to014.M31).
Resolution
One tick is 100 ns, or 0.0000001 s.
Note
At its peak speed, the Parker Solar Probe, the fastest human-made object, travels approximately 19 mm in one tick.
| Calculation | Value |
|---|---|
| Probe's peak speed | 191.2 km/s = 191,200 m/s |
| Time interval | 1 tick = 0.0000001 s |
| Distance = speed × time | 191,200 × 0.0000001 = 0.01912 m ≈ 19 mm |
Thread wake-up jitter on common platforms is microseconds, so a smaller unit gives no useful precision. Windows also counts time in 100 ns units.
Order and time zones
- Integer ticks have no floating-point rounding. ABI numbers are
i64orf64only. - An instant in UTC ticks has no time zone or daylight-saving state. Each instant has one meaning, and integer comparison gives the time order.
- The host applies time zones for presentation.
- Each binding uses the duration and instant types of its language and converts at the call boundary.
C conversion
C passes durations and instants as int64_t tick counts. The caller converts them.
Value types
Each value type has one meaning in every language. Types below use the selected language's spelling.
| Value | Type | Unit | Range | Absent |
|---|---|---|---|---|
| document | stardust_document* | None | Available memory | A null handle |
| format | stardust_source_format | None | JSON, DUST, EDN, TRON | Never absent |
| node_id | uint32_t | Count | 0 through 2147483646 | 4294967295 |
| transaction | int64_t | Count | Signed 64-bit integer | Zero selects the latest snapshot |
| entity | int64_t | Count | Signed 64-bit integer | Never absent |
| instant | int64_t | 100 ns ticks | Signed 64-bit ticks (host ranges differ) | Zero when no commit was written |
| duration | int64_t | 100 ns ticks | Signed 64-bit ticks (host ranges differ) | Each field defines its zero or negative sentinel |
| number | stardust_number_kind, int64_t, double | None | i64 or finite f64 | Never absent |
| bytes | stardust_bytes | Bytes | Available memory | An empty sequence |
document
An owned native document preserves ordered members and duplicate keys.
format
The format selects a text codec or binary TRON.
node_id
A node ID selects a node within its owning document.
transaction
A transaction selects a committed database snapshot.
entity
An entity identifies an object in a database.
instant
An instant counts 100 ns ticks since the Unix epoch. An instant outside the host range reports time_out_of_range.
duration
A duration counts 100 ns ticks. Conversions beyond a host duration range saturate.
number
A number is a signed integer or finite floating-point value.
bytes
Bytes contain a borrowed byte sequence with an explicit length.
Other kinds
These kinds have no value type of their own. The signature of each operation gives the exact type. Parameter tables link handle and record kinds to the operation or record that defines them.
| Kind | Meaning |
|---|---|
none | The operation returns no value. |
version | An ABI version number. |
text | UTF-8 text, or binary bytes for TRON. |
integer | A signed 64-bit integer. |
real | A finite 64-bit floating-point number. |
count | A count that is not negative. |
boolean | True or false. |
name | A string: a key, title, path, kind or pattern. |
value | A host value. The host mapping gives its document form. |
source | A stored definition path or an inline definition document. |
Binding mechanics
Bindings may include these arguments in addition to native operation arguments:
| Argument | Purpose |
|---|---|
| Allocator | Owns copied output and diagnostics. |
| Cancellation context | Controls cancellation. |
| Loaded library | Selects the native ABI library. |
Optional wrappers such as pointers, Option and Maybe keep the wrapped type's contract.
Record examples
The generator captured each result from the native library.
Activate the license from a token file
char token[4097];
FILE *file = fopen("license.token", "rb");
if (file == NULL) return STARDUST_INVALID_ARGUMENT;
size_t length = fread(token, 1, sizeof token, file);
fclose(file);
while (length > 0 && (token[length - 1] == '\n' || token[length - 1] == '\r')) length--;
stardust_bytes bytes = {(const uint8_t *)token, (int64_t)length};
stardust_license_view result = {.size = sizeof(stardust_license_view), .version = 1};
uint32_t status = stardust_activate(bytes);
if (status == STARDUST_OK) status = stardust_license(&result);
if (status != STARDUST_OK) return status;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 000 | 54 52 4F 4E | magic TRON |
| 004 | 5C 6275696C64 | txt "build" |
| 00A | 00 | nil |
| 00B | 0F 0A 04000000 0A00 0000 | map leaf, size 10: @4 → @A |
| 015 | 4C 74696572 | txt "tier" |
| 01A | 0C | txt "" |
| 01B | 0F 0A 15000000 1A00 0000 | map leaf, size 10: @15 → @1A |
| 025 | 07 0E 20080000 0B00 0000 1B000000 | map branch, size 14, depth 1, slots 5, 11: @B → @1B |
| 033 | 14 13 726566757365 645F737570706F72 745F656E64 | txt "refused_support_end" |
| 048 | 00 | nil |
| 049 | 0F 0A 33000000 4800 0000 | map leaf, size 10: @33 → @48 |
| 053 | AC 6C6963656E7365 5F6964 | txt "license_id" |
| 05E | 4C 74657374 | txt "test" |
| 063 | 0F 0A 53000000 5E00 0000 | map leaf, size 10: @53 → @5E |
| 06D | 07 0E 08020000 4900 0000 63000000 | map branch, size 14, depth 1, slots 3, 9: @49 → @63 |
| 07B | 7C 6661696C757265 | txt "failure" |
| 083 | 4C 6E6F6E65 | txt "none" |
| 088 | 0F 0A 7B000000 8300 0000 | map leaf, size 10: @7B → @83 |
| 092 | 7C 6C6963656E7365 | txt "license" |
| 09A | 0C | txt "" |
| 09B | 0F 0A 92000000 9A00 0000 | map leaf, size 10: @92 → @9A |
| 0A5 | 7C 7375626A656374 | txt "subject" |
| 0AD | 4C 74657374 | txt "test" |
| 0B2 | 0F 0A A5000000 AD00 0000 | map leaf, size 10: @A5 → @AD |
| 0BC | BC 737570706F7274 5F656E64 | txt "support_end" |
| 0C8 | 02 00C0489F6ADB01 01 | i64 72580320000000000 |
| 0D1 | 0F 0A BC000000 C800 0000 | map leaf, size 10: @BC → @C8 |
| 0DB | 6C 616374697665 | txt "active" |
| 0E2 | 09 | bit true |
| 0E3 | 0F 0A DB000000 E200 0000 | map leaf, size 10: @DB → @E2 |
| 0ED | 4C 6E616D65 | txt "name" |
| 0F2 | 0C | txt "" |
| 0F3 | 0F 0A ED000000 F200 0000 | map leaf, size 10: @ED → @F2 |
| 0FD | 7C 65787069726573 | txt "expires" |
| 105 | 00 | nil |
| 106 | 0F 0A FD000000 0501 0000 | map leaf, size 10: @FD → @105 |
| 110 | 07 0E 06000000 F300 0000 06010000 | map branch, size 14, depth 1, slots 1, 2: @F3 → @106 |
| 11E | 07 26 219F0000 2500 0000 6D000000 8800 0000 9B000000 B200 0000 D1000000 E300 0000 10010000 | map branch, size 38, depth 0 (root), slots 0, 5, 8, 9, 10, 11, 12, 15: @25 → @6D → @88 → @9B → @B2 → @D1 → @E3 → @110 |
| 144 | 1E010000 00000000 | root → @11E; previous: none |
Add a typed integer node
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;| 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 |
database/merge_patch
seed_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 000 | 54 52 4F 4E | magic TRON |
| 004 | 3C 616765 | txt "age" |
| 008 | 02 24000000000000 00 | i64 36 |
| 011 | 0F 0A 04000000 0800 0000 | map leaf, size 10: @4 → @8 |
| 01B | 4C 726F6C65 | txt "role" |
| 020 | 8C 656E67696E6565 72 | txt "engineer" |
| 029 | 0F 0A 1B000000 2000 0000 | map leaf, size 10: @1B → @20 |
| 033 | 4C 6E616D65 | txt "name" |
| 038 | 3C 416461 | txt "Ada" |
| 03C | 0F 0A 33000000 3800 0000 | map leaf, size 10: @33 → @38 |
| 046 | 07 12 00910000 1100 0000 29000000 3C00 0000 | map branch, size 18, depth 0 (root), slots 8, 12, 15: @11 → @29 → @3C |
| 058 | 5C 236C696E6B | txt "#link" |
| 05E | 5C 235F616461 | txt "#_ada" |
| 064 | 0F 0A 58000000 5E00 0000 | map leaf, size 10: @58 → @5E |
| 06E | 3C 616765 | txt "age" |
| 072 | 02 29000000000000 00 | i64 41 |
| 07B | 0F 0A 6E000000 7200 0000 | map leaf, size 10: @6E → @72 |
| 085 | 6C 6D656E746F72 | txt "mentor" |
| 08C | 0F 0A 85000000 6400 0000 | map leaf, size 10: @85 → @64 |
| 096 | 4C 726F6C65 | txt "role" |
| 09B | 8C 656E67696E6565 72 | txt "engineer" |
| 0A4 | 0F 0A 96000000 9B00 0000 | map leaf, size 10: @96 → @9B |
| 0AE | 4C 6E616D65 | txt "name" |
| 0B3 | 3C 426F62 | txt "Bob" |
| 0B7 | 0F 0A AE000000 B300 0000 | map leaf, size 10: @AE → @B3 |
| 0C1 | 07 16 00990000 7B00 0000 8C000000 A400 0000 B7000000 | map branch, size 22, depth 0 (root), slots 8, 11, 12, 15: @7B → @8C → @A4 → @B7 |
| 0D7 | 3C 616765 | txt "age" |
| 0DB | 02 1D000000000000 00 | i64 29 |
| 0E4 | 0F 0A D7000000 DB00 0000 | map leaf, size 10: @D7 → @DB |
| 0EE | 4C 726F6C65 | txt "role" |
| 0F3 | 8C 64657369676E65 72 | txt "designer" |
| 0FC | 0F 0A EE000000 F300 0000 | map leaf, size 10: @EE → @F3 |
| 106 | 4C 6E616D65 | txt "name" |
| 10B | 2C 4379 | txt "Cy" |
| 10E | 0F 0A 06010000 0B01 0000 | map leaf, size 10: @106 → @10B |
| 118 | 07 12 00910000 E400 0000 FC000000 0E01 0000 | map branch, size 18, depth 0 (root), slots 8, 12, 15: @E4 → @FC → @10E |
| 12A | 6C 617574686F72 | txt "author" |
| 131 | 5C 736D6F6B65 | txt "smoke" |
| 137 | 0F 0A 2A010000 3101 0000 | map leaf, size 10: @12A → @131 |
| 141 | 6C 726561736F6E | txt "reason" |
| 148 | 4C 73656564 | txt "seed" |
| 14D | 0F 0A 41010000 4801 0000 | map leaf, size 10: @141 → @148 |
| 157 | 07 0E 40080000 3701 0000 4D010000 | map branch, size 14, depth 0 (root), slots 6, 11: @137 → @14D |
| 165 | 4C 235F7478 | txt "#_tx" |
| 16A | 0F 0A 65010000 5701 0000 | map leaf, size 10: @165 → @157 |
| 174 | 4C 235F6379 | txt "#_cy" |
| 179 | 0F 0A 74010000 1801 0000 | map leaf, size 10: @174 → @118 |
| 183 | 5C 235F626F62 | txt "#_bob" |
| 189 | 0F 0A 83010000 C100 0000 | map leaf, size 10: @183 → @C1 |
| 193 | 5C 235F616461 | txt "#_ada" |
| 199 | 0F 0A 93010000 4600 0000 | map leaf, size 10: @193 → @46 |
| 1A3 | 07 16 88210000 6A01 0000 79010000 8901 0000 99010000 | map branch, size 22, depth 0 (root), slots 3, 7, 8, 13: @16A → @179 → @189 → @199 |
| 1B9 | A3010000 00000000 | root → @1A3; previous: none |
stardust_document *patch = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(seed_text, STARDUST_TRON, &patch);
if (status == STARDUST_OK) status = stardust_db_merge_patch(db, patch, NULL, NULL, &result);
stardust_document_release(patch);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 000 | 54 52 4F 4E | magic TRON |
| 004 | 4C 235F6379 | txt "#_cy" |
| 009 | 02 01000000000000 00 | i64 1 |
| 012 | 0F 0A 04000000 0900 0000 | map leaf, size 10: @4 → @9 |
| 01C | 5C 235F626F62 | txt "#_bob" |
| 022 | 02 02000000000000 00 | i64 2 |
| 02B | 0F 0A 1C000000 2200 0000 | map leaf, size 10: @1C → @22 |
| 035 | 5C 235F616461 | txt "#_ada" |
| 03B | 02 03000000000000 00 | i64 3 |
| 044 | 0F 0A 35000000 3B00 0000 | map leaf, size 10: @35 → @3B |
| 04E | 07 12 80210000 1200 0000 2B000000 4400 0000 | map branch, size 18, depth 0 (root), slots 7, 8, 13: @12 → @2B → @44 |
| 060 | 3C 696473 | txt "ids" |
| 064 | 0F 0A 60000000 4E00 0000 | map leaf, size 10: @60 → @4E |
| 06E | 6C 737461747573 | txt "status" |
| 075 | 9C 636F6D6D697474 6564 | txt "committed" |
| 07F | 0F 0A 6E000000 7500 0000 | map leaf, size 10: @6E → @75 |
| 089 | 07 0E 02040000 6400 0000 7F000000 | map branch, size 14, depth 1, slots 1, 10: @64 → @7F |
| 097 | BC 7472616E736163 74696F6E | txt "transaction" |
| 0A3 | 02 04000000000000 00 | i64 4 |
| 0AC | 0F 0A 97000000 A300 0000 | map leaf, size 10: @97 → @A3 |
| 0B6 | CC 636F6D6D697474 65645F6174 | txt "committed_at" |
| 0C3 | 02 84AC8E4A35AD3F 00 | i64 17923367928507524 |
| 0CC | 0F 0A B6000000 C300 0000 | map leaf, size 10: @B6 → @C3 |
| 0D6 | 5C 6661637473 | txt "facts" |
| 0DC | 02 0C000000000000 00 | i64 12 |
| 0E5 | 0F 0A D6000000 DC00 0000 | map leaf, size 10: @D6 → @DC |
| 0EF | 07 16 01460000 8900 0000 AC000000 CC00 0000 E5000000 | map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @89 → @AC → @CC → @E5 |
| 105 | EF000000 00000000 | root → @EF; previous: none |
database/mutation
birthday_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 2C 3F65 | txt "?e" |
| 07 | 0E 0D 00 0100 010000 00 04000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4 |
| 14 | 2C 3F65 | txt "?e" |
| 17 | 4C 6E616D65 | txt "name" |
| 1C | 3C 416461 | txt "Ada" |
| 20 | 0E 15 00 0700 030000 00 14000000 170000 00 1C000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C |
| 35 | 0E 0D 00 0100 010000 00 20000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20 |
| 42 | 5C 7768657265 | txt "where" |
| 48 | 0F 0A 42000000 3500 0000 | map leaf, size 10: @42 → @35 |
| 52 | 4C 66696E64 | txt "find" |
| 57 | 0F 0A 52000000 0700 0000 | map leaf, size 10: @52 → @7 |
| 61 | 07 0E 0A000000 4800 0000 57000000 | map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57 |
| 6F | 3C 616765 | txt "age" |
| 73 | 02 25000000000000 00 | i64 37 |
| 7C | 0F 0A 6F000000 7300 0000 | map leaf, size 10: @6F → @73 |
| 86 | 2C 3F65 | txt "?e" |
| 89 | 0F 0A 86000000 7C00 0000 | map leaf, size 10: @86 → @7C |
| 93 | 5C 7175657279 | txt "query" |
| 99 | 0F 0A 93000000 6100 0000 | map leaf, size 10: @93 → @61 |
| A3 | 5C 7061746368 | txt "patch" |
| A9 | 0F 0A A3000000 8900 0000 | map leaf, size 10: @A3 → @89 |
| B3 | 07 0E 40020000 9900 0000 A9000000 | map branch, size 14, depth 2, slots 6, 9: @99 → @A9 |
| C1 | 07 0A 01000000 B300 0000 | map branch, size 10, depth 1, slots 0: @B3 |
| CB | 07 0A 80000000 C100 0000 | map branch, size 10, depth 0 (root), slots 7: @C1 |
| D5 | CB000000 00000000 | root → @CB; previous: none |
stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &source, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &result);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 0F 02 | map leaf, size 2 |
| 06 | 3C 696473 | txt "ids" |
| 0A | 0F 0A 06000000 0400 0000 | map leaf, size 10: @6 → @4 |
| 14 | 6C 737461747573 | txt "status" |
| 1B | 9C 636F6D6D697474 6564 | txt "committed" |
| 25 | 0F 0A 14000000 1B00 0000 | map leaf, size 10: @14 → @1B |
| 2F | 07 0E 02040000 0A00 0000 25000000 | map branch, size 14, depth 1, slots 1, 10: @A → @25 |
| 3D | BC 7472616E736163 74696F6E | txt "transaction" |
| 49 | 02 05000000000000 00 | i64 5 |
| 52 | 0F 0A 3D000000 4900 0000 | map leaf, size 10: @3D → @49 |
| 5C | CC 636F6D6D697474 65645F6174 | txt "committed_at" |
| 69 | 02 3F9FB74A35AD3F 00 | i64 17923367931191103 |
| 72 | 0F 0A 5C000000 6900 0000 | map leaf, size 10: @5C → @69 |
| 7C | 5C 6661637473 | txt "facts" |
| 82 | 02 01000000000000 00 | i64 1 |
| 8B | 0F 0A 7C000000 8200 0000 | map leaf, size 10: @7C → @82 |
| 95 | 07 16 01460000 2F00 0000 52000000 7200 0000 8B000000 | map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B |
| AB | 95000000 00000000 | root → @95; previous: none |
database/patch_definition
definition_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 000 | 54 52 4F 4E | magic TRON |
| 004 | 5C 3F726F6C65 | txt "?role" |
| 00A | 8C 656E67696E6565 72 | txt "engineer" |
| 013 | 0F 0A 04000000 0A00 0000 | map leaf, size 10: @4 → @A |
| 01D | 5C 3F6E616D65 | txt "?name" |
| 023 | 0E 0D 00 0100 010000 00 1D000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @1D |
| 030 | 2C 3F65 | txt "?e" |
| 033 | 4C 726F6C65 | txt "role" |
| 038 | 5C 3F726F6C65 | txt "?role" |
| 03E | 0E 15 00 0700 030000 00 30000000 330000 00 38000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @30 → @33 → @38 |
| 053 | 2C 3F65 | txt "?e" |
| 056 | 4C 6E616D65 | txt "name" |
| 05B | 5C 3F6E616D65 | txt "?name" |
| 061 | 0E 15 00 0700 030000 00 53000000 560000 00 5B000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @53 → @56 → @5B |
| 076 | 0E 11 00 0300 020000 00 3E000000 610000 00 | array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @3E → @61 |
| 087 | 5C 3F6E616D65 | txt "?name" |
| 08D | 0E 0D 00 0100 010000 00 87000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @87 |
| 09A | 5C 7768657265 | txt "where" |
| 0A0 | 0F 0A 9A000000 7600 0000 | map leaf, size 10: @9A → @76 |
| 0AA | 4C 66696E64 | txt "find" |
| 0AF | 0F 0A AA000000 2300 0000 | map leaf, size 10: @AA → @23 |
| 0B9 | AC 706172616D6574 657273 | txt "parameters" |
| 0C4 | 0F 0A B9000000 1300 0000 | map leaf, size 10: @B9 → @13 |
| 0CE | 7C 6F726465724279 | txt "orderBy" |
| 0D6 | 0F 0A CE000000 8D00 0000 | map leaf, size 10: @CE → @8D |
| 0E0 | 07 0E 20080000 C400 0000 D6000000 | map branch, size 14, depth 1, slots 5, 11: @C4 → @D6 |
| 0EE | 07 12 2A000000 A000 0000 AF000000 E000 0000 | map branch, size 18, depth 0 (root), slots 1, 3, 5: @A0 → @AF → @E0 |
| 100 | EE000000 00000000 | root → @EE; previous: none |
stardust_document *definition = NULL;
stardust_result *result = NULL;
stardust_bytes kind = {(const uint8_t *)"queries", 7};
stardust_bytes path = {(const uint8_t *)"people/by_role", 14};
uint32_t status = stardust_parse(definition_text, STARDUST_TRON, &definition);
if (status == STARDUST_OK) status = stardust_db_definition_patch(db, kind, path, definition, &result);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 0F 02 | map leaf, size 2 |
| 06 | 3C 696473 | txt "ids" |
| 0A | 0F 0A 06000000 0400 0000 | map leaf, size 10: @6 → @4 |
| 14 | 6C 737461747573 | txt "status" |
| 1B | 9C 636F6D6D697474 6564 | txt "committed" |
| 25 | 0F 0A 14000000 1B00 0000 | map leaf, size 10: @14 → @1B |
| 2F | 07 0E 02040000 0A00 0000 25000000 | map branch, size 14, depth 1, slots 1, 10: @A → @25 |
| 3D | BC 7472616E736163 74696F6E | txt "transaction" |
| 49 | 02 03000000000000 00 | i64 3 |
| 52 | 0F 0A 3D000000 4900 0000 | map leaf, size 10: @3D → @49 |
| 5C | CC 636F6D6D697474 65645F6174 | txt "committed_at" |
| 69 | 02 81E7C34A35AD3F 00 | i64 17923367931996033 |
| 72 | 0F 0A 5C000000 6900 0000 | map leaf, size 10: @5C → @69 |
| 7C | 5C 6661637473 | txt "facts" |
| 82 | 02 00000000000000 00 | i64 0 |
| 8B | 0F 0A 7C000000 8200 0000 | map leaf, size 10: @7C → @82 |
| 95 | 07 16 01460000 2F00 0000 52000000 7200 0000 8B000000 | map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B |
| AB | 95000000 00000000 | root → @95; previous: none |
document/read_many
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 |
stardust_document *source = NULL;
uint32_t root = 0;
stardust_node_view view = {0};
int64_t written = 0;
uint32_t status = stardust_parse(input_text, STARDUST_TRON, &source);
if (status == STARDUST_OK) status = stardust_document_root(source, &root);
if (status == STARDUST_OK) status = stardust_document_read_many(source, root, 1, &view, &written);
stardust_document_release(source);
if (status != STARDUST_OK) return status;
// The root object has no key or text, so the view borrows nothing.
stardust_node_view result = view;| 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 6F626A656374 | txt "object" |
| 1F | 0F 0A 13000000 1800 0000 | map leaf, size 10: @13 → @18 |
| 29 | BC 66697273745F63 68696C64 | txt "first_child" |
| 35 | 02 01000000000000 00 | i64 1 |
| 3E | 0F 0A 29000000 3500 0000 | map leaf, size 10: @29 → @35 |
| 48 | 8C 706F736974696F 6E | txt "position" |
| 51 | 02 00000000000000 00 | i64 0 |
| 5A | 0F 0A 48000000 5100 0000 | map leaf, size 10: @48 → @51 |
| 64 | 07 0E 00810000 3E00 0000 5A000000 | map branch, size 14, depth 1, slots 8, 15: @3E → @5A |
| 72 | 6C 706172656E74 | txt "parent" |
| 79 | 00 | nil |
| 7A | 0F 0A 72000000 7900 0000 | map leaf, size 10: @72 → @79 |
| 84 | 4C 74657874 | txt "text" |
| 89 | 0C | txt "" |
| 8A | 0F 0A 84000000 8900 0000 | map leaf, size 10: @84 → @89 |
| 94 | 7C 626F6F6C65616E | txt "boolean" |
| 9C | 01 | bit false |
| 9D | 0F 0A 94000000 9C00 0000 | map leaf, size 10: @94 → @9C |
| A7 | CC 6E6578745F7369 626C696E67 | txt "next_sibling" |
| B4 | 00 | nil |
| B5 | 0F 0A A7000000 B400 0000 | map leaf, size 10: @A7 → @B4 |
| BF | 07 22 A1990000 0900 0000 1F000000 6400 0000 7A000000 8A00 0000 9D000000 B500 0000 | map branch, size 34, depth 0 (root), slots 0, 5, 7, 8, 11, 12, 15: @9 → @1F → @64 → @7A → @8A → @9D → @B5 |
| E1 | BF000000 00000000 | root → @BF; previous: none |
document/read_many
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 |
stardust_document *source = NULL;
uint32_t root = 0;
stardust_node_view view = {0};
int64_t written = 0;
uint32_t status = stardust_parse(input_text, STARDUST_TRON, &source);
if (status == STARDUST_OK) status = stardust_document_root(source, &root);
if (status == STARDUST_OK) status = stardust_document_read_many(source, root, 1, &view, &written);
stardust_document_release(source);
if (status != STARDUST_OK) return status;
// The root object has no key or text, so the view borrows nothing.
stardust_node_view result = view;| 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 6F626A656374 | txt "object" |
| 1F | 0F 0A 13000000 1800 0000 | map leaf, size 10: @13 → @18 |
| 29 | BC 66697273745F63 68696C64 | txt "first_child" |
| 35 | 02 01000000000000 00 | i64 1 |
| 3E | 0F 0A 29000000 3500 0000 | map leaf, size 10: @29 → @35 |
| 48 | 8C 706F736974696F 6E | txt "position" |
| 51 | 02 00000000000000 00 | i64 0 |
| 5A | 0F 0A 48000000 5100 0000 | map leaf, size 10: @48 → @51 |
| 64 | 07 0E 00810000 3E00 0000 5A000000 | map branch, size 14, depth 1, slots 8, 15: @3E → @5A |
| 72 | 6C 706172656E74 | txt "parent" |
| 79 | 00 | nil |
| 7A | 0F 0A 72000000 7900 0000 | map leaf, size 10: @72 → @79 |
| 84 | 4C 74657874 | txt "text" |
| 89 | 0C | txt "" |
| 8A | 0F 0A 84000000 8900 0000 | map leaf, size 10: @84 → @89 |
| 94 | 7C 626F6F6C65616E | txt "boolean" |
| 9C | 01 | bit false |
| 9D | 0F 0A 94000000 9C00 0000 | map leaf, size 10: @94 → @9C |
| A7 | CC 6E6578745F7369 626C696E67 | txt "next_sibling" |
| B4 | 00 | nil |
| B5 | 0F 0A A7000000 B400 0000 | map leaf, size 10: @A7 → @B4 |
| BF | 07 22 A1990000 0900 0000 1F000000 6400 0000 7A000000 8A00 0000 9D000000 B500 0000 | map branch, size 34, depth 0 (root), slots 0, 5, 7, 8, 11, 12, 15: @9 → @1F → @64 → @7A → @8A → @9D → @B5 |
| E1 | BF000000 00000000 | root → @BF; previous: none |
Read the process license
stardust_license_view result = {.size = sizeof(stardust_license_view), .version = 1};
uint32_t status = stardust_license(&result);
if (status != STARDUST_OK) return status;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 000 | 54 52 4F 4E | magic TRON |
| 004 | 5C 6275696C64 | txt "build" |
| 00A | 00 | nil |
| 00B | 0F 0A 04000000 0A00 0000 | map leaf, size 10: @4 → @A |
| 015 | 4C 74696572 | txt "tier" |
| 01A | 0C | txt "" |
| 01B | 0F 0A 15000000 1A00 0000 | map leaf, size 10: @15 → @1A |
| 025 | 07 0E 20080000 0B00 0000 1B000000 | map branch, size 14, depth 1, slots 5, 11: @B → @1B |
| 033 | 14 13 726566757365 645F737570706F72 745F656E64 | txt "refused_support_end" |
| 048 | 00 | nil |
| 049 | 0F 0A 33000000 4800 0000 | map leaf, size 10: @33 → @48 |
| 053 | AC 6C6963656E7365 5F6964 | txt "license_id" |
| 05E | 4C 74657374 | txt "test" |
| 063 | 0F 0A 53000000 5E00 0000 | map leaf, size 10: @53 → @5E |
| 06D | 07 0E 08020000 4900 0000 63000000 | map branch, size 14, depth 1, slots 3, 9: @49 → @63 |
| 07B | 7C 6661696C757265 | txt "failure" |
| 083 | 4C 6E6F6E65 | txt "none" |
| 088 | 0F 0A 7B000000 8300 0000 | map leaf, size 10: @7B → @83 |
| 092 | 7C 6C6963656E7365 | txt "license" |
| 09A | 0C | txt "" |
| 09B | 0F 0A 92000000 9A00 0000 | map leaf, size 10: @92 → @9A |
| 0A5 | 7C 7375626A656374 | txt "subject" |
| 0AD | 4C 74657374 | txt "test" |
| 0B2 | 0F 0A A5000000 AD00 0000 | map leaf, size 10: @A5 → @AD |
| 0BC | BC 737570706F7274 5F656E64 | txt "support_end" |
| 0C8 | 02 00C0489F6ADB01 01 | i64 72580320000000000 |
| 0D1 | 0F 0A BC000000 C800 0000 | map leaf, size 10: @BC → @C8 |
| 0DB | 6C 616374697665 | txt "active" |
| 0E2 | 09 | bit true |
| 0E3 | 0F 0A DB000000 E200 0000 | map leaf, size 10: @DB → @E2 |
| 0ED | 4C 6E616D65 | txt "name" |
| 0F2 | 0C | txt "" |
| 0F3 | 0F 0A ED000000 F200 0000 | map leaf, size 10: @ED → @F2 |
| 0FD | 7C 65787069726573 | txt "expires" |
| 105 | 00 | nil |
| 106 | 0F 0A FD000000 0501 0000 | map leaf, size 10: @FD → @105 |
| 110 | 07 0E 06000000 F300 0000 06010000 | map branch, size 14, depth 1, slots 1, 2: @F3 → @106 |
| 11E | 07 26 219F0000 2500 0000 6D000000 8800 0000 9B000000 B200 0000 D1000000 E300 0000 10010000 | map branch, size 38, depth 0 (root), slots 0, 5, 8, 9, 10, 11, 12, 15: @25 → @6D → @88 → @9B → @B2 → @D1 → @E3 → @110 |
| 144 | 1E010000 00000000 | root → @11E; previous: none |
mutation/close
birthday_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 2C 3F65 | txt "?e" |
| 07 | 0E 0D 00 0100 010000 00 04000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4 |
| 14 | 2C 3F65 | txt "?e" |
| 17 | 4C 6E616D65 | txt "name" |
| 1C | 3C 416461 | txt "Ada" |
| 20 | 0E 15 00 0700 030000 00 14000000 170000 00 1C000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C |
| 35 | 0E 0D 00 0100 010000 00 20000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20 |
| 42 | 5C 7768657265 | txt "where" |
| 48 | 0F 0A 42000000 3500 0000 | map leaf, size 10: @42 → @35 |
| 52 | 4C 66696E64 | txt "find" |
| 57 | 0F 0A 52000000 0700 0000 | map leaf, size 10: @52 → @7 |
| 61 | 07 0E 0A000000 4800 0000 57000000 | map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57 |
| 6F | 3C 616765 | txt "age" |
| 73 | 02 25000000000000 00 | i64 37 |
| 7C | 0F 0A 6F000000 7300 0000 | map leaf, size 10: @6F → @73 |
| 86 | 2C 3F65 | txt "?e" |
| 89 | 0F 0A 86000000 7C00 0000 | map leaf, size 10: @86 → @7C |
| 93 | 5C 7175657279 | txt "query" |
| 99 | 0F 0A 93000000 6100 0000 | map leaf, size 10: @93 → @61 |
| A3 | 5C 7061746368 | txt "patch" |
| A9 | 0F 0A A3000000 8900 0000 | map leaf, size 10: @A3 → @89 |
| B3 | 07 0E 40020000 9900 0000 A9000000 | map branch, size 14, depth 2, slots 6, 9: @99 → @A9 |
| C1 | 07 0A 01000000 B300 0000 | map branch, size 10, depth 1, slots 0: @B3 |
| CB | 07 0A 80000000 C100 0000 | map branch, size 10, depth 0 (root), slots 7: @C1 |
| D5 | CB000000 00000000 | root → @CB; previous: none |
stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &source, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &result);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 0F 02 | map leaf, size 2 |
| 06 | 3C 696473 | txt "ids" |
| 0A | 0F 0A 06000000 0400 0000 | map leaf, size 10: @6 → @4 |
| 14 | 6C 737461747573 | txt "status" |
| 1B | 9C 636F6D6D697474 6564 | txt "committed" |
| 25 | 0F 0A 14000000 1B00 0000 | map leaf, size 10: @14 → @1B |
| 2F | 07 0E 02040000 0A00 0000 25000000 | map branch, size 14, depth 1, slots 1, 10: @A → @25 |
| 3D | BC 7472616E736163 74696F6E | txt "transaction" |
| 49 | 02 05000000000000 00 | i64 5 |
| 52 | 0F 0A 3D000000 4900 0000 | map leaf, size 10: @3D → @49 |
| 5C | CC 636F6D6D697474 65645F6174 | txt "committed_at" |
| 69 | 02 6E83F34A35AD3F 00 | i64 17923367935116142 |
| 72 | 0F 0A 5C000000 6900 0000 | map leaf, size 10: @5C → @69 |
| 7C | 5C 6661637473 | txt "facts" |
| 82 | 02 01000000000000 00 | i64 1 |
| 8B | 0F 0A 7C000000 8200 0000 | map leaf, size 10: @7C → @82 |
| 95 | 07 16 01460000 2F00 0000 52000000 7200 0000 8B000000 | map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B |
| AB | 95000000 00000000 | root → @95; previous: none |
mutation/run
birthday_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 2C 3F65 | txt "?e" |
| 07 | 0E 0D 00 0100 010000 00 04000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4 |
| 14 | 2C 3F65 | txt "?e" |
| 17 | 4C 6E616D65 | txt "name" |
| 1C | 3C 416461 | txt "Ada" |
| 20 | 0E 15 00 0700 030000 00 14000000 170000 00 1C000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C |
| 35 | 0E 0D 00 0100 010000 00 20000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20 |
| 42 | 5C 7768657265 | txt "where" |
| 48 | 0F 0A 42000000 3500 0000 | map leaf, size 10: @42 → @35 |
| 52 | 4C 66696E64 | txt "find" |
| 57 | 0F 0A 52000000 0700 0000 | map leaf, size 10: @52 → @7 |
| 61 | 07 0E 0A000000 4800 0000 57000000 | map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57 |
| 6F | 3C 616765 | txt "age" |
| 73 | 02 25000000000000 00 | i64 37 |
| 7C | 0F 0A 6F000000 7300 0000 | map leaf, size 10: @6F → @73 |
| 86 | 2C 3F65 | txt "?e" |
| 89 | 0F 0A 86000000 7C00 0000 | map leaf, size 10: @86 → @7C |
| 93 | 5C 7175657279 | txt "query" |
| 99 | 0F 0A 93000000 6100 0000 | map leaf, size 10: @93 → @61 |
| A3 | 5C 7061746368 | txt "patch" |
| A9 | 0F 0A A3000000 8900 0000 | map leaf, size 10: @A3 → @89 |
| B3 | 07 0E 40020000 9900 0000 A9000000 | map branch, size 14, depth 2, slots 6, 9: @99 → @A9 |
| C1 | 07 0A 01000000 B300 0000 | map branch, size 10, depth 1, slots 0: @B3 |
| CB | 07 0A 80000000 C100 0000 | map branch, size 10, depth 0 (root), slots 7: @C1 |
| D5 | CB000000 00000000 | root → @CB; previous: none |
stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &source, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &result);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 0F 02 | map leaf, size 2 |
| 06 | 3C 696473 | txt "ids" |
| 0A | 0F 0A 06000000 0400 0000 | map leaf, size 10: @6 → @4 |
| 14 | 6C 737461747573 | txt "status" |
| 1B | 9C 636F6D6D697474 6564 | txt "committed" |
| 25 | 0F 0A 14000000 1B00 0000 | map leaf, size 10: @14 → @1B |
| 2F | 07 0E 02040000 0A00 0000 25000000 | map branch, size 14, depth 1, slots 1, 10: @A → @25 |
| 3D | BC 7472616E736163 74696F6E | txt "transaction" |
| 49 | 02 05000000000000 00 | i64 5 |
| 52 | 0F 0A 3D000000 4900 0000 | map leaf, size 10: @3D → @49 |
| 5C | CC 636F6D6D697474 65645F6174 | txt "committed_at" |
| 69 | 02 3D9BFF4A35AD3F 00 | i64 17923367935908669 |
| 72 | 0F 0A 5C000000 6900 0000 | map leaf, size 10: @5C → @69 |
| 7C | 5C 6661637473 | txt "facts" |
| 82 | 02 01000000000000 00 | i64 1 |
| 8B | 0F 0A 7C000000 8200 0000 | map leaf, size 10: @7C → @82 |
| 95 | 07 16 01460000 2F00 0000 52000000 7200 0000 8B000000 | map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B |
| AB | 95000000 00000000 | root → @95; previous: none |
Open with explicit native options
stardust_db_options result = {.size=sizeof(result), .version=1, .create=1, .page_size=0};
stardust_db *database = NULL;
stardust_result *opening = NULL;
uint32_t status = stardust_db_open((stardust_bytes){(const uint8_t *)database_path, (int64_t)strlen(database_path)}, &result, &database, &opening);
stardust_result_release(opening);
stardust_db_close(database);
if (status != STARDUST_OK) return status;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 000 | 54 52 4F 4E | magic TRON |
| 004 | 6C 637265617465 | txt "create" |
| 00B | 09 | bit true |
| 00C | 0F 0A 04000000 0B00 0000 | map leaf, size 10: @4 → @B |
| 016 | 14 11 696E69746961 6C5F6D61705F6279 746573 | txt "initial_map_bytes" |
| 029 | 02 00000000000000 00 | i64 0 |
| 032 | 0F 0A 16000000 2900 0000 | map leaf, size 10: @16 → @29 |
| 03C | 7C 706C7567696E73 | txt "plugins" |
| 044 | 00 | nil |
| 045 | 0F 0A 3C000000 4400 0000 | map leaf, size 10: @3C → @44 |
| 04F | 14 13 6D656D6F7279 5F6275646765745F 6279746573 | txt "memory_budget_bytes" |
| 064 | 02 00000000000000 00 | i64 0 |
| 06D | 0F 0A 4F000000 6400 0000 | map leaf, size 10: @4F → @64 |
| 077 | CC 6C6F636B5F7469 6D656F7574 | txt "lock_timeout" |
| 084 | 02 00000000000000 00 | i64 0 |
| 08D | 0F 0A 77000000 8400 0000 | map leaf, size 10: @77 → @84 |
| 097 | 5C 636C656172 | txt "clear" |
| 09D | 01 | bit false |
| 09E | 0F 0A 97000000 9D00 0000 | map leaf, size 10: @97 → @9D |
| 0A8 | AC 70696E5F6D656D 6F7279 | txt "pin_memory" |
| 0B3 | 01 | bit false |
| 0B4 | 0F 0A A8000000 B300 0000 | map leaf, size 10: @A8 → @B3 |
| 0BE | 9C 706167655F7369 7A65 | txt "page_size" |
| 0C8 | 02 00000000000000 00 | i64 0 |
| 0D1 | 0F 0A BE000000 C800 0000 | map leaf, size 10: @BE → @C8 |
| 0DB | CC 636F6D6D69745F 6261746368 | txt "commit_batch" |
| 0E8 | 02 00000000000000 00 | i64 0 |
| 0F1 | 0F 0A DB000000 E800 0000 | map leaf, size 10: @DB → @E8 |
| 0FB | 07 12 00430000 B400 0000 D1000000 F100 0000 | map branch, size 18, depth 1, slots 8, 9, 14: @B4 → @D1 → @F1 |
| 10D | 07 22 193A0000 0C00 0000 32000000 4500 0000 6D000000 8D00 0000 9E000000 FB00 0000 | map branch, size 34, depth 0 (root), slots 0, 3, 4, 9, 11, 12, 13: @C → @32 → @45 → @6D → @8D → @9E → @FB |
| 12F | 0D010000 00000000 | root → @10D; previous: none |
Wait for the database lock without a limit
stardust_db_options result = {.size=sizeof(result), .version=1, .create=1, .page_size=0, .lock_timeout_ticks=-1};
stardust_db *database = NULL;
stardust_result *opening = NULL;
uint32_t status = stardust_db_open((stardust_bytes){(const uint8_t *)database_path, (int64_t)strlen(database_path)}, &result, &database, &opening);
stardust_result_release(opening);
stardust_db_close(database);
if (status != STARDUST_OK) return status;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 000 | 54 52 4F 4E | magic TRON |
| 004 | 6C 637265617465 | txt "create" |
| 00B | 09 | bit true |
| 00C | 0F 0A 04000000 0B00 0000 | map leaf, size 10: @4 → @B |
| 016 | 14 11 696E69746961 6C5F6D61705F6279 746573 | txt "initial_map_bytes" |
| 029 | 02 00000000000000 00 | i64 0 |
| 032 | 0F 0A 16000000 2900 0000 | map leaf, size 10: @16 → @29 |
| 03C | 7C 706C7567696E73 | txt "plugins" |
| 044 | 00 | nil |
| 045 | 0F 0A 3C000000 4400 0000 | map leaf, size 10: @3C → @44 |
| 04F | 14 13 6D656D6F7279 5F6275646765745F 6279746573 | txt "memory_budget_bytes" |
| 064 | 02 00000000000000 00 | i64 0 |
| 06D | 0F 0A 4F000000 6400 0000 | map leaf, size 10: @4F → @64 |
| 077 | CC 6C6F636B5F7469 6D656F7574 | txt "lock_timeout" |
| 084 | 00 | nil |
| 085 | 0F 0A 77000000 8400 0000 | map leaf, size 10: @77 → @84 |
| 08F | 5C 636C656172 | txt "clear" |
| 095 | 01 | bit false |
| 096 | 0F 0A 8F000000 9500 0000 | map leaf, size 10: @8F → @95 |
| 0A0 | AC 70696E5F6D656D 6F7279 | txt "pin_memory" |
| 0AB | 01 | bit false |
| 0AC | 0F 0A A0000000 AB00 0000 | map leaf, size 10: @A0 → @AB |
| 0B6 | 9C 706167655F7369 7A65 | txt "page_size" |
| 0C0 | 02 00000000000000 00 | i64 0 |
| 0C9 | 0F 0A B6000000 C000 0000 | map leaf, size 10: @B6 → @C0 |
| 0D3 | CC 636F6D6D69745F 6261746368 | txt "commit_batch" |
| 0E0 | 02 00000000000000 00 | i64 0 |
| 0E9 | 0F 0A D3000000 E000 0000 | map leaf, size 10: @D3 → @E0 |
| 0F3 | 07 12 00430000 AC00 0000 C9000000 E900 0000 | map branch, size 18, depth 1, slots 8, 9, 14: @AC → @C9 → @E9 |
| 105 | 07 22 193A0000 0C00 0000 32000000 4500 0000 6D000000 8500 0000 96000000 F300 0000 | map branch, size 34, depth 0 (root), slots 0, 3, 4, 9, 11, 12, 13: @C → @32 → @45 → @6D → @85 → @96 → @F3 |
| 127 | 05010000 00000000 | root → @105; previous: none |
Capture the host duration boundary
query_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 5C 3F6E616D65 | txt "?name" |
| 0A | 0E 0D 00 0100 010000 00 04000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4 |
| 17 | 2C 3F65 | txt "?e" |
| 1A | 4C 6E616D65 | txt "name" |
| 1F | 5C 3F6E616D65 | txt "?name" |
| 25 | 0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F |
| 3A | 0E 0D 00 0100 010000 00 25000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25 |
| 47 | 5C 3F6E616D65 | txt "?name" |
| 4D | 0E 0D 00 0100 010000 00 47000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47 |
| 5A | 5C 7768657265 | txt "where" |
| 60 | 0F 0A 5A000000 3A00 0000 | map leaf, size 10: @5A → @3A |
| 6A | 4C 66696E64 | txt "find" |
| 6F | 0F 0A 6A000000 0A00 0000 | map leaf, size 10: @6A → @A |
| 79 | 7C 6F726465724279 | txt "orderBy" |
| 81 | 0F 0A 79000000 4D00 0000 | map leaf, size 10: @79 → @4D |
| 8B | 07 12 2A000000 6000 0000 6F000000 8100 0000 | map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81 |
| 9D | 8B000000 00000000 | root → @8B; previous: none |
boundary_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 02 FFFFFFFFFFFFFF 7F | i64 9223372036854775807 |
| 0D | 04000000 00000000 | root → @4; previous: none |
stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_document *boundary = NULL;
uint32_t boundary_root = 0;
int64_t ticks = 0;
uint32_t status = stardust_parse(boundary_text, STARDUST_TRON, &boundary);
if (status == STARDUST_OK) status = stardust_document_root(boundary, &boundary_root);
if (status == STARDUST_OK) status = stardust_document_i64(boundary, boundary_root, &ticks);
stardust_document_release(boundary);
if (status == STARDUST_OK) status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query_options result = {.size=sizeof(result), .version=1, .page_size=2, .max_cost_ticks=ticks};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, &result, NULL, &rows);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 8C 6D61785F636F73 74 | txt "max_cost" |
| 0D | 02 FFFFFFFFFFFFFF 7F | i64 9223372036854775807 |
| 16 | 0F 0A 04000000 0D00 0000 | map leaf, size 10: @4 → @D |
| 20 | 5C 61735F6F66 | txt "as_of" |
| 26 | 02 00000000000000 00 | i64 0 |
| 2F | 0F 0A 20000000 2600 0000 | map leaf, size 10: @20 → @26 |
| 39 | 9C 706167655F7369 7A65 | txt "page_size" |
| 43 | 02 02000000000000 00 | i64 2 |
| 4C | 0F 0A 39000000 4300 0000 | map leaf, size 10: @39 → @43 |
| 56 | 07 12 28200000 1600 0000 2F000000 4C00 0000 | map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C |
| 68 | 56000000 00000000 | root → @56; previous: none |
The C ABI takes complete 100-ns ticks
query_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 5C 3F6E616D65 | txt "?name" |
| 0A | 0E 0D 00 0100 010000 00 04000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4 |
| 17 | 2C 3F65 | txt "?e" |
| 1A | 4C 6E616D65 | txt "name" |
| 1F | 5C 3F6E616D65 | txt "?name" |
| 25 | 0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F |
| 3A | 0E 0D 00 0100 010000 00 25000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25 |
| 47 | 5C 3F6E616D65 | txt "?name" |
| 4D | 0E 0D 00 0100 010000 00 47000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47 |
| 5A | 5C 7768657265 | txt "where" |
| 60 | 0F 0A 5A000000 3A00 0000 | map leaf, size 10: @5A → @3A |
| 6A | 4C 66696E64 | txt "find" |
| 6F | 0F 0A 6A000000 0A00 0000 | map leaf, size 10: @6A → @A |
| 79 | 7C 6F726465724279 | txt "orderBy" |
| 81 | 0F 0A 79000000 4D00 0000 | map leaf, size 10: @79 → @4D |
| 8B | 07 12 2A000000 6000 0000 6F000000 8100 0000 | map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81 |
| 9D | 8B000000 00000000 | root → @8B; previous: none |
stardust_document *definition = NULL;
stardust_db_query *query = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query_options result = {.size=sizeof(result), .version=1, .page_size=2, .max_cost_ticks=1};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 8C 6D61785F636F73 74 | txt "max_cost" |
| 0D | 02 01000000000000 00 | i64 1 |
| 16 | 0F 0A 04000000 0D00 0000 | map leaf, size 10: @4 → @D |
| 20 | 5C 61735F6F66 | txt "as_of" |
| 26 | 02 00000000000000 00 | i64 0 |
| 2F | 0F 0A 20000000 2600 0000 | map leaf, size 10: @20 → @26 |
| 39 | 9C 706167655F7369 7A65 | txt "page_size" |
| 43 | 02 02000000000000 00 | i64 2 |
| 4C | 0F 0A 39000000 4300 0000 | map leaf, size 10: @39 → @43 |
| 56 | 07 12 28200000 1600 0000 2F000000 4C00 0000 | map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C |
| 68 | 56000000 00000000 | root → @56; previous: none |
A negative configured duration is not an absent field
stardust_db_query_options result = {.size=sizeof(result), .version=1, .max_cost_ticks=-1};| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 8C 6D61785F636F73 74 | txt "max_cost" |
| 0D | 02 FFFFFFFFFFFFFF FF | i64 -1 |
| 16 | 0F 0A 04000000 0D00 0000 | map leaf, size 10: @4 → @D |
| 20 | 5C 61735F6F66 | txt "as_of" |
| 26 | 02 00000000000000 00 | i64 0 |
| 2F | 0F 0A 20000000 2600 0000 | map leaf, size 10: @20 → @26 |
| 39 | 9C 706167655F7369 7A65 | txt "page_size" |
| 43 | 02 00000000000000 00 | i64 0 |
| 4C | 0F 0A 39000000 4300 0000 | map leaf, size 10: @39 → @43 |
| 56 | 07 12 28200000 1600 0000 2F000000 4C00 0000 | map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C |
| 68 | 56000000 00000000 | root → @56; previous: none |
Run with typed query options
query_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 5C 3F6E616D65 | txt "?name" |
| 0A | 0E 0D 00 0100 010000 00 04000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4 |
| 17 | 2C 3F65 | txt "?e" |
| 1A | 4C 6E616D65 | txt "name" |
| 1F | 5C 3F6E616D65 | txt "?name" |
| 25 | 0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F |
| 3A | 0E 0D 00 0100 010000 00 25000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25 |
| 47 | 5C 3F6E616D65 | txt "?name" |
| 4D | 0E 0D 00 0100 010000 00 47000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47 |
| 5A | 5C 7768657265 | txt "where" |
| 60 | 0F 0A 5A000000 3A00 0000 | map leaf, size 10: @5A → @3A |
| 6A | 4C 66696E64 | txt "find" |
| 6F | 0F 0A 6A000000 0A00 0000 | map leaf, size 10: @6A → @A |
| 79 | 7C 6F726465724279 | txt "orderBy" |
| 81 | 0F 0A 79000000 4D00 0000 | map leaf, size 10: @79 → @4D |
| 8B | 07 12 2A000000 6000 0000 6F000000 8100 0000 | map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81 |
| 9D | 8B000000 00000000 | root → @8B; previous: none |
stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query_options result = {.size=sizeof(result), .version=1, .page_size=2, .max_cost_ticks=STARDUST_TICKS_PER_SECOND};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, &result, NULL, &rows);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 8C 6D61785F636F73 74 | txt "max_cost" |
| 0D | 02 80969800000000 00 | i64 10000000 |
| 16 | 0F 0A 04000000 0D00 0000 | map leaf, size 10: @4 → @D |
| 20 | 5C 61735F6F66 | txt "as_of" |
| 26 | 02 00000000000000 00 | i64 0 |
| 2F | 0F 0A 20000000 2600 0000 | map leaf, size 10: @20 → @26 |
| 39 | 9C 706167655F7369 7A65 | txt "page_size" |
| 43 | 02 02000000000000 00 | i64 2 |
| 4C | 0F 0A 39000000 4300 0000 | map leaf, size 10: @39 → @43 |
| 56 | 07 12 28200000 1600 0000 2F000000 4C00 0000 | map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C |
| 68 | 56000000 00000000 | root → @56; previous: none |
Read the complete initial subscription event
query_text holds this document:
| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 5C 3F6E616D65 | txt "?name" |
| 0A | 0E 0D 00 0100 010000 00 04000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4 |
| 17 | 2C 3F65 | txt "?e" |
| 1A | 4C 6E616D65 | txt "name" |
| 1F | 5C 3F6E616D65 | txt "?name" |
| 25 | 0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F |
| 3A | 0E 0D 00 0100 010000 00 25000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25 |
| 47 | 5C 3F6E616D65 | txt "?name" |
| 4D | 0E 0D 00 0100 010000 00 47000000 | array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47 |
| 5A | 5C 7768657265 | txt "where" |
| 60 | 0F 0A 5A000000 3A00 0000 | map leaf, size 10: @5A → @3A |
| 6A | 4C 66696E64 | txt "find" |
| 6F | 0F 0A 6A000000 0A00 0000 | map leaf, size 10: @6A → @A |
| 79 | 7C 6F726465724279 | txt "orderBy" |
| 81 | 0F 0A 79000000 4D00 0000 | map leaf, size 10: @79 → @4D |
| 8B | 07 12 2A000000 6000 0000 6F000000 8100 0000 | map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81 |
| 9D | 8B000000 00000000 | root → @8B; previous: none |
stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_subscription *subscription = NULL;
stardust_db_live_event event = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_subscribe(query, NULL, NULL, &subscription);
if (status == STARDUST_OK) status = stardust_db_subscription_next(subscription, 0, &event);
stardust_db_subscription_release(subscription);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(event.result); return status;}
stardust_db_live_event result = event;| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 4C 6E616D65 | txt "name" |
| 09 | 3C 416461 | txt "Ada" |
| 0D | 0F 0A 04000000 0900 0000 | map leaf, size 10: @4 → @9 |
| 17 | 4C 6E616D65 | txt "name" |
| 1C | 3C 426F62 | txt "Bob" |
| 20 | 0F 0A 17000000 1C00 0000 | map leaf, size 10: @17 → @1C |
| 2A | 4C 6E616D65 | txt "name" |
| 2F | 2C 4379 | txt "Cy" |
| 32 | 0F 0A 2A000000 2F00 0000 | map leaf, size 10: @2A → @2F |
| 3C | 0E 15 00 0700 030000 00 0D000000 200000 00 32000000 | array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32 |
| 51 | AC 73757065727365 646564 | txt "superseded" |
| 5C | 02 00000000000000 00 | i64 0 |
| 65 | 0F 0A 51000000 5C00 0000 | map leaf, size 10: @51 → @5C |
| 6F | BC 7472616E736163 74696F6E | txt "transaction" |
| 7B | 02 04000000000000 00 | i64 4 |
| 84 | 0F 0A 6F000000 7B00 0000 | map leaf, size 10: @6F → @7B |
| 8E | 6C 726573756C74 | txt "result" |
| 95 | 0F 0A 8E000000 3C00 0000 | map leaf, size 10: @8E → @3C |
| 9F | 8C 73657175656E63 65 | txt "sequence" |
| A8 | 02 01000000000000 00 | i64 1 |
| B1 | 0F 0A 9F000000 A800 0000 | map leaf, size 10: @9F → @A8 |
| BB | 07 16 00330000 6500 0000 84000000 9500 0000 B1000000 | map branch, size 22, depth 0 (root), slots 8, 9, 12, 13: @65 → @84 → @95 → @B1 |
| D1 | BB000000 00000000 | root → @BB; previous: none |