Lite³
A JSON-Compatible Zero-Copy Serialization Format
Loading...
Searching...
No Matches
Nesting

Table of Contents

Introduction

The previous guide was about strings. This guide will explain nested structures (object hierarchies).

Nesting allows applications to represent complex relationships that would be difficult to represent with only flat datastructures.

Example Code

This guide is based on an example inside the Lite³ repository found in examples/context_api/04-nesting.c:

1/*
2 Lite³: A JSON-Compatible Zero-Copy Serialization Format
3
4 Copyright © 2025 Elias de Jong <elias@fastserial.com>
5
6 Permission is hereby granted, free of charge, to any person obtaining a copy
7 of this software and associated documentation files (the "Software"), to deal
8 in the Software without restriction, including without limitation the rights
9 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 copies of the Software, and to permit persons to whom the Software is
11 furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included in all
14 copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 SOFTWARE.
23
24 __ __________________ ____
25 _ ___ ___/ /___(_)_/ /_______|_ /
26 _ _____/ / __/ /_ __/ _ \_/_ <
27 ___ __/ /___/ / / /_ / __/____/
28 /_____/_/ \__/ \___/
29*/
30#include <stdio.h>
31#include <string.h>
32
33#include "lite3_context_api.h"
34
35
36int main() {
37 lite3_ctx *ctx = lite3_ctx_create();
38 if (!ctx) {
39 perror("Failed to create lite3_ctx *ctx");
40 return 1;
41 }
42
43 // Build message
44 if (lite3_ctx_init_obj(ctx) < 0
45 || lite3_ctx_set_str(ctx, 0, "event", "http_request") < 0
46 || lite3_ctx_set_str(ctx, 0, "method", "POST") < 0
47 || lite3_ctx_set_i64(ctx, 0, "duration_ms", 47) < 0) {
48 perror("Failed to build message");
49 return 1;
50 }
51 // Set headers
52 size_t headers_ofs;
53 if (lite3_ctx_set_obj(ctx, 0, "headers", &headers_ofs) < 0
54 || lite3_ctx_set_str(ctx, headers_ofs, "content-type", "application/json") < 0
55 || lite3_ctx_set_str(ctx, headers_ofs, "x-request-id", "req_9f8e2a") < 0
56 || lite3_ctx_set_str(ctx, headers_ofs, "user-agent", "curl/8.1.2") < 0) {
57 perror("Failed to set headers");
58 return 1;
59 }
60
61 if (lite3_ctx_json_print(ctx, 0) < 0) { // Print Lite³ as JSON
62 perror("Failed to print JSON");
63 return 1;
64 }
65
66 // Get user-agent
67 lite3_str user_agent;
68 size_t ofs;
69 if (lite3_ctx_get_obj(ctx, 0, "headers", &ofs) < 0
70 || lite3_ctx_get_str(ctx, ofs, "user-agent", &user_agent) < 0) {
71 perror("Failed to get user-agent");
72 return 1;
73 }
74 printf("User agent: %s\n", LITE3_STR(ctx->buf, user_agent));
75
76 lite3_ctx_destroy(ctx);
77 return 0;
78}
lite3_ctx_get_str
#define lite3_ctx_get_str(ctx, ofs, key, out)
Get string value by key.
Definition lite3_context_api.h:1725
lite3_ctx_get_obj
#define lite3_ctx_get_obj(ctx, ofs, key, out)
Get object by key.
Definition lite3_context_api.h:1765
lite3_ctx_init_obj
static int lite3_ctx_init_obj(lite3_ctx *ctx)
Initialize a Lite³ context as an object.
Definition lite3_context_api.h:273
lite3_ctx_json_print
static int lite3_ctx_json_print(lite3_ctx *ctx, size_t ofs)
Print Lite³ buffer as JSON to stdout
Definition lite3_context_api.h:2217
lite3_ctx_create
static lite3_ctx * lite3_ctx_create(void)
Create context with minimum size.
Definition lite3_context_api.h:214
lite3_ctx_destroy
void lite3_ctx_destroy(lite3_ctx *ctx)
Destroy context.
Definition ctx_api.c:229
lite3_ctx_set_obj
#define lite3_ctx_set_obj(ctx, ofs, key, out_ofs)
Set object in object.
Definition lite3_context_api.h:596
lite3_ctx_set_i64
#define lite3_ctx_set_i64(ctx, ofs, key, value)
Set integer in object.
Definition lite3_context_api.h:401
lite3_ctx_set_str
#define lite3_ctx_set_str(ctx, ofs, key, str)
Set string in object.
Definition lite3_context_api.h:515
LITE3_STR
#define LITE3_STR(buf, val)
Generational pointer / safe access wrapper.
Definition lite3.h:666
lite3_context_api.h
Lite³ Context API Header.
lite3_ctx
Lite³ context struct.
Definition lite3_context_api.h:140
lite3_str
Struct holding a reference to a string inside a Lite³ buffer.
Definition lite3.h:601

Output:

{
"method": "POST",
"event": "http_request",
"duration_ms": 47,
"headers": {
"user-agent": "curl/8.1.2",
"x-request-id": "req_9f8e2a",
"content-type": "application/json"
}
}
User agent: curl/8.1.2

Explanation

We will walk through the example code step-by-step, explaining the use of Lite³ library functions.

Lite³ messages are just bytes, stored contiguously inside a buffer. If you want to allocate these messages inside your own custom allocators, you can using the Buffer API. However in this guide, we will be using the Context API so that memory is managed automatically.

Note that Lite³ is a binary format, but the examples print message data as JSON to stdout for better readability.

Building the message

As explained in the first guide, we use contexts to store Lite³ buffers (see: Context API):

lite3_ctx *ctx = lite3_ctx_create();
if (!ctx) {
perror("Failed to create lite3_ctx *ctx");
return 1;
}

We then insert the first part of the message:

// Build message
if (lite3_ctx_init_obj(ctx) < 0
|| lite3_ctx_set_str(ctx, 0, "event", "http_request") < 0
|| lite3_ctx_set_str(ctx, 0, "method", "POST") < 0
|| lite3_ctx_set_i64(ctx, 0, "duration_ms", 47) < 0) {
perror("Failed to build message");
return 1;
}

Which at this point would look like this:

{
"method": "POST",
"event": "http_request",
"duration_ms": 47
}

Nested insertion

But now we will insert for the first time a nested object:

// Set headers
size_t headers_ofs;
if (lite3_ctx_set_obj(ctx, 0, "headers", &headers_ofs) < 0
|| lite3_ctx_set_str(ctx, headers_ofs, "content-type", "application/json") < 0
|| lite3_ctx_set_str(ctx, headers_ofs, "x-request-id", "req_9f8e2a") < 0
|| lite3_ctx_set_str(ctx, headers_ofs, "user-agent", "curl/8.1.2") < 0) {
perror("Failed to set headers");
return 1;
}

To make the complete message look like this:

{
"method": "POST",
"event": "http_request",
"duration_ms": 47,
"headers": {
"user-agent": "curl/8.1.2",
"x-request-id": "req_9f8e2a",
"content-type": "application/json"
}
}

Let's focus on the critical components here:

size_t headers_ofs;
lite3_ctx_set_obj(ctx, 0, "headers", &headers_ofs);
lite3_ctx_set_str(ctx, headers_ofs, "content-type", "application/json");

Almost all Lite³ functions have these two as their first parameters:

  1. First parameter (ctx): a pointer pointing to the context storing the current message that we are reading from or inserting into.
  2. Second parameter (ofs): the 'offset' of the target object/array.

Any read or write operation on a Lite³ message must always target an object or array. This is because data will always be contained in one of those types. Recall that the JSON standard requires that the root-level always be an array or object. This also applies to Lite³, since Lite³ is JSON-compatible.

Lite³ always stores the root object/array at the start of the buffer. Therefore, if we want to access the root-level object/array, we simply pass 0 (zero-index). If we want to target a nested (internal) object, we need to pass the offset at which it is located inside the buffer.

How do we know at what offset the internal object is located?

Conveniently, whenever we insert an object, this offset is written back via the out parameter *out_ofs (the last parameter):

size_t headers_ofs;
lite3_ctx_set_obj(ctx, 0, "headers", &headers_ofs);
Note
If you don't want to receive this offset, perhaps because you just want to insert an empty object, you can also pass NULL:
lite3_ctx_set_obj(ctx, 0, "headers", NULL);

The new object is empty. So to target it for insertion, we pass the offset of the "headers" object as the 2nd parameter:

lite3_ctx_set_str(ctx, headers_ofs, "content-type", "application/json");

One nice feature of this offset mechanism is that it provides constant-time access to any internal object, regardless of nesting hierarchy. This is because no matter how deep the 'logical' document hierarchy is, at the end of the day, it will be located somewhere inside the buffer, at some offset. To find an internal object, you may have to traverse some hierarchies. But once found, the offset can be stored for later. It is then possible to target many read/write operations on this object without 'repaying' the traversing cost.

Nested lookup

After the previous explanation, the reading example should speak for itself:

// Get user-agent
lite3_str user_agent;
size_t ofs;
if (lite3_ctx_get_obj(ctx, 0, "headers", &ofs) < 0
|| lite3_ctx_get_str(ctx, ofs, "user-agent", &user_agent) < 0) {
perror("Failed to get user-agent");
return 1;
}
printf("User agent: %s\n", LITE3_STR(ctx->buf, user_agent));

Output:

User agent: curl/8.1.2

Again, the 2nd parameter is used to target the internal object. First obtain the offset, then use it to perform lookups.

Cleaning up

We are good citizens, so we clean up after ourselves:

lite3_ctx_destroy(ctx);

This destroys the context, freeing all the internal buffers so that the memory is released. When you create contexts, don't forget to destroy them, or else you will be leaking memory.

Conclusion

This was the fourth guide showing nested structures.

The next guide will be about arrays: Next Guide: Arrays