Json

The error's path in jsonpath form, as jsonb_path_query takes it: $ for the document itself, $.address.tags[2], and a key that is not a plain identifier quoted: $."we ird". Allocated with the temporary allocator.

Item :: struct { tags: [..] string; }

_, error := from_json(Item, "{\"tags\": [\"a\", 2]}");
assert(json_path_text(error) == "$.tags[1]");
free_json(*error);

The error as one line: message at line 3, column 5 (tags[2]).

_, error := from_json(s64, "x");
text := error_text(error);
assert(text.count > 0);
free_json(*error);

Releases the message and path of an error and clears it.

Encodes value. Output is compact unless pretty (two-space indent). The result comes from context.allocator.

Point :: struct { x: int; y: int; }

text := to_json(Point.{ 1, 2 });
assert(text == "{\"x\":1,\"y\":2}");
free(text);

Like to_json, appending to a String_Builder instead of allocating a string.

builder: String_Builder;
write_json(*builder, s32.[1, 2, 3]);
assert(builder_to_string(*builder,, temp) == "[1,2,3]");

Decodes a T from a source in pieces. The pieces are gathered in one buffer (the decoder wants the whole document, and its strings are copied out of it, so the buffer is freed before this returns) and then decoded exactly as from_json(T, text) would, so a document split at any byte gives the same value or the same error. A source that fails gives a .READ error with the source's text; a document longer than options.max_size is a .LIMIT error and the rest is not read.

Chunks :: struct { parts: [] string; next: int; }

fill :: (data: *void, buffer: [] u8) -> s64, string {
    chunks := cast(*Chunks) data;
    if chunks.next >= chunks.parts.count return 0, "";
    part := chunks.parts[chunks.next];
    chunks.next += 1;
    memcpy(buffer.data, part.data, part.count);
    return part.count, "";
}

chunks := Chunks.{ parts = .["[1, ", "2, 3]"] };
numbers, error := from_json([] s64, Json_Source.{ *chunks, fill });
assert(error.kind == .NONE && numbers.count == 3);
free_json(*numbers);

Writes the JSON of the value value points to to the writer w. This and json_decode are what with= handlers call for the parts they do not encode themselves.

Price :: struct {
    cents: s64; @json(with=dollars)

    dollars_encode :: (w: *Json_Writer, value: *s64) {
        json_write_float64(w, cast(float64) value.* / 100.0);
    }

    dollars_decode :: (r: *Json_Reader, out: *s64) -> bool {
        dollars: float64;
        if !json_read_float64(r, *dollars) return false;
        out.* = cast(s64) (dollars * 100.0 + 0.5);
        return true;
    }
}

assert(to_json(Price.{ 1250 }) == "{\"cents\":12.5}");
price, _ := from_json(Price, "{\"cents\": 3.25}");
assert(price.cents == 325);

Reads a T into out from the reader r; false after recording an error. See json_encode.

A JSON null.

A JSON true or false.

A JSON number from a signed integer.

A JSON number from an unsigned integer.

NaN and infinities have no JSON spelling and become null.

assert(json_float(1.5).text == "1.5");
zero := 0.0;
assert(json_float(zero / zero).kind == .NULL);

A JSON string. The string is copied.

v := json_string("hi");
text, ok := json_as_string(*v);
assert(ok && text == "hi");
free_json(*v);

An empty JSON array; fill it with json_push.

An empty JSON object; fill it with json_set.

Appends to an array; array takes ownership of item.

list := json_array();
json_push(*list, json_bool(true));
assert(json_count(*list) == 1);
free_json(*list);

Sets a member of an object, replacing the last member with that key; object takes ownership of value and copies key.

object := json_object();
json_set(*object, "n", json_int(1));
json_set(*object, "n", json_int(2));
assert(json_count(*object) == 1);
free_json(*object);

The member key of an object (the last one, if the key repeats), or null.

object, _ := from_json(Json_Value, "{\"n\": 5}");
n := json_get(*object, "n");
value, ok := json_as_s64(n);
assert(ok && value == 5);
assert(json_get(*object, "missing") == null);
free_json(*object);

Element index of an array, or null.

list, _ := from_json(Json_Value, "[10, 20]");
second, _ := json_as_s64(json_at(*list, 1));
assert(second == 20);
assert(json_at(*list, 2) == null);
free_json(*list);

How many elements an array has, or members an object has; 0 for anything else.

list, _ := from_json(Json_Value, "[1, 2, 3]");
assert(json_count(*list) == 3);
free_json(*list);

A number that is written as an integer and fits. False for anything else.

n, _ := from_json(Json_Value, "42");
value, ok := json_as_s64(*n);
assert(ok && value == 42);

fraction, _ := from_json(Json_Value, "4.5");
_, ok = json_as_s64(*fraction);
assert(!ok);
free_json(*n);
free_json(*fraction);

The same as json_as_s64, for an unsigned integer.

Any number, rounded to the nearest float64. False if it is not a number or is too large.

n, _ := from_json(Json_Value, "4.5");
value, ok := json_as_float64(*n);
assert(ok && value == 4.5);
free_json(*n);

The boolean and true, or false and false when the value is not a boolean.

The text and true, or "" and false when the value is not a string. The text belongs to the value.

Appends text as a JSON string with its quotes. Control characters, quotes and backslashes are escaped; bytes that are not valid UTF-8 become U+FFFD so the output is always valid JSON.

Writes null.

Writes true or false.

Writes an unsigned integer.

Writes a signed integer.

Writes a float64; NaN and infinities have no JSON spelling and are written as null.

Writes a float32, like json_write_float64.

Writes a quoted, escaped string.

Appends text that is already JSON, as is.

{. Pair it with json_end_object and put a json_key before each member.

}, on a line of its own when pretty-printing. empty is true when no member was written.

[. Pair it with json_end_array and call json_item before each element.

], on a line of its own when pretty-printing. empty is true when no element was written.

Starts a member: the separator, then the key. quoted_key is the key with its quotes and escapes already applied (the generated code does that at compile time).

json_key with the compact forms prebuilt at compile time: first_form is "key": and next_form is ,"key":, so compact output costs one append.

A member whose key is only known at run time (a Hash_Table's).

Starts an array element.

Writes a Json_Value.

Records an error at the current position (when there is none yet) and returns false.

Like json_fail, at the byte offset.

Say the value being read is at key / index of its parent. The generated decoders call these while an error travels up, so the error's path reads address.tags[2].

Like json_path_key, for an array element.

The next significant byte (0 at the end of the input).

Records a duplicate-field error for key.

Records an unknown-field error for key.

Records a missing-field error for key.

Reads up to the next member of the object: its key (valid until the next read) and the colon after it, or the closing brace. first is true before the first call.

Moves to the next element of the array: .ITEM with the reader at its value, or .END. first is true before the first call.

A string value, copied into new memory from context.allocator (with borrow, a slice of the input when it has no escapes).

A string value without copying: a view of the input, or of the reader's scratch space when it has escapes. Valid until the next read; copy it to keep it.

Keeps a key from json_read_name: a slice of the input with borrow (unless it had escapes and lives in the scratch space), else a copy.

Reads true or false.

Whether the next value is null, without consuming it.

Consumes a null.

Reads an integer into out, which must fit between low and high. type_name appears in the message when it does not.

Like json_read_signed, for an unsigned integer up to high.

Reads any number into a float64.

Reads any number into a float32.

Checks the next value and moves past it without keeping anything.

Reads any value into a Json_Value. On failure out holds what was read so far, and free_json releases it.

Decodes a T from pairs. A key that repeats gives an array for an array field, and is a "duplicate field" error for any other. Keys no field has are ignored unless T is marked deny_unknown_fields. Everything allocated (strings, arrays) comes from context.allocator and is released by free_json, as for from_json.

Search :: struct @json(default) { q: string; limit := 20; tags: [..] string; }

// The pairs of "?q=jai&tags=a&tags=b".
pairs := Query_Pair.[.{"q", "jai"}, .{"tags", "a"}, .{"tags", "b"}];
search, error := from_query(Search, pairs);

assert(error.kind == .NONE);
assert(search.q == "jai");
assert(search.limit == 20);
assert(search.tags.count == 2);

Decodes a T from one piece of text: an integer, float, bool, string or enum. from_param(int, "42") is 42; from_param(Color, "red") the member red; a string is taken as it is.

number, error := from_param(int, "42");
assert(error.kind == .NONE && number == 42);

_, error = from_param(int, "forty-two");
assert(error.kind != .NONE);
free_json(*error);

Why decoding failed.

Why decoding failed and where. path names the value inside the document (tags[2], address.zip); line and column count from 1, the column in characters. message and path are allocated with context.allocator: free_json releases them.

_, error := from_json([] s64, "[1, 2");
assert(error.kind == .SYNTAX && error.line == 1);
free_json(*error);

What a repeated key in an object does; see Json_Options.

Limits and strictness for from_json.

Point :: struct { x: int; y: int; }

options: Json_Options;
options.deny_unknown_fields = true;
_, error := from_json(Point, "{\"x\": 1, \"y\": 2, \"z\": 3}", options);
assert(error.kind == .UNKNOWN_FIELD);
free_json(*error);

A field that distinguishes a key that is missing, a null and a value. As a struct member a missing key leaves .MISSING (never a missing-field error), null gives .NULL and any other value decodes into value and gives .SET. Encoding omits the key for .MISSING, writes null for .NULL and the value for .SET. Outside a struct member (the document, an array element) .MISSING encodes as null. free_json releases value when it is .SET.

A member type for a field that may be absent: it holds a Json_Presence and the value.

Patch :: struct { name: Json_Maybe(string); }

missing, _ := from_json(Patch, "{}");
assert(missing.name.state == .MISSING);

cleared, _ := from_json(Patch, "{\"name\": null}");
assert(cleared.name.state == .NULL);

renamed, _ := from_json(Patch, "{\"name\": \"Ada\"}");
assert(renamed.name.state == .SET && renamed.name.value == "Ada");
free_json(*renamed);

How the structural index fared since the program began, for tests and curiosity.

Where a document comes from when it is not in memory yet: fill puts the next piece of text in buffer and returns how many bytes it wrote (0 at the end), and a non-empty string when the source failed (what went wrong). data is handed to it as it is. Json does not know what the pieces come from; Io.read_json makes one from an Io.Reader.

A document that arrives in pieces; see Json_Fill.

What a Json_Value holds.

One JSON value. Only the fields of its kind are used: BOOL boolean NUMBER text, the number as written (exact for integers of any size; see json_as_s64) STRING text, the contents with escapes resolved ARRAY items OBJECT members, in document order (duplicate keys are kept; json_get finds the last) Everything a Json_Value owns comes from context.allocator; free_json releases it.

doc := json_object();
json_set(*doc, "name", json_string("Ada"));
tags := json_array();
json_push(*tags, json_int(1));
json_set(*doc, "tags", tags);

text := to_json(doc);
assert(text == "{\"name\":\"Ada\",\"tags\":[1]}");
free(text);
free_json(*doc);

One key: value of an object.

Where an encoder writes: the builder, whether to indent, and the nesting depth. Set builder (and pretty) and pass it to json_encode.

Reads one JSON document. Every reading procedure returns false after recording an error in error; the first error wins, and callers must stop at once and return false themselves.

What json_object_next found: a key, the end of the object, or an error.

What json_array_next found: an item, the end of the array, or an error.

One key=value of a query or a form, already percent-decoded.