可使用 serialize 序列化 ZON。
以下函数用于序列化递归类型:
若需进一步控制序列化,参见 Serializer。
以下类型及任何包含这些类型的类型不可序列化:
typevoid,但作为联合体载荷时除外noreturn- 错误集合、错误联合体
- 无标签联合体
- 非穷举枚举
- 多元素指针或 C 指针
- 不透明类型,包括
anyopaque - 异步帧类型,包括
anyframe和anyframe->T - 函数
其他所有类型均有效。不支持的类型会在编译期序列化失败。 指针会被解引用后继续序列化。
std.zon.stringify.assert
别名
别名目标 std.debug.assert
std.zon.stringify.expectSerializeEqual
函数
fn expectSerializeEqual( expected: []const u8, value: anytype, options: SerializeOptions, ) !void
参数
expected: []const u8
options: SerializeOptions
std.zon.stringify.isNestedOptional
函数
fn isNestedOptional(T: type) bool
参数
T: type
std.zon.stringify.isNestedOptionalInner
函数
fn isNestedOptionalInner(T: type) bool
参数
T: type
std.zon.stringify.serialize
函数
将给定值序列化为 ZON。
在编译期断言 @TypeOf(val) 不是递归类型。
pub fn serialize(val: anytype, options: SerializeOptions, writer: *Writer) Writer.Error!void
参数
options: SerializeOptions
writer: *Writer
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.zon.stringify.serializeArbitraryDepth
函数
类似于 serialize,但允许递归类型。
调用方负责确保 val 不包含环。
pub fn serializeArbitraryDepth( val: anytype, options: SerializeOptions, writer: *Writer, ) Serializer.Error!void
参数
options: SerializeOptions
writer: *Writer
错误
std.zon.stringify.serializeMaxDepth
函数
类似 serialize,但允许递归类型。
若超过 depth,返回 error.ExceededMaxDepth。
每个嵌套值都会使深度增加一。
pub fn serializeMaxDepth( val: anytype, options: SerializeOptions, writer: *Writer, depth: usize, ) Serializer.DepthError!void
参数
错误
std.zon.stringify.SerializeOptions
容器
字段
whitespace: bool = true为 false 时省略空白,否则按标准 Zig 风格生成空白。
emit_codepoint_literals: Serializer.EmitCodepointLiterals = .never确定何时将 Unicode 码点输出为字面量,而不是整数。
emit_strings_as_containers: bool = false为 true 时,u8 切片和指向 u8 数组的指针序列化为容器。
否则序列化为字符串字面量。
emit_default_optional_fields: bool = true为 false 时,结构体字段值等于默认值则不写入。
使用 std.meta.eql 比较。
escape_non_ascii: bool = false若为 true,则转义非 ASCII Unicode 字符。
std.zon.stringify.Serializer
别名
别名目标 std.zon.Serializer
std.zon.stringify.std
别名
别名目标 std
std.zon.stringify.Writer
别名
别名目标 std.Io.Writer
源码
std/zon/stringify.zig
//! 可使用 `serialize` 序列化 ZON。
//!
//! 以下函数用于序列化递归类型:
//! * `serializeMaxDepth`
//! * `serializeArbitraryDepth`
//!
//! 若需进一步控制序列化,参见 `Serializer`。
//!
//! 以下类型及任何包含这些类型的类型不可序列化:
//! * `type`
//! * `void`,但作为联合体载荷时除外
//! * `noreturn`
//! * 错误集合、错误联合体
//! * 无标签联合体
//! * 非穷举枚举
//! * 多元素指针或 C 指针
//! * 不透明类型,包括 `anyopaque`
//! * 异步帧类型,包括 `anyframe` 和 `anyframe->T`
//! * 函数
//!
//! 其他所有类型均有效。不支持的类型会在编译期序列化失败。
//! 指针会被解引用后继续序列化。
const std = @import("std");
const assert = std.debug.assert;
const Writer = std.Io.Writer;
const Serializer = @import("Serializer.zig");
pub const SerializeOptions = struct {
/// 为 false 时省略空白,否则按标准 Zig 风格生成空白。
whitespace: bool = true,
/// 确定何时将 Unicode 码点输出为字面量,而不是整数。
emit_codepoint_literals: Serializer.EmitCodepointLiterals = .never,
/// 为 true 时,`u8` 切片和指向 `u8` 数组的指针序列化为容器。
/// 否则序列化为字符串字面量。
emit_strings_as_containers: bool = false,
/// 为 false 时,结构体字段值等于默认值则不写入。
/// 使用 `std.meta.eql` 比较。
emit_default_optional_fields: bool = true,
/// 若为 true,则转义非 ASCII Unicode 字符。
escape_non_ascii: bool = false,
};
/// 将给定值序列化为 ZON。
///
/// 在编译期断言 `@TypeOf(val)` 不是递归类型。
pub fn serialize(val: anytype, options: SerializeOptions, writer: *Writer) Writer.Error!void {
var s: Serializer = .{
.writer = writer,
.options = .{ .whitespace = options.whitespace },
};
try s.value(val, .{
.emit_codepoint_literals = options.emit_codepoint_literals,
.emit_strings_as_containers = options.emit_strings_as_containers,
.emit_default_optional_fields = options.emit_default_optional_fields,
.escape_non_ascii = options.escape_non_ascii,
});
}
/// 类似 `serialize`,但允许递归类型。
///
/// 若超过 `depth`,返回 `error.ExceededMaxDepth`。
/// 每个嵌套值都会使深度增加一。
pub fn serializeMaxDepth(
val: anytype,
options: SerializeOptions,
writer: *Writer,
depth: usize,
) Serializer.DepthError!void {
var s: Serializer = .{
.writer = writer,
.options = .{ .whitespace = options.whitespace },
};
try s.valueMaxDepth(val, .{
.emit_codepoint_literals = options.emit_codepoint_literals,
.emit_strings_as_containers = options.emit_strings_as_containers,
.emit_default_optional_fields = options.emit_default_optional_fields,
.escape_non_ascii = options.escape_non_ascii,
}, depth);
}
/// 类似于 `serialize`,但允许递归类型。
///
/// 调用方负责确保 `val` 不包含环。
pub fn serializeArbitraryDepth(
val: anytype,
options: SerializeOptions,
writer: *Writer,
) Serializer.Error!void {
var s: Serializer = .{
.writer = writer,
.options = .{ .whitespace = options.whitespace },
};
try s.valueArbitraryDepth(val, .{
.emit_codepoint_literals = options.emit_codepoint_literals,
.emit_strings_as_containers = options.emit_strings_as_containers,
.emit_default_optional_fields = options.emit_default_optional_fields,
.escape_non_ascii = options.escape_non_ascii,
});
}
fn isNestedOptional(T: type) bool {
comptime switch (@typeInfo(T)) {
.optional => |optional| return isNestedOptionalInner(optional.child),
else => return false,
};
}
fn isNestedOptionalInner(T: type) bool {
switch (@typeInfo(T)) {
.pointer => |pointer| {
if (pointer.size == .one) {
return isNestedOptionalInner(pointer.child);
} else {
return false;
}
},
.optional => return true,
else => return false,
}
}
fn expectSerializeEqual(
expected: []const u8,
value: anytype,
options: SerializeOptions,
) !void {
var aw: Writer.Allocating = .init(std.testing.allocator);
const bw = &aw.writer;
defer aw.deinit();
try serialize(value, options, bw);
try std.testing.expectEqualStrings(expected, aw.written());
}
test "std.zon stringify whitespace, high level API" {
try expectSerializeEqual(".{}", .{}, .{});
try expectSerializeEqual(".{}", .{}, .{ .whitespace = false });
try expectSerializeEqual(".{1}", .{1}, .{});
try expectSerializeEqual(".{1}", .{1}, .{ .whitespace = false });
try expectSerializeEqual(".{1}", @as([1]u32, .{1}), .{});
try expectSerializeEqual(".{1}", @as([1]u32, .{1}), .{ .whitespace = false });
try expectSerializeEqual(".{1}", @as([]const u32, &.{1}), .{});
try expectSerializeEqual(".{1}", @as([]const u32, &.{1}), .{ .whitespace = false });
try expectSerializeEqual(".{ .x = 1 }", .{ .x = 1 }, .{});
try expectSerializeEqual(".{.x=1}", .{ .x = 1 }, .{ .whitespace = false });
try expectSerializeEqual(".{ 1, 2 }", .{ 1, 2 }, .{});
try expectSerializeEqual(".{1,2}", .{ 1, 2 }, .{ .whitespace = false });
try expectSerializeEqual(".{ 1, 2 }", @as([2]u32, .{ 1, 2 }), .{});
try expectSerializeEqual(".{1,2}", @as([2]u32, .{ 1, 2 }), .{ .whitespace = false });
try expectSerializeEqual(".{ 1, 2 }", @as([]const u32, &.{ 1, 2 }), .{});
try expectSerializeEqual(".{1,2}", @as([]const u32, &.{ 1, 2 }), .{ .whitespace = false });
try expectSerializeEqual(".{ .x = 1, .y = 2 }", .{ .x = 1, .y = 2 }, .{});
try expectSerializeEqual(".{.x=1,.y=2}", .{ .x = 1, .y = 2 }, .{ .whitespace = false });
try expectSerializeEqual(
\\.{
\\ 1,
\\ 2,
\\ 3,
\\}
, .{ 1, 2, 3 }, .{});
try expectSerializeEqual(".{1,2,3}", .{ 1, 2, 3 }, .{ .whitespace = false });
try expectSerializeEqual(
\\.{
\\ 1,
\\ 2,
\\ 3,
\\}
, @as([3]u32, .{ 1, 2, 3 }), .{});
try expectSerializeEqual(".{1,2,3}", @as([3]u32, .{ 1, 2, 3 }), .{ .whitespace = false });
try expectSerializeEqual(
\\.{
\\ 1,
\\ 2,
\\ 3,
\\}
, @as([]const u32, &.{ 1, 2, 3 }), .{});
try expectSerializeEqual(
".{1,2,3}",
@as([]const u32, &.{ 1, 2, 3 }),
.{ .whitespace = false },
);
try expectSerializeEqual(
\\.{
\\ .x = 1,
\\ .y = 2,
\\ .z = 3,
\\}
, .{ .x = 1, .y = 2, .z = 3 }, .{});
try expectSerializeEqual(
".{.x=1,.y=2,.z=3}",
.{ .x = 1, .y = 2, .z = 3 },
.{ .whitespace = false },
);
const Union = union(enum) { a: bool, b: i32, c: u8 };
try expectSerializeEqual(".{ .b = 1 }", Union{ .b = 1 }, .{});
try expectSerializeEqual(".{.b=1}", Union{ .b = 1 }, .{ .whitespace = false });
// 外层对象不换行时的嵌套缩进
try expectSerializeEqual(
\\.{ .inner = .{
\\ 1,
\\ 2,
\\ 3,
\\} }
, .{ .inner = .{ 1, 2, 3 } }, .{});
const UnionWithVoid = union(enum) { a, b: void, c: u8 };
try expectSerializeEqual(
\\.a
, UnionWithVoid.a, .{});
}
test "std.zon stringify whitespace, low level API" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
for ([2]bool{ true, false }) |whitespace| {
s.options = .{ .whitespace = whitespace };
// 空容器
{
var container = try s.beginStruct(.{});
try container.end();
try std.testing.expectEqualStrings(".{}", aw.written());
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{});
try container.end();
try std.testing.expectEqualStrings(".{}", aw.written());
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .wrap = false } });
try container.end();
try std.testing.expectEqualStrings(".{}", aw.written());
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{ .whitespace_style = .{ .wrap = false } });
try container.end();
try std.testing.expectEqualStrings(".{}", aw.written());
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .fields = 0 } });
try container.end();
try std.testing.expectEqualStrings(".{}", aw.written());
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{ .whitespace_style = .{ .fields = 0 } });
try container.end();
try std.testing.expectEqualStrings(".{}", aw.written());
aw.clearRetainingCapacity();
}
// 大小为 1
{
var container = try s.beginStruct(.{});
try container.field("a", 1, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ .a = 1,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{});
try container.field(1, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ 1,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{1}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .wrap = false } });
try container.field("a", 1, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ .a = 1 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1}", aw.written());
}
aw.clearRetainingCapacity();
}
{
// 这里会多出空格,因为事先不知道只有一个字段。
//
var container = try s.beginTuple(.{ .whitespace_style = .{ .wrap = false } });
try container.field(1, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ 1 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{1}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .fields = 1 } });
try container.field("a", 1, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ .a = 1 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{ .whitespace_style = .{ .fields = 1 } });
try container.field(1, .{});
try container.end();
try std.testing.expectEqualStrings(".{1}", aw.written());
aw.clearRetainingCapacity();
}
// 大小为 2
{
var container = try s.beginStruct(.{});
try container.field("a", 1, .{});
try container.field("b", 2, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ .a = 1,
\\ .b = 2,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1,.b=2}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{});
try container.field(1, .{});
try container.field(2, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ 1,
\\ 2,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{1,2}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .wrap = false } });
try container.field("a", 1, .{});
try container.field("b", 2, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ .a = 1, .b = 2 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1,.b=2}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{ .whitespace_style = .{ .wrap = false } });
try container.field(1, .{});
try container.field(2, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ 1, 2 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{1,2}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .fields = 2 } });
try container.field("a", 1, .{});
try container.field("b", 2, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ .a = 1, .b = 2 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1,.b=2}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{ .whitespace_style = .{ .fields = 2 } });
try container.field(1, .{});
try container.field(2, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ 1, 2 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{1,2}", aw.written());
}
aw.clearRetainingCapacity();
}
// 大小 3
{
var container = try s.beginStruct(.{});
try container.field("a", 1, .{});
try container.field("b", 2, .{});
try container.field("c", 3, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ .a = 1,
\\ .b = 2,
\\ .c = 3,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1,.b=2,.c=3}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{});
try container.field(1, .{});
try container.field(2, .{});
try container.field(3, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ 1,
\\ 2,
\\ 3,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{1,2,3}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .wrap = false } });
try container.field("a", 1, .{});
try container.field("b", 2, .{});
try container.field("c", 3, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ .a = 1, .b = 2, .c = 3 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1,.b=2,.c=3}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{ .whitespace_style = .{ .wrap = false } });
try container.field(1, .{});
try container.field(2, .{});
try container.field(3, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(".{ 1, 2, 3 }", aw.written());
} else {
try std.testing.expectEqualStrings(".{1,2,3}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .fields = 3 } });
try container.field("a", 1, .{});
try container.field("b", 2, .{});
try container.field("c", 3, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ .a = 1,
\\ .b = 2,
\\ .c = 3,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{.a=1,.b=2,.c=3}", aw.written());
}
aw.clearRetainingCapacity();
}
{
var container = try s.beginTuple(.{ .whitespace_style = .{ .fields = 3 } });
try container.field(1, .{});
try container.field(2, .{});
try container.field(3, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{
\\ 1,
\\ 2,
\\ 3,
\\}
, aw.written());
} else {
try std.testing.expectEqualStrings(".{1,2,3}", aw.written());
}
aw.clearRetainingCapacity();
}
// 嵌套对象,其中外层容器不换行,而内层容器换行。
{
var container = try s.beginStruct(.{ .whitespace_style = .{ .wrap = false } });
try container.field("first", .{ 1, 2, 3 }, .{});
try container.field("second", .{ 4, 5, 6 }, .{});
try container.end();
if (whitespace) {
try std.testing.expectEqualStrings(
\\.{ .first = .{
\\ 1,
\\ 2,
\\ 3,
\\}, .second = .{
\\ 4,
\\ 5,
\\ 6,
\\} }
, aw.written());
} else {
try std.testing.expectEqualStrings(
".{.first=.{1,2,3},.second=.{4,5,6}}",
aw.written(),
);
}
aw.clearRetainingCapacity();
}
}
}
test "std.zon stringify utf8 codepoints" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
// 可打印 ASCII
try s.int('a');
try std.testing.expectEqualStrings("97", aw.written());
aw.clearRetainingCapacity();
try s.codePoint('a', .{});
try std.testing.expectEqualStrings("'a'", aw.written());
aw.clearRetainingCapacity();
try s.value('a', .{ .emit_codepoint_literals = .always });
try std.testing.expectEqualStrings("'a'", aw.written());
aw.clearRetainingCapacity();
try s.value('a', .{ .emit_codepoint_literals = .printable_ascii });
try std.testing.expectEqualStrings("'a'", aw.written());
aw.clearRetainingCapacity();
try s.value('a', .{ .emit_codepoint_literals = .never });
try std.testing.expectEqualStrings("97", aw.written());
aw.clearRetainingCapacity();
// 过短的转义码点
try s.int('\n');
try std.testing.expectEqualStrings("10", aw.written());
aw.clearRetainingCapacity();
try s.codePoint('\n', .{});
try std.testing.expectEqualStrings("'\\n'", aw.written());
aw.clearRetainingCapacity();
try s.value('\n', .{ .emit_codepoint_literals = .always });
try std.testing.expectEqualStrings("'\\n'", aw.written());
aw.clearRetainingCapacity();
try s.value('\n', .{ .emit_codepoint_literals = .printable_ascii });
try std.testing.expectEqualStrings("10", aw.written());
aw.clearRetainingCapacity();
try s.value('\n', .{ .emit_codepoint_literals = .never });
try std.testing.expectEqualStrings("10", aw.written());
aw.clearRetainingCapacity();
// 较大的码点
try s.int('⚡');
try std.testing.expectEqualStrings("9889", aw.written());
aw.clearRetainingCapacity();
try s.codePoint('⚡', .{ .escape_non_ascii = true });
try std.testing.expectEqualStrings("'\\u{26a1}'", aw.written());
aw.clearRetainingCapacity();
try s.value('⚡', .{ .emit_codepoint_literals = .always, .escape_non_ascii = true });
try std.testing.expectEqualStrings("'\\u{26a1}'", aw.written());
aw.clearRetainingCapacity();
try s.value('⚡', .{ .emit_codepoint_literals = .printable_ascii });
try std.testing.expectEqualStrings("9889", aw.written());
aw.clearRetainingCapacity();
try s.value('⚡', .{ .emit_codepoint_literals = .never });
try std.testing.expectEqualStrings("9889", aw.written());
aw.clearRetainingCapacity();
// 码点无效
try std.testing.expectError(error.InvalidCodepoint, s.codePoint(0x110000 + 1, .{ .escape_non_ascii = true }));
aw.clearRetainingCapacity();
try s.int(0x110000 + 1);
try std.testing.expectEqualStrings("1114113", aw.written());
aw.clearRetainingCapacity();
try s.value(0x110000 + 1, .{ .emit_codepoint_literals = .always });
try std.testing.expectEqualStrings("1114113", aw.written());
aw.clearRetainingCapacity();
try s.value(0x110000 + 1, .{ .emit_codepoint_literals = .printable_ascii });
try std.testing.expectEqualStrings("1114113", aw.written());
aw.clearRetainingCapacity();
try s.value(0x110000 + 1, .{ .emit_codepoint_literals = .never });
try std.testing.expectEqualStrings("1114113", aw.written());
aw.clearRetainingCapacity();
// 有效码点,而非码点类型
try s.value(@as(u22, 'a'), .{ .emit_codepoint_literals = .always });
try std.testing.expectEqualStrings("97", aw.written());
aw.clearRetainingCapacity();
try s.value(@as(u22, 'a'), .{ .emit_codepoint_literals = .printable_ascii });
try std.testing.expectEqualStrings("97", aw.written());
aw.clearRetainingCapacity();
try s.value(@as(i32, 'a'), .{ .emit_codepoint_literals = .never });
try std.testing.expectEqualStrings("97", aw.written());
aw.clearRetainingCapacity();
// 确保将值选项传递给子级
try s.value(.{ .c = '⚡' }, .{ .emit_codepoint_literals = .always, .escape_non_ascii = true });
try std.testing.expectEqualStrings(".{ .c = '\\u{26a1}' }", aw.written());
aw.clearRetainingCapacity();
try s.value(.{ .c = '⚡' }, .{ .emit_codepoint_literals = .never });
try std.testing.expectEqualStrings(".{ .c = 9889 }", aw.written());
aw.clearRetainingCapacity();
}
test "std.zon stringify strings" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
// 最小情况
try s.string("abc⚡ÿ\n", .{ .escape_non_ascii = true });
try std.testing.expectEqualStrings("\"abc\\u{26a1}\\u{ff}\\n\"", aw.written());
aw.clearRetainingCapacity();
try s.tuple("abc⚡ÿ\n", .{});
try std.testing.expectEqualStrings(
\\.{
\\ 97,
\\ 98,
\\ 99,
\\ 226,
\\ 154,
\\ 161,
\\ 195,
\\ 191,
\\ 10,
\\}
, aw.written());
aw.clearRetainingCapacity();
try s.value("abc⚡ÿ\n", .{ .escape_non_ascii = false });
try std.testing.expectEqualStrings("\"abc⚡ÿ\\n\"", aw.written());
aw.clearRetainingCapacity();
try s.value("abc⚡ÿ\n", .{ .emit_strings_as_containers = true });
try std.testing.expectEqualStrings(
\\.{
\\ 97,
\\ 98,
\\ 99,
\\ 226,
\\ 154,
\\ 161,
\\ 195,
\\ 191,
\\ 10,
\\}
, aw.written());
aw.clearRetainingCapacity();
// 子项继承值选项
try s.value(.{ .str = "abc" }, .{});
try std.testing.expectEqualStrings(".{ .str = \"abc\" }", aw.written());
aw.clearRetainingCapacity();
try s.value(.{ .str = "abc" }, .{ .emit_strings_as_containers = true });
try std.testing.expectEqualStrings(
\\.{ .str = .{
\\ 97,
\\ 98,
\\ 99,
\\} }
, aw.written());
aw.clearRetainingCapacity();
// u8 数组(而非指向数组的指针)不被视为字符串,以便数据能够
// 正确往返转换。
try s.value("abc".*, .{});
try std.testing.expectEqualStrings(
\\.{
\\ 97,
\\ 98,
\\ 99,
\\}
, aw.written());
aw.clearRetainingCapacity();
}
test "std.zon stringify multiline strings" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
inline for (.{ true, false }) |whitespace| {
s.options.whitespace = whitespace;
{
try s.multilineString("", .{ .top_level = true });
try std.testing.expectEqualStrings("\\\\", aw.written());
aw.clearRetainingCapacity();
}
{
try s.multilineString("abc⚡", .{ .top_level = true });
try std.testing.expectEqualStrings("\\\\abc⚡", aw.written());
aw.clearRetainingCapacity();
}
{
try s.multilineString("abc⚡\ndef", .{ .top_level = true });
try std.testing.expectEqualStrings("\\\\abc⚡\n\\\\def", aw.written());
aw.clearRetainingCapacity();
}
{
try s.multilineString("abc⚡\r\ndef", .{ .top_level = true });
try std.testing.expectEqualStrings("\\\\abc⚡\n\\\\def", aw.written());
aw.clearRetainingCapacity();
}
{
try s.multilineString("\nabc⚡", .{ .top_level = true });
try std.testing.expectEqualStrings("\\\\\n\\\\abc⚡", aw.written());
aw.clearRetainingCapacity();
}
{
try s.multilineString("\r\nabc⚡", .{ .top_level = true });
try std.testing.expectEqualStrings("\\\\\n\\\\abc⚡", aw.written());
aw.clearRetainingCapacity();
}
{
try s.multilineString("abc\ndef", .{});
if (whitespace) {
try std.testing.expectEqualStrings("\n\\\\abc\n\\\\def\n", aw.written());
} else {
try std.testing.expectEqualStrings("\\\\abc\n\\\\def\n", aw.written());
}
aw.clearRetainingCapacity();
}
{
const str: []const u8 = &.{ 'a', '\r', 'c' };
try s.string(str, .{ .escape_non_ascii = false });
try std.testing.expectEqualStrings("\"a\\rc\"", aw.written());
aw.clearRetainingCapacity();
}
{
try std.testing.expectError(
error.InnerCarriageReturn,
s.multilineString(@as([]const u8, &.{ 'a', '\r', 'c' }), .{}),
);
try std.testing.expectError(
error.InnerCarriageReturn,
s.multilineString(@as([]const u8, &.{ 'a', '\r', 'c', '\n' }), .{}),
);
try std.testing.expectError(
error.InnerCarriageReturn,
s.multilineString(@as([]const u8, &.{ 'a', '\r', 'c', '\r', '\n' }), .{}),
);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
}
}
}
test "std.zon stringify skip default fields" {
const Struct = struct {
x: i32 = 2,
y: i8,
z: u32 = 4,
inner1: struct { a: u8 = 'z', b: u8 = 'y', c: u8 } = .{
.a = '1',
.b = '2',
.c = '3',
},
inner2: struct { u8, u8, u8 } = .{
'a',
'b',
'c',
},
inner3: struct { u8, u8, u8 } = .{
'a',
'b',
'c',
},
};
// 未设置时不跳过
try expectSerializeEqual(
\\.{
\\ .x = 2,
\\ .y = 3,
\\ .z = 4,
\\ .inner1 = .{
\\ .a = '1',
\\ .b = '2',
\\ .c = '3',
\\ },
\\ .inner2 = .{
\\ 'a',
\\ 'b',
\\ 'c',
\\ },
\\ .inner3 = .{
\\ 'a',
\\ 'b',
\\ 'd',
\\ },
\\}
,
Struct{
.y = 3,
.z = 4,
.inner1 = .{
.a = '1',
.b = '2',
.c = '3',
},
.inner3 = .{
'a',
'b',
'd',
},
},
.{ .emit_codepoint_literals = .always },
);
// 顶层默认值
try expectSerializeEqual(
\\.{ .y = 3, .inner3 = .{
\\ 'a',
\\ 'b',
\\ 'd',
\\} }
,
Struct{
.y = 3,
.z = 4,
.inner1 = .{
.a = '1',
.b = '2',
.c = '3',
},
.inner3 = .{
'a',
'b',
'd',
},
},
.{
.emit_default_optional_fields = false,
.emit_codepoint_literals = .always,
},
);
// 内部类型具有默认值,且默认值会改变字段数,从而影响
// 格式化。
try expectSerializeEqual(
\\.{
\\ .y = 3,
\\ .inner1 = .{ .b = '2', .c = '3' },
\\ .inner3 = .{
\\ 'a',
\\ 'b',
\\ 'd',
\\ },
\\}
,
Struct{
.y = 3,
.z = 4,
.inner1 = .{
.a = 'z',
.b = '2',
.c = '3',
},
.inner3 = .{
'a',
'b',
'd',
},
},
.{
.emit_default_optional_fields = false,
.emit_codepoint_literals = .always,
},
);
const DefaultStrings = struct {
foo: []const u8 = "abc",
};
try expectSerializeEqual(
\\.{}
,
DefaultStrings{ .foo = "abc" },
.{ .emit_default_optional_fields = false },
);
try expectSerializeEqual(
\\.{ .foo = "abcd" }
,
DefaultStrings{ .foo = "abcd" },
.{ .emit_default_optional_fields = false },
);
}
test "std.zon depth limits" {
var aw: Writer.Allocating = .init(std.testing.allocator);
const bw = &aw.writer;
defer aw.deinit();
const Recurse = struct { r: []const @This() };
// 正常操作
try serializeMaxDepth(.{ 1, .{ 2, 3 } }, .{}, bw, 16);
try std.testing.expectEqualStrings(".{ 1, .{ 2, 3 } }", aw.written());
aw.clearRetainingCapacity();
try serializeArbitraryDepth(.{ 1, .{ 2, 3 } }, .{}, bw);
try std.testing.expectEqualStrings(".{ 1, .{ 2, 3 } }", aw.written());
aw.clearRetainingCapacity();
// 非递归类型触发最大深度错误
try std.testing.expectError(
error.ExceededMaxDepth,
serializeMaxDepth(.{ 1, .{ 2, .{ 3, 4 } } }, .{}, bw, 3),
);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
// 递归类型达到最大深度的通过情况
{
const maybe_recurse = Recurse{ .r = &.{} };
try serializeMaxDepth(maybe_recurse, .{}, bw, 2);
try std.testing.expectEqualStrings(".{ .r = .{} }", aw.written());
aw.clearRetainingCapacity();
}
// 未经检查地传递递归类型
{
const maybe_recurse = Recurse{ .r = &.{} };
try serializeArbitraryDepth(maybe_recurse, .{}, bw);
try std.testing.expectEqualStrings(".{ .r = .{} }", aw.written());
aw.clearRetainingCapacity();
}
// 递归类型因深度达到最大值而失败。
{
var maybe_recurse = Recurse{ .r = &.{} };
maybe_recurse.r = &.{.{ .r = &.{} }};
try std.testing.expectError(
error.ExceededMaxDepth,
serializeMaxDepth(maybe_recurse, .{}, bw, 2),
);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
}
// 同样的操作,但针对切片
{
var temp: [1]Recurse = .{.{ .r = &.{} }};
const maybe_recurse: []const Recurse = &temp;
try std.testing.expectError(
error.ExceededMaxDepth,
serializeMaxDepth(maybe_recurse, .{}, bw, 2),
);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
var s: Serializer = .{ .writer = bw };
try std.testing.expectError(
error.ExceededMaxDepth,
s.tupleMaxDepth(maybe_recurse, .{}, 2),
);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
try s.tupleArbitraryDepth(maybe_recurse, .{});
try std.testing.expectEqualStrings(".{.{ .r = .{} }}", aw.written());
aw.clearRetainingCapacity();
}
// 后续的切片
{
var temp: [1]Recurse = .{.{ .r = &.{} }};
const maybe_recurse: []const Recurse = &temp;
try serializeMaxDepth(maybe_recurse, .{}, bw, 3);
try std.testing.expectEqualStrings(".{.{ .r = .{} }}", aw.written());
aw.clearRetainingCapacity();
var s: Serializer = .{ .writer = bw };
try s.tupleMaxDepth(maybe_recurse, .{}, 3);
try std.testing.expectEqualStrings(".{.{ .r = .{} }}", aw.written());
aw.clearRetainingCapacity();
try s.tupleArbitraryDepth(maybe_recurse, .{});
try std.testing.expectEqualStrings(".{.{ .r = .{} }}", aw.written());
aw.clearRetainingCapacity();
}
// 递归类型因递归达到最大深度而失败。
{
var temp: [1]Recurse = .{.{ .r = &.{} }};
temp[0].r = &temp;
const maybe_recurse: []const Recurse = &temp;
try std.testing.expectError(
error.ExceededMaxDepth,
serializeMaxDepth(maybe_recurse, .{}, bw, 128),
);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
var s: Serializer = .{ .writer = bw };
try std.testing.expectError(
error.ExceededMaxDepth,
s.tupleMaxDepth(maybe_recurse, .{}, 128),
);
try std.testing.expectEqualStrings("", aw.written());
aw.clearRetainingCapacity();
}
// 较底层 API 其他部分允许的最大深度
{
var s: Serializer = .{ .writer = bw };
const maybe_recurse: []const Recurse = &.{};
try std.testing.expectError(error.ExceededMaxDepth, s.valueMaxDepth(1, .{}, 0));
try s.valueMaxDepth(2, .{}, 1);
try s.value(3, .{});
try s.valueArbitraryDepth(maybe_recurse, .{});
var wip_struct = try s.beginStruct(.{});
try std.testing.expectError(error.ExceededMaxDepth, wip_struct.fieldMaxDepth("a", 1, .{}, 0));
try wip_struct.fieldMaxDepth("b", 4, .{}, 1);
try wip_struct.field("c", 5, .{});
try wip_struct.fieldArbitraryDepth("d", maybe_recurse, .{});
try wip_struct.end();
var t = try s.beginTuple(.{});
try std.testing.expectError(error.ExceededMaxDepth, t.fieldMaxDepth(1, .{}, 0));
try t.fieldMaxDepth(6, .{}, 1);
try t.field(7, .{});
try t.fieldArbitraryDepth(maybe_recurse, .{});
try t.end();
var a = try s.beginTuple(.{});
try std.testing.expectError(error.ExceededMaxDepth, a.fieldMaxDepth(1, .{}, 0));
try a.fieldMaxDepth(8, .{}, 1);
try a.field(9, .{});
try a.fieldArbitraryDepth(maybe_recurse, .{});
try a.end();
try std.testing.expectEqualStrings(
\\23.{}.{
\\ .b = 4,
\\ .c = 5,
\\ .d = .{},
\\}.{
\\ 6,
\\ 7,
\\ .{},
\\}.{
\\ 8,
\\ 9,
\\ .{},
\\}
, aw.written());
}
}
test "std.zon stringify primitives" {
try expectSerializeEqual(
\\.{
\\ .a = 1.5,
\\ .b = 0.3333333333333333333333333333333333,
\\ .c = 3.1415926535897932384626433832795028,
\\ .d = 0,
\\ .e = 0,
\\ .f = -0.0,
\\ .g = inf,
\\ .h = -inf,
\\ .i = nan,
\\}
,
.{
.a = @as(f128, 1.5), // 确保显式 f128 正常工作
.b = 1.0 / 3.0,
.c = std.math.pi,
.d = 0.0,
.e = -0.0,
.f = @as(f128, -0.0),
.g = std.math.inf(f32),
.h = -std.math.inf(f32),
.i = std.math.nan(f32),
},
.{},
);
try expectSerializeEqual(
\\.{
\\ .a = 18446744073709551616,
\\ .b = -18446744073709551616,
\\ .c = 680564733841876926926749214863536422912,
\\ .d = -680564733841876926926749214863536422912,
\\ .e = 0,
\\}
,
.{
.a = 18446744073709551616,
.b = -18446744073709551616,
.c = 680564733841876926926749214863536422912,
.d = -680564733841876926926749214863536422912,
.e = 0,
},
.{},
);
try expectSerializeEqual(
\\.{
\\ .a = true,
\\ .b = false,
\\ .c = .foo,
\\ .e = null,
\\}
,
.{
.a = true,
.b = false,
.c = .foo,
.e = null,
},
.{},
);
const Struct = struct { x: f32, y: f32 };
try expectSerializeEqual(
".{ .a = .{ .x = 1, .y = 2 }, .b = null }",
.{
.a = @as(?Struct, .{ .x = 1, .y = 2 }),
.b = @as(?Struct, null),
},
.{},
);
const E = enum(u8) {
foo,
bar,
};
try expectSerializeEqual(
".{ .a = .foo, .b = .foo }",
.{
.a = .foo,
.b = E.foo,
},
.{},
);
}
test "std.zon stringify ident" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
try expectSerializeEqual(".{ .a = 0 }", .{ .a = 0 }, .{});
try s.ident("a");
try std.testing.expectEqualStrings(".a", aw.written());
aw.clearRetainingCapacity();
try s.ident("foo_1");
try std.testing.expectEqualStrings(".foo_1", aw.written());
aw.clearRetainingCapacity();
try s.ident("_foo_1");
try std.testing.expectEqualStrings("._foo_1", aw.written());
aw.clearRetainingCapacity();
try s.ident("foo bar");
try std.testing.expectEqualStrings(".@\"foo bar\"", aw.written());
aw.clearRetainingCapacity();
try s.ident("1foo");
try std.testing.expectEqualStrings(".@\"1foo\"", aw.written());
aw.clearRetainingCapacity();
try s.ident("var");
try std.testing.expectEqualStrings(".@\"var\"", aw.written());
aw.clearRetainingCapacity();
try s.ident("true");
try std.testing.expectEqualStrings(".true", aw.written());
aw.clearRetainingCapacity();
try s.ident("_");
try std.testing.expectEqualStrings("._", aw.written());
aw.clearRetainingCapacity();
const Enum = enum {
@"foo bar",
};
try expectSerializeEqual(".{ .@\"var\" = .@\"foo bar\", .@\"1\" = .@\"foo bar\" }", .{
.@"var" = .@"foo bar",
.@"1" = Enum.@"foo bar",
}, .{});
}
test "std.zon stringify as tuple" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
// 元组
try s.tuple(.{ 1, 2 }, .{});
try std.testing.expectEqualStrings(".{ 1, 2 }", aw.written());
aw.clearRetainingCapacity();
// 切片
try s.tuple(@as([]const u8, &.{ 1, 2 }), .{});
try std.testing.expectEqualStrings(".{ 1, 2 }", aw.written());
aw.clearRetainingCapacity();
// 数组
try s.tuple([2]u8{ 1, 2 }, .{});
try std.testing.expectEqualStrings(".{ 1, 2 }", aw.written());
aw.clearRetainingCapacity();
}
test "std.zon stringify as float" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
// 编译期浮点数
try s.float(2.5);
try std.testing.expectEqualStrings("2.5", aw.written());
aw.clearRetainingCapacity();
// 指定大小的浮点数
try s.float(@as(f32, 2.5));
try std.testing.expectEqualStrings("2.5", aw.written());
aw.clearRetainingCapacity();
}
test "std.zon stringify vector" {
try expectSerializeEqual(
\\.{
\\ .{},
\\ .{
\\ true,
\\ false,
\\ true,
\\ },
\\ .{},
\\ .{
\\ 1.5,
\\ 2.5,
\\ 3.5,
\\ },
\\ .{},
\\ .{
\\ 2,
\\ 4,
\\ 6,
\\ },
\\ .{ 1, 2 },
\\ .{
\\ 3,
\\ 4,
\\ null,
\\ },
\\}
,
.{
@Vector(0, bool){},
@Vector(3, bool){ true, false, true },
@Vector(0, f32){},
@Vector(3, f32){ 1.5, 2.5, 3.5 },
@Vector(0, u8){},
@Vector(3, u8){ 2, 4, 6 },
@Vector(2, *const u8){ &1, &2 },
@Vector(3, ?*const u8){ &3, &4, null },
},
.{},
);
}
test "std.zon pointers" {
// 具有不同指针层级的基本类型
try expectSerializeEqual("10", &@as(u32, 10), .{});
try expectSerializeEqual("10", &&@as(u32, 10), .{});
try expectSerializeEqual("10", &&&@as(u32, 10), .{});
// 具有不同指针层级的基础可选类型
try expectSerializeEqual("10", @as(?*const u32, &10), .{});
try expectSerializeEqual("null", @as(?*const u32, null), .{});
try expectSerializeEqual("10", @as(?*const u32, &10), .{});
try expectSerializeEqual("null", @as(*const ?u32, &null), .{});
try expectSerializeEqual("10", @as(?*const *const u32, &&10), .{});
try expectSerializeEqual("null", @as(?*const *const u32, null), .{});
try expectSerializeEqual("10", @as(*const ?*const u32, &&10), .{});
try expectSerializeEqual("null", @as(*const ?*const u32, &null), .{});
try expectSerializeEqual("10", @as(*const *const ?u32, &&10), .{});
try expectSerializeEqual("null", @as(*const *const ?u32, &&null), .{});
try expectSerializeEqual(".{ 1, 2 }", &[2]u32{ 1, 2 }, .{});
// 包含嵌套内部指针及字符串分配的复杂类型
{
const Inner = struct {
f1: *const ?*const []const u8,
f2: *const ?*const []const u8,
};
const Outer = struct {
f1: *const ?*const Inner,
f2: *const ?*const Inner,
};
const val: ?*const Outer = &.{
.f1 = &&.{
.f1 = &null,
.f2 = &&"foo",
},
.f2 = &null,
};
try expectSerializeEqual(
\\.{ .f1 = .{ .f1 = null, .f2 = "foo" }, .f2 = null }
, val, .{});
}
}
test "std.zon tuple/struct field" {
var aw: Writer.Allocating = .init(std.testing.allocator);
var s: Serializer = .{ .writer = &aw.writer };
defer aw.deinit();
// 针对结构体测试
{
var root = try s.beginStruct(.{});
{
var tuple = try root.beginTupleField("foo", .{});
try tuple.field(0, .{});
try tuple.field(1, .{});
try tuple.end();
}
{
var strct = try root.beginStructField("bar", .{});
try strct.field("a", 0, .{});
try strct.field("b", 1, .{});
try strct.end();
}
try root.end();
try std.testing.expectEqualStrings(
\\.{
\\ .foo = .{
\\ 0,
\\ 1,
\\ },
\\ .bar = .{
\\ .a = 0,
\\ .b = 1,
\\ },
\\}
, aw.written());
aw.clearRetainingCapacity();
}
// 测试元组
{
var root = try s.beginTuple(.{});
{
var tuple = try root.beginTupleField(.{});
try tuple.field(0, .{});
try tuple.field(1, .{});
try tuple.end();
}
{
var strct = try root.beginStructField(.{});
try strct.field("a", 0, .{});
try strct.field("b", 1, .{});
try strct.end();
}
try root.end();
try std.testing.expectEqualStrings(
\\.{
\\ .{
\\ 0,
\\ 1,
\\ },
\\ .{
\\ .a = 0,
\\ .b = 1,
\\ },
\\}
, aw.written());
aw.clearRetainingCapacity();
}
}