Type Function WriteStream [src]
Alias for std.json.stringify.WriteStream
Writes JSON (RFC8259) formatted data
to a stream.
The sequence of method calls to write JSON content must follow this grammar:
=
=
|
Prototype
pub fn WriteStream( comptime OutStream: type, comptime safety_checks_hint: union(enum) { checked_to_arbitrary_depth, checked_to_fixed_depth: usize,assumed_correct, }, ) type Parameters
OutStream: typesafety_checks_hint: union(enum) {
checked_to_arbitrary_depth,
checked_to_fixed_depth: usize, // Rounded up to the nearest multiple of 8.
assumed_correct,
} Source
pub fn WriteStream(
comptime OutStream: type,
comptime safety_checks_hint: union(enum) {
checked_to_arbitrary_depth,
checked_to_fixed_depth: usize, // Rounded up to the nearest multiple of 8.
assumed_correct,
},
) type {
return struct {
const Self = @This();
const build_mode_has_safety = switch (@import("builtin").mode) {
.Debug, .ReleaseSafe => true,
.ReleaseFast, .ReleaseSmall => false,
};
const safety_checks: @TypeOf(safety_checks_hint) = if (build_mode_has_safety)
safety_checks_hint
else
.assumed_correct;
pub const Stream = OutStream;
pub const Error = switch (safety_checks) {
.checked_to_arbitrary_depth => Stream.Error || error{OutOfMemory},
.checked_to_fixed_depth, .assumed_correct => Stream.Error,
};
options: StringifyOptions,
stream: OutStream,
indent_level: usize = 0,
next_punctuation: enum {
the_beginning,
none,
comma,
colon,
} = .the_beginning,
nesting_stack: switch (safety_checks) {
.checked_to_arbitrary_depth => BitStack,
.checked_to_fixed_depth => |fixed_buffer_size| [(fixed_buffer_size + 7) >> 3]u8,
.assumed_correct => void,
},
raw_streaming_mode: if (build_mode_has_safety)
enum { none, value, objectField }
else
void = if (build_mode_has_safety) .none else {},
pub fn init(safety_allocator: Allocator, stream: OutStream, options: StringifyOptions) Self {
return .{
.options = options,
.stream = stream,
.nesting_stack = switch (safety_checks) {
.checked_to_arbitrary_depth => BitStack.init(safety_allocator),
.checked_to_fixed_depth => |fixed_buffer_size| [_]u8{0} ** ((fixed_buffer_size + 7) >> 3),
.assumed_correct => {},
},
};
}
/// Only necessary with .checked_to_arbitrary_depth.
pub fn deinit(self: *Self) void {
switch (safety_checks) {
.checked_to_arbitrary_depth => self.nesting_stack.deinit(),
.checked_to_fixed_depth, .assumed_correct => {},
}
self.* = undefined;
}
pub fn beginArray(self: *Self) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
try self.valueStart();
try self.stream.writeByte('[');
try self.pushIndentation(ARRAY_MODE);
self.next_punctuation = .none;
}
pub fn beginObject(self: *Self) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
try self.valueStart();
try self.stream.writeByte('{');
try self.pushIndentation(OBJECT_MODE);
self.next_punctuation = .none;
}
pub fn endArray(self: *Self) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
self.popIndentation(ARRAY_MODE);
switch (self.next_punctuation) {
.none => {},
.comma => {
try self.indent();
},
.the_beginning, .colon => unreachable,
}
try self.stream.writeByte(']');
self.valueDone();
}
pub fn endObject(self: *Self) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
self.popIndentation(OBJECT_MODE);
switch (self.next_punctuation) {
.none => {},
.comma => {
try self.indent();
},
.the_beginning, .colon => unreachable,
}
try self.stream.writeByte('}');
self.valueDone();
}
fn pushIndentation(self: *Self, mode: u1) !void {
switch (safety_checks) {
.checked_to_arbitrary_depth => {
try self.nesting_stack.push(mode);
self.indent_level += 1;
},
.checked_to_fixed_depth => {
BitStack.pushWithStateAssumeCapacity(&self.nesting_stack, &self.indent_level, mode);
},
.assumed_correct => {
self.indent_level += 1;
},
}
}
fn popIndentation(self: *Self, assert_its_this_one: u1) void {
switch (safety_checks) {
.checked_to_arbitrary_depth => {
assert(self.nesting_stack.pop() == assert_its_this_one);
self.indent_level -= 1;
},
.checked_to_fixed_depth => {
assert(BitStack.popWithState(&self.nesting_stack, &self.indent_level) == assert_its_this_one);
},
.assumed_correct => {
self.indent_level -= 1;
},
}
}
fn indent(self: *Self) !void {
var char: u8 = ' ';
const n_chars = switch (self.options.whitespace) {
.minified => return,
.indent_1 => 1 * self.indent_level,
.indent_2 => 2 * self.indent_level,
.indent_3 => 3 * self.indent_level,
.indent_4 => 4 * self.indent_level,
.indent_8 => 8 * self.indent_level,
.indent_tab => blk: {
char = '\t';
break :blk self.indent_level;
},
};
try self.stream.writeByte('\n');
try self.stream.writeByteNTimes(char, n_chars);
}
fn valueStart(self: *Self) !void {
if (self.isObjectKeyExpected()) |is_it| assert(!is_it); // Call objectField*(), not write(), for object keys.
return self.valueStartAssumeTypeOk();
}
fn objectFieldStart(self: *Self) !void {
if (self.isObjectKeyExpected()) |is_it| assert(is_it); // Expected write(), not objectField*().
return self.valueStartAssumeTypeOk();
}
fn valueStartAssumeTypeOk(self: *Self) !void {
assert(!self.isComplete()); // JSON document already complete.
switch (self.next_punctuation) {
.the_beginning => {
// No indentation for the very beginning.
},
.none => {
// First item in a container.
try self.indent();
},
.comma => {
// Subsequent item in a container.
try self.stream.writeByte(',');
try self.indent();
},
.colon => {
try self.stream.writeByte(':');
if (self.options.whitespace != .minified) {
try self.stream.writeByte(' ');
}
},
}
}
fn valueDone(self: *Self) void {
self.next_punctuation = .comma;
}
// Only when safety is enabled:
fn isObjectKeyExpected(self: *const Self) ?bool {
switch (safety_checks) {
.checked_to_arbitrary_depth => return self.indent_level > 0 and
self.nesting_stack.peek() == OBJECT_MODE and
self.next_punctuation != .colon,
.checked_to_fixed_depth => return self.indent_level > 0 and
BitStack.peekWithState(&self.nesting_stack, self.indent_level) == OBJECT_MODE and
self.next_punctuation != .colon,
.assumed_correct => return null,
}
}
fn isComplete(self: *const Self) bool {
return self.indent_level == 0 and self.next_punctuation == .comma;
}
/// An alternative to calling `write` that formats a value with `std.fmt`.
/// This function does the usual punctuation and indentation formatting
/// assuming the resulting formatted string represents a single complete value;
/// e.g. `"1"`, `"[]"`, `"[1,2]"`, not `"1,2"`.
/// This function may be useful for doing your own number formatting.
pub fn print(self: *Self, comptime fmt: []const u8, args: anytype) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
try self.valueStart();
try self.stream.print(fmt, args);
self.valueDone();
}
/// An alternative to calling `write` that allows you to write directly to the `.stream` field, e.g. with `.stream.writeAll()`.
/// Call `beginWriteRaw()`, then write a complete value (including any quotes if necessary) directly to the `.stream` field,
/// then call `endWriteRaw()`.
/// This can be useful for streaming very long strings into the output without needing it all buffered in memory.
pub fn beginWriteRaw(self: *Self) !void {
if (build_mode_has_safety) {
assert(self.raw_streaming_mode == .none);
self.raw_streaming_mode = .value;
}
try self.valueStart();
}
/// See `beginWriteRaw`.
pub fn endWriteRaw(self: *Self) void {
if (build_mode_has_safety) {
assert(self.raw_streaming_mode == .value);
self.raw_streaming_mode = .none;
}
self.valueDone();
}
/// See `WriteStream` for when to call this method.
/// `key` is the string content of the property name.
/// Surrounding quotes will be added and any special characters will be escaped.
/// See also `objectFieldRaw`.
pub fn objectField(self: *Self, key: []const u8) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
try self.objectFieldStart();
try encodeJsonString(key, self.options, self.stream);
self.next_punctuation = .colon;
}
/// See `WriteStream` for when to call this method.
/// `quoted_key` is the complete bytes of the key including quotes and any necessary escape sequences.
/// A few assertions are performed on the given value to ensure that the caller of this function understands the API contract.
/// See also `objectField`.
pub fn objectFieldRaw(self: *Self, quoted_key: []const u8) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
assert(quoted_key.len >= 2 and quoted_key[0] == '"' and quoted_key[quoted_key.len - 1] == '"'); // quoted_key should be "quoted".
try self.objectFieldStart();
try self.stream.writeAll(quoted_key);
self.next_punctuation = .colon;
}
/// In the rare case that you need to write very long object field names,
/// this is an alternative to `objectField` and `objectFieldRaw` that allows you to write directly to the `.stream` field
/// similar to `beginWriteRaw`.
/// Call `endObjectFieldRaw()` when you're done.
pub fn beginObjectFieldRaw(self: *Self) !void {
if (build_mode_has_safety) {
assert(self.raw_streaming_mode == .none);
self.raw_streaming_mode = .objectField;
}
try self.objectFieldStart();
}
/// See `beginObjectFieldRaw`.
pub fn endObjectFieldRaw(self: *Self) void {
if (build_mode_has_safety) {
assert(self.raw_streaming_mode == .objectField);
self.raw_streaming_mode = .none;
}
self.next_punctuation = .colon;
}
/// Renders the given Zig value as JSON.
///
/// Supported types:
/// * Zig `bool` -> JSON `true` or `false`.
/// * Zig `?T` -> `null` or the rendering of `T`.
/// * Zig `i32`, `u64`, etc. -> JSON number or string.
/// * When option `emit_nonportable_numbers_as_strings` is true, if the value is outside the range `+-1<<53` (the precise integer range of f64), it is rendered as a JSON string in base 10. Otherwise, it is rendered as JSON number.
/// * Zig floats -> JSON number or string.
/// * If the value cannot be precisely represented by an f64, it is rendered as a JSON string. Otherwise, it is rendered as JSON number.
/// * TODO: Float rendering will likely change in the future, e.g. to remove the unnecessary "e+00".
/// * Zig `[]const u8`, `[]u8`, `*[N]u8`, `@Vector(N, u8)`, and similar -> JSON string.
/// * See `StringifyOptions.emit_strings_as_arrays`.
/// * If the content is not valid UTF-8, rendered as an array of numbers instead.
/// * Zig `[]T`, `[N]T`, `*[N]T`, `@Vector(N, T)`, and similar -> JSON array of the rendering of each item.
/// * Zig tuple -> JSON array of the rendering of each item.
/// * Zig `struct` -> JSON object with each field in declaration order.
/// * If the struct declares a method `pub fn jsonStringify(self: *@This(), jw: anytype) !void`, it is called to do the serialization instead of the default behavior. The given `jw` is a pointer to this `WriteStream`. See `std.json.Value` for an example.
/// * See `StringifyOptions.emit_null_optional_fields`.
/// * Zig `union(enum)` -> JSON object with one field named for the active tag and a value representing the payload.
/// * If the payload is `void`, then the emitted value is `{}`.
/// * If the union declares a method `pub fn jsonStringify(self: *@This(), jw: anytype) !void`, it is called to do the serialization instead of the default behavior. The given `jw` is a pointer to this `WriteStream`.
/// * Zig `enum` -> JSON string naming the active tag.
/// * If the enum declares a method `pub fn jsonStringify(self: *@This(), jw: anytype) !void`, it is called to do the serialization instead of the default behavior. The given `jw` is a pointer to this `WriteStream`.
/// * If the enum is non-exhaustive, unnamed values are rendered as integers.
/// * Zig untyped enum literal -> JSON string naming the active tag.
/// * Zig error -> JSON string naming the error.
/// * Zig `*T` -> the rendering of `T`. Note there is no guard against circular-reference infinite recursion.
///
/// See also alternative functions `print` and `beginWriteRaw`.
/// For writing object field names, use `objectField` instead.
pub fn write(self: *Self, value: anytype) Error!void {
if (build_mode_has_safety) assert(self.raw_streaming_mode == .none);
const T = @TypeOf(value);
switch (@typeInfo(T)) {
.int => {
try self.valueStart();
if (self.options.emit_nonportable_numbers_as_strings and
(value <= -(1 << 53) or value >= (1 << 53)))
{
try self.stream.print("\"{}\"", .{value});
} else {
try self.stream.print("{}", .{value});
}
self.valueDone();
return;
},
.comptime_int => {
return self.write(@as(std.math.IntFittingRange(value, value), value));
},
.float, .comptime_float => {
if (@as(f64, @floatCast(value)) == value) {
try self.valueStart();
try self.stream.print("{}", .{@as(f64, @floatCast(value))});
self.valueDone();
return;
}
try self.valueStart();
try self.stream.print("\"{}\"", .{value});
self.valueDone();
return;
},
.bool => {
try self.valueStart();
try self.stream.writeAll(if (value) "true" else "false");
self.valueDone();
return;
},
.null => {
try self.valueStart();
try self.stream.writeAll("null");
self.valueDone();
return;
},
.optional => {
if (value) |payload| {
return try self.write(payload);
} else {
return try self.write(null);
}
},
.@"enum" => |enum_info| {
if (std.meta.hasFn(T, "jsonStringify")) {
return value.jsonStringify(self);
}
if (!enum_info.is_exhaustive) {
inline for (enum_info.fields) |field| {
if (value == @field(T, field.name)) {
break;
}
} else {
return self.write(@intFromEnum(value));
}
}
return self.stringValue(@tagName(value));
},
.enum_literal => {
return self.stringValue(@tagName(value));
},
.@"union" => {
if (std.meta.hasFn(T, "jsonStringify")) {
return value.jsonStringify(self);
}
const info = @typeInfo(T).@"union";
if (info.tag_type) |UnionTagType| {
try self.beginObject();
inline for (info.fields) |u_field| {
if (value == @field(UnionTagType, u_field.name)) {
try self.objectField(u_field.name);
if (u_field.type == void) {
// void value is {}
try self.beginObject();
try self.endObject();
} else {
try self.write(@field(value, u_field.name));
}
break;
}
} else {
unreachable; // No active tag?
}
try self.endObject();
return;
} else {
@compileError("Unable to stringify untagged union '" ++ @typeName(T) ++ "'");
}
},
.@"struct" => |S| {
if (std.meta.hasFn(T, "jsonStringify")) {
return value.jsonStringify(self);
}
if (S.is_tuple) {
try self.beginArray();
} else {
try self.beginObject();
}
inline for (S.fields) |Field| {
// don't include void fields
if (Field.type == void) continue;
var emit_field = true;
// don't include optional fields that are null when emit_null_optional_fields is set to false
if (@typeInfo(Field.type) == .optional) {
if (self.options.emit_null_optional_fields == false) {
if (@field(value, Field.name) == null) {
emit_field = false;
}
}
}
if (emit_field) {
if (!S.is_tuple) {
try self.objectField(Field.name);
}
try self.write(@field(value, Field.name));
}
}
if (S.is_tuple) {
try self.endArray();
} else {
try self.endObject();
}
return;
},
.error_set => return self.stringValue(@errorName(value)),
.pointer => |ptr_info| switch (ptr_info.size) {
.one => switch (@typeInfo(ptr_info.child)) {
.array => {
// Coerce `*[N]T` to `[]const T`.
const Slice = []const std.meta.Elem(ptr_info.child);
return self.write(@as(Slice, value));
},
else => {
return self.write(value.*);
},
},
.many, .slice => {
if (ptr_info.size == .many and ptr_info.sentinel() == null)
@compileError("unable to stringify type '" ++ @typeName(T) ++ "' without sentinel");
const slice = if (ptr_info.size == .many) std.mem.span(value) else value;
if (ptr_info.child == u8) {
// This is a []const u8, or some similar Zig string.
if (!self.options.emit_strings_as_arrays and std.unicode.utf8ValidateSlice(slice)) {
return self.stringValue(slice);
}
}
try self.beginArray();
for (slice) |x| {
try self.write(x);
}
try self.endArray();
return;
},
else => @compileError("Unable to stringify type '" ++ @typeName(T) ++ "'"),
},
.array => {
// Coerce `[N]T` to `*const [N]T` (and then to `[]const T`).
return self.write(&value);
},
.vector => |info| {
const array: [info.len]info.child = value;
return self.write(&array);
},
else => @compileError("Unable to stringify type '" ++ @typeName(T) ++ "'"),
}
unreachable;
}
fn stringValue(self: *Self, s: []const u8) !void {
try self.valueStart();
try encodeJsonString(s, self.options, self.stream);
self.valueDone();
}
};
}