跳转到内容

std.json.Scanner

标准库Zig 0.17.1官方原文
源码std/json/Scanner.zig

第 1 行

本包最底层的解析接口,支持低内存占用的流式输入。 内存需求为 O(d),其中 d 是输入中 [] 或 {} 容器的嵌套深度。 具体需要 d/8 字节,以及 std.ArrayList 实现所需的额外缓冲区。

此扫描器可以产生不完整的词法单元;参见 std.json.Token。 此类型的输入是一系列缓冲区,必须逐个提供。 先使用第一个缓冲区调用 feedInput(),再反复调用 next(),直到返回 error.BufferUnderrun。 随后再次调用 feedInput(),依此类推。 调用 endInput() 时,最后一个输入缓冲区应已传给 feedInput();可以紧接在调用 feedInput() 后执行,也可以等 error.BufferUnderrun 请求更多数据而已无数据可提供时执行。 务必继续调用 next()(在调用 endInput() 之后),直到返回 Token.end_of_document。

标准符合性说明:https://datatracker.ietf.org/doc/html/rfc8259

  • RFC 8259 要求 JSON 文档是有效 UTF-8,但对“属于封闭生态系统”的系统有所例外。作者不清楚这在标准规范中究竟意味着什么。本实现要求输入为有效 UTF-8。
  • RFC 8259 对 \u 十六进制数字是否允许小写存在自相矛盾之处,但这可能是规范缺陷,其意图显然是允许小写。(RFC 5234 将 HEXDIG 定义为仅允许大写。)
  • RFC 8259 提及“字符”时,本实现假定其实际含义是“Unicode 标量值”。参见 http://www.unicode.org/glossary/#unicode_scalar_value 。
  • RFC 8259 未明确禁止 \u 转义序列中的未配对代理项,但含糊地暗示 \u 转义用于编码 Unicode“字符”(即 Unicode 标量值?),这意味着未配对代理项应被禁止。相比之下,ECMA-404(另一项与之竞争或兼容的 JSON 标准,JavaScript 的 JSON.parse() 遵循该标准)明确允许未配对代理项。本实现禁止 \u 序列中的未配对代理项:若 \u 序列出现高位代理项,其后必须立即跟随以 \u 形式表示的低位代理项。
  • RFC 8259 允许实现“接受非 JSON 形式或扩展”,本实现均不接受。
  • RFC 8259 允许实现限制“文本大小”“最大嵌套深度”“数值范围与精度”以及“字符串长度和字符内容”。除上述限制,以及嵌套深度需要分配内存外,此底层实现不施加这些限制。注意,此底层接口并不按数值解释数字,而是输出其原始文本形式,供上层代码解释。
  • 此底层实现允许对象键重复,键值对按其在输入中出现的顺序输出。

字段

state: State = .value
string_is_object_key: bool = false
stack: BitStack
value_start: usize = undefined
utf16_code_units: [2]u16 = undefined
input: []const u8 = ""
cursor: usize = 0
is_end_of_input: bool = false
diagnostics: ?*Diagnostics = null

std.json.Scanner.Allocator

别名

第 48 行

别名目标 std.mem.Allocator

std.json.Scanner.AllocError

错误集合

第 116 行

错误

OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.AllocIntoArrayListError

错误集合

第 119 行

错误

BufferUnderrun
OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong AllocError

std.json.Scanner.allocNextIntoArrayList

函数

第 175 行

等价于 allocNextIntoArrayListMax(value_list, when, default_max_value_len);。

pub fn allocNextIntoArrayList(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen) AllocIntoArrayListError!?[]const u8

参数

self: *@This()
value_list: *std.array_list.Managed(u8)
when: AllocWhen

错误

BufferUnderrun
OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong AllocError

std.json.Scanner.allocNextIntoArrayListMax

函数

第 188 行

下一个标记的类型必须为 .number 或 .string。参见 peekNextTokenType()。 采用 .alloc_if_needed 且无需分配时, 此方法返回输入缓冲区中的内容切片,不修改 value_list。 需要分配或采用 .alloc_always 时,此方法将部分标记拼接到给定的 value_list 中, 返回 null 的条件是最终的 .number 或 .string 标记已写入。 发生 error.BufferUnderrun 时,部分值会保留在给定的 value_list 中。 此方法从不重置给定的 value_list,因此发生 error.BufferUnderrun 后, 可再次传入同一数组列表来继续处理。 此方法不会指出返回内容属于 .number 还是 .string 标记类型; 调用方应自行知道当前处理的标记类型。

pub fn allocNextIntoArrayListMax(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen, max_value_len: usize) AllocIntoArrayListError!?[]const u8

参数

self: *@This()
value_list: *std.array_list.Managed(u8)
when: AllocWhen
max_value_len: usize

错误

BufferUnderrun
OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong AllocError

std.json.Scanner.AllocWhen

容器

第 1567 行

参见 std.json.Token 的文档。

字段

alloc_if_needed
alloc_always

std.json.Scanner.appendSlice

函数

第 1748 行

fn appendSlice(list: *std.array_list.Managed(u8), buf: []const u8, max_value_len: usize) !void

参数

list: *std.array_list.Managed(u8)
buf: []const u8
max_value_len: usize

std.json.Scanner.ARRAY_MODE

常量

第 1746 行

std.json.Scanner.assert

别名

第 49 行

别名目标 std.debug.assert

std.json.Scanner.BitStack

别名

第 50 行

别名目标 std.BitStack

std.json.Scanner.default_buffer_size

常量

第 1422 行

由 json.reader 使用。

std.json.Scanner.default_max_value_len

常量

第 1571 行

为保证安全,默认将单个字符串或数值的存储分配大小上限设为 4MiB。 可通过调用 nextAllocMax() 而非 nextAlloc() 指定此限制。

std.json.Scanner.deinit

函数

第 83 行

pub fn deinit(self: *@This()) void

参数

self: *@This()

std.json.Scanner.Diagnostics

容器

第 1546 行

要启用诊断,请声明 var diagnostics = Diagnostics{};,然后调用 source.enableDiagnostics(&diagnostics);, 其中 source 是刚初始化的 std.json.Reader 或 std.json.Scanner。 在任意时刻,尤其是刚发生错误之后,调用 getLine()、getColumn() 和/或 getByteOffset(), 即可取得有意义的信息。

字段

line_number: u64 = 1
line_start_cursor: usize = @as(usize, @bitCast(@as(isize, -1)))
total_bytes_before_current_input: u64 = 0
cursor_pointer: *const usize = undefined

std.json.Scanner.Diagnostics.getByteOffset

函数

第 1561 行

从 0 开始。表示自输入起点以来的字节偏移。

pub fn getByteOffset(self: *const @This()) u64

参数

self: *const @This()

std.json.Scanner.Diagnostics.getColumn

函数

第 1557 行

从 1 开始。

pub fn getColumn(self: *const @This()) u64

参数

self: *const @This()

std.json.Scanner.Diagnostics.getLine

函数

第 1553 行

从 1 开始。

pub fn getLine(self: *const @This()) u64

参数

self: *const @This()

std.json.Scanner.enableDiagnostics

函数

第 88 行

pub fn enableDiagnostics(self: *@This(), diagnostics: *Diagnostics) void

参数

self: *@This()
diagnostics: *Diagnostics

std.json.Scanner.endInput

函数

第 111 行

不再调用 feedInput() 时调用此函数。 可以在最后一次 feedInput() 之后立即调用, 也可以稍后调用,例如当 next() 返回 error.BufferUnderrun 时。 调用 endInput() 后,务必继续调用 next*(),直到获得 .end_of_document。

pub fn endInput(self: *@This()) void

参数

self: *@This()

std.json.Scanner.endOfBufferInNumber

函数

第 1338 行

fn endOfBufferInNumber(self: *@This(), allow_end: bool) !Token

参数

self: *@This()
allow_end: bool

std.json.Scanner.endOfBufferInString

函数

第 1349 行

fn endOfBufferInString(self: *@This()) !Token

参数

self: *@This()

std.json.Scanner.ensureTotalStackCapacity

函数

第 316 行

预先分配足以容纳给定嵌套层数的内存。 stackHeight() 不超过该数值时,不会发生分配。

pub fn ensureTotalStackCapacity(self: *@This(), height: usize) Allocator.Error!void

参数

self: *@This()
height: usize

错误

OutOfMemory

std.json.Scanner.Error

错误集合

第 1419 行

解析错误分为两类:

  • SyntaxError 表示明显格式错误的 JSON 文档, 例如输入文档根本不是 JSON。
  • UnexpectedEndOfInput 表示此前的内容均 有效,但输入似乎因某种原因被截断。 注意,完全为空或仅包含空白的输入会产生 UnexpectedEndOfInput。

错误

SyntaxError
UnexpectedEndOfInput

std.json.Scanner.expectByte

函数

第 1270 行

fn expectByte(self: *const @This()) !u8

参数

self: *const @This()

std.json.Scanner.feedInput

函数

第 95 行

每当从 next() 得到 error.BufferUnderrun 时调用此函数。 没有更多输入可提供时,调用 endInput()。

pub fn feedInput(self: *@This(), input: []const u8) void

参数

self: *@This()
input: []const u8

std.json.Scanner.initCompleteInput

函数

第 76 行

如果输入是单个切片,请使用此方法。 这实际上等价于:

initStreaming(allocator);
feedInput(complete_input);
endInput();
pub fn initCompleteInput(allocator: Allocator, complete_input: []const u8) @This()

参数

allocator: Allocator
complete_input: []const u8

std.json.Scanner.initStreaming

函数

第 64 行

分配器仅用于跟踪 [] 和 {} 的嵌套层级。

pub fn initStreaming(allocator: Allocator) @This()

参数

allocator: Allocator

std.json.Scanner.isNumberFormattedLikeAnInteger

函数

第 1759 行

对于从 Token.number 或 Token.allocated_number 获取的切片, 若数字不含小数部分或指数部分,且不是 -0,此函数返回 true。 注意,所编码的数值本身仍可能是整数,例如 1.0。 此函数用于提示应对该值使用整数解析还是浮点解析。 对于非数字输入,结果无意义。

pub fn isNumberFormattedLikeAnInteger(value: []const u8) bool

参数

value: []const u8

std.json.Scanner.next

函数

第 321 行

此函数的文档见 std.json.Token。

pub fn next(self: *@This()) NextError!Token

参数

self: *@This()

错误

BufferUnderrun
OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.nextAlloc

函数

第 124 行

等同于 nextAllocMax(allocator, when, default_max_value_len);。 只有调用 endInput() 或 initCompleteInput() 后才能使用此函数。 nextAlloc*() 函数行为的文档另请参见 std.json.Token。

pub fn nextAlloc(self: *@This(), allocator: Allocator, when: AllocWhen) AllocError!Token

参数

self: *@This()
allocator: Allocator
when: AllocWhen

错误

OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.nextAllocMax

函数

第 130 行

此函数仅在调用 endInput()(或 initCompleteInput())后可用。 有关 nextAlloc*() 函数行为的文档,另见 std.json.Token。

pub fn nextAllocMax(self: *@This(), allocator: Allocator, when: AllocWhen, max_value_len: usize) AllocError!Token

参数

self: *@This()
allocator: Allocator
when: AllocWhen
max_value_len: usize

错误

OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.NextError

错误集合

第 115 行

错误

BufferUnderrun
OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.OBJECT_MODE

常量

第 1745 行

std.json.Scanner.partialStringCodepoint

函数

第 1382 行

fn partialStringCodepoint(code_point: u21) Token

参数

code_point: u21

std.json.Scanner.PeekError

错误集合

第 117 行

错误

BufferUnderrun
SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.peekNextTokenType

函数

第 1092 行

在输入中向前扫描,直到下一个词元的首字节或输入末尾, 确定下次调用 next*() 将返回的词元类型。 此函数幂等,只会越过逗号、冒号及词元之间的空白。

pub fn peekNextTokenType(self: *@This()) PeekError!TokenType

参数

self: *@This()

错误

BufferUnderrun
SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.Reader

容器

第 1574 行

此处所有 next*() 方法均处理来自 std.json.Scanner 的 error.BufferUnderrun,然后从读取器读取。

字段

scanner: Scanner
reader: *std.Io.Reader

std.json.Scanner.Reader.AllocError

错误集合

第 1597 行

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.Reader.allocNextIntoArrayList

函数

第 1641 行

等价于 allocNextIntoArrayListMax(value_list, when, default_max_value_len);。

pub fn allocNextIntoArrayList(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen) Reader.AllocError!?[]const u8

参数

self: *@This()
value_list: *std.array_list.Managed(u8)
when: AllocWhen

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.Reader.allocNextIntoArrayListMax

函数

第 1645 行

调用 std.json.Scanner.allocNextIntoArrayListMax,并处理 error.BufferUnderrun。

pub fn allocNextIntoArrayListMax(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen, max_value_len: usize) Reader.AllocError!?[]const u8

参数

self: *@This()
value_list: *std.array_list.Managed(u8)
when: AllocWhen
max_value_len: usize

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.Reader.deinit

函数

第 1585 行

pub fn deinit(self: *@This()) void

参数

self: *@This()

std.json.Scanner.Reader.enableDiagnostics

函数

第 1591 行

调用 std.json.Scanner.enableDiagnostics。

pub fn enableDiagnostics(self: *@This(), diagnostics: *Diagnostics) void

参数

self: *@This()
diagnostics: *Diagnostics

std.json.Scanner.Reader.ensureTotalStackCapacity

函数

第 1705 行

调用 std.json.Scanner.ensureTotalStackCapacity。

pub fn ensureTotalStackCapacity(self: *@This(), height: usize) Allocator.Error!void

参数

self: *@This()
height: usize

错误

OutOfMemory

std.json.Scanner.Reader.init

函数

第 1579 行

分配器仅用于跟踪 [] 和 {} 的嵌套层级。

pub fn init(allocator: Allocator, io_reader: *std.Io.Reader) @This()

参数

allocator: Allocator
io_reader: *std.Io.Reader

std.json.Scanner.Reader.next

函数

第 1710 行

此函数的文档见 std.json.Token。

pub fn next(self: *@This()) Reader.NextError!Token

参数

self: *@This()

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.Reader.nextAlloc

函数

第 1602 行

等同于 nextAllocMax(allocator, when, default_max_value_len); nextAlloc*() 函数的行为文档另见 std.json.Token。

pub fn nextAlloc(self: *@This(), allocator: Allocator, when: AllocWhen) Reader.AllocError!Token

参数

self: *@This()
allocator: Allocator
when: AllocWhen

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.Reader.nextAllocMax

函数

第 1606 行

关于 nextAlloc*() 函数行为的文档,另请参见 std.json.Token。

pub fn nextAllocMax(self: *@This(), allocator: Allocator, when: AllocWhen, max_value_len: usize) Reader.AllocError!Token

参数

self: *@This()
allocator: Allocator
when: AllocWhen
max_value_len: usize

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error
ValueTooLong

std.json.Scanner.Reader.NextError

错误集合

第 1595 行

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.Reader.PeekError

错误集合

第 1598 行

错误

EndOfStream Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.Reader.peekNextTokenType

函数

第 1723 行

参见 std.json.Scanner.peekNextTokenType()。

pub fn peekNextTokenType(self: *@This()) Reader.PeekError!TokenType

参数

self: *@This()

错误

EndOfStream Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.Reader.refillBuffer

函数

第 1735 行

fn refillBuffer(self: *@This()) std.Io.Reader.Error!void

参数

self: *@This()

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.json.Scanner.Reader.SkipError

别名

第 1596 行

别名目标 std.json.Scanner.Reader.NextError

std.json.Scanner.Reader.skipUntilStackHeight

函数

第 1688 行

类似于 std.json.Scanner.skipUntilStackHeight(),但会处理 error.BufferUnderrun。

pub fn skipUntilStackHeight(self: *@This(), terminal_stack_height: usize) Reader.NextError!void

参数

self: *@This()
terminal_stack_height: usize

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.Reader.skipValue

函数

第 1658 行

类似于 std.json.Scanner.skipValue,但处理 error.BufferUnderrun。

pub fn skipValue(self: *@This()) Reader.SkipError!void

参数

self: *@This()

错误

EndOfStream Error
OutOfMemory Error
ReadFailed Error

详细诊断参见 Reader 的实现。

SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.Reader.stackHeight

函数

第 1701 行

调用 std.json.Scanner.stackHeight。

pub fn stackHeight(self: *const @This()) usize

参数

self: *const @This()

std.json.Scanner.Scanner

别名

第 45 行

别名目标 std.json.Scanner

std.json.Scanner.SkipError

错误集合

第 118 行

错误

OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.skipUntilStackHeight

函数

第 297 行

跳过标记,直到某个 .object_end 或 .array_end 标记使 stackHeight() 等于给定栈高度。 与 skipValue() 不同,此函数可在流式模式下使用。

pub fn skipUntilStackHeight(self: *@This(), terminal_stack_height: usize) NextError!void

参数

self: *@This()
terminal_stack_height: usize

错误

BufferUnderrun
OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.skipValue

函数

第 252 行

只有调用 endInput() 或 initCompleteInput() 后才能使用此函数。 如果下一个词元类型为 .object_begin 或 .array_begin, 则反复调用 next(),直到找到对应的 .object_end 或 .array_end。 如果下一个词元类型为 .number 或 .string, 则反复调用 next(),直到找到非 .partial_* 的 .number 或 .string 词元。 如果下一个词元类型为 .true、.false 或 .null,则调用一次 next()。 下一个词元类型不得为 .object_end、.array_end 或 .end_of_document; 参见 peekNextTokenType()。

pub fn skipValue(self: *@This()) SkipError!void

参数

self: *@This()

错误

OutOfMemory Error
SyntaxError Error
UnexpectedEndOfInput Error

std.json.Scanner.skipWhitespace

函数

第 1279 行

fn skipWhitespace(self: *@This()) void

参数

self: *@This()

std.json.Scanner.skipWhitespaceCheckEnd

函数

第 1303 行

fn skipWhitespaceCheckEnd(self: *@This()) !bool

参数

self: *@This()

std.json.Scanner.skipWhitespaceExpectByte

函数

第 1298 行

fn skipWhitespaceExpectByte(self: *@This()) !u8

参数

self: *@This()

std.json.Scanner.stackHeight

函数

第 310 行

当前位置 {} 或 [] 的嵌套深度。

pub fn stackHeight(self: *const @This()) usize

参数

self: *const @This()

std.json.Scanner.State

容器

第 1218 行

字段

value
post_value
object_start
object_post_comma
array_start
number_minus
number_leading_zero
number_int
number_post_dot
number_frac
number_post_e
number_post_e_sign
number_exp
string
string_backslash
string_backslash_u
string_backslash_u_1
string_backslash_u_2
string_backslash_u_3
string_surrogate_half
string_surrogate_half_backslash
string_surrogate_half_backslash_u
string_surrogate_half_backslash_u_1
string_surrogate_half_backslash_u_2
string_surrogate_half_backslash_u_3
string_utf8_last_byte
string_utf8_second_to_last_byte
string_utf8_second_to_last_byte_guard_against_overlong
string_utf8_second_to_last_byte_guard_against_surrogate_half
string_utf8_third_to_last_byte
string_utf8_third_to_last_byte_guard_against_overlong
string_utf8_third_to_last_byte_guard_against_too_large
literal_t
literal_tr
literal_tru
literal_f
literal_fa
literal_fal
literal_fals
literal_n
literal_nu
literal_nul

std.json.Scanner.std

别名

第 46 行

别名目标 std

std.json.Scanner.takeValueSlice

函数

第 1321 行

fn takeValueSlice(self: *@This()) []const u8

参数

self: *@This()

std.json.Scanner.takeValueSliceMinusTrailingOffset

函数

第 1326 行

fn takeValueSliceMinusTrailingOffset(self: *@This(), trailing_negative_offset: usize) []const u8

参数

self: *@This()
trailing_negative_offset: usize

std.json.Scanner.Token

容器

第 1503 行

std.json.Scanner 和 std.json.Reader 的 .next*() 函数生成的标记遵循以下语法:

 <document> = <value> .end_of_document
 <value> =
   | <object>
   | <array>
   | <number>
   | <string>
   | .true
   | .false
   | .null
 <object> = .object_begin ( <string> <value> )* .object_end
 <array> = .array_begin ( <value> )* .array_end
 <number> = <It depends. See below.>
 <string> = <It depends. See below.>

<number> 和 <string> 的具体形式取决于调用哪个 next*() 方法:

next():
 <number> = ( .partial_number )* .number
 <string> = ( <partial_string> )* .string
 <partial_string> =
   | .partial_string
   | .partial_string_escaped_1
   | .partial_string_escaped_2
   | .partial_string_escaped_3
   | .partial_string_escaped_4

nextAlloc*(..., .alloc_always):
 <number> = .allocated_number
 <string> = .allocated_string

nextAlloc*(..., .alloc_if_needed):
 <number> =
   | .number
   | .allocated_number
 <string> =
   | .string
   | .allocated_string

对于所有载荷类型为 []const u8、[]u8 或 [n]u8 的标记,载荷表示该值的内容。数字载荷保留其在输入中的精确文本表示;字符串载荷则是解析转义序列后的内容。

对于 .allocated_number 和 .allocated_string,[]u8 载荷由给定分配器分配。你负责管理这些内存;json.Reader.deinit() 不会释放它们。

.partial_* 标记表示值跨越多个输入缓冲区,或者字符串包含转义序列。若要在内存中取得完整值,需要自行拼接;调用 nextAlloc*() 可以代为完成,并返回包含结果的 .allocated_* 标记。

对于载荷为 []const u8 的标记,载荷是当前输入缓冲区的切片。下一次调用 json.Scanner.feedInput(),或调用返回错误集合包含 json.Error 的任意 json.Reader 方法时,该内存可能变为未定义。若要持久保留值,建议复制,或使用会代为复制的 .alloc_always。

注意,跟在 .partial_* 后的 .number 和 .string 标记长度可能为 0,表示之前的部分值已经完整,且没有额外字节。当输入缓冲区恰好在值的末尾分界时会出现这种情况,例如 "[1234"、"]"。.partial_* 标记的长度绝不会为 0。

建议按如下策略使用不同的 next*() 方法:

预期对象键时使用 .alloc_if_needed。通常无须长期保留键字符串的副本,只需检查它属于哪个字段;若键恰好需要分配内存,检查后立即释放。

预期有实际含义的字符串值(例如 : 右侧)时,使用 .alloc_always,使其在继续解析文档其他部分时保持有效。

预期数字值时,使用 .alloc_if_needed。通常会将数字字符串解析为数值,因此只临时需要完整字符串表示。

跳过无法识别的值时,使用 skipValue()。

字段

object_begin
object_end
array_begin
array_end
true
false
null
number: []const u8
partial_number: []const u8
allocated_number: []u8
string: []const u8
partial_string: []const u8
partial_string_escaped_1: [1]u8
partial_string_escaped_2: [2]u8
partial_string_escaped_3: [3]u8
partial_string_escaped_4: [4]u8
allocated_string: []u8
end_of_document

std.json.Scanner.TokenType

容器

第 1529 行

仅用于 peekNextTokenType();根据 next*() 调用将生成的下一个标记的首字节进行分类。

字段

object_begin
object_end
array_begin
array_end
true
false
null
number
string
end_of_document

std.json.Scanner.validate

函数

第 1397 行

扫描输入,检查 JSON 格式是否有误。 遇到 SyntaxError 或 UnexpectedEndOfInput 时返回 false。 原样返回分配器的任何错误;这种情况不太常见, 但输入嵌套极深时可能发生。

pub fn validate(allocator: Allocator, s: []const u8) Allocator.Error!bool

参数

allocator: Allocator
s: []const u8

错误

OutOfMemory
源码

std/json/Scanner.zig

//! 本包最底层的解析接口,支持低内存占用的流式输入。
//! 内存需求为 `O(d)`,其中 d 是输入中 `[]` 或 `{}` 容器的嵌套深度。
//! 具体需要 `d/8` 字节,以及 `std.ArrayList` 实现所需的额外缓冲区。
//!
//! 此扫描器可以产生不完整的词法单元;参见 `std.json.Token`。
//! 此类型的输入是一系列缓冲区,必须逐个提供。
//! 先使用第一个缓冲区调用 `feedInput()`,再反复调用 `next()`,直到返回 `error.BufferUnderrun`。
//! 随后再次调用 `feedInput()`,依此类推。
//! 调用 `endInput()` 时,最后一个输入缓冲区应已传给 `feedInput()`;可以紧接在调用 `feedInput()` 后执行,也可以等 `error.BufferUnderrun` 请求更多数据而已无数据可提供时执行。
//! 务必继续调用 `next()`(在调用 `endInput()` 之后),直到返回 `Token.end_of_document`。
//!
//! 标准符合性说明:https://datatracker.ietf.org/doc/html/rfc8259
//! * RFC 8259 要求 JSON 文档是有效 UTF-8,但对“属于封闭生态系统”的系统有所例外。作者不清楚这在标准规范中究竟意味着什么。本实现要求输入为有效 UTF-8。
//! * RFC 8259 对 \u 十六进制数字是否允许小写存在自相矛盾之处,但这可能是规范缺陷,其意图显然是允许小写。(RFC 5234 将 HEXDIG 定义为仅允许大写。)
//! * RFC 8259 提及“字符”时,本实现假定其实际含义是“Unicode 标量值”。参见 http://www.unicode.org/glossary/#unicode_scalar_value 。
//! * RFC 8259 未明确禁止 \u 转义序列中的未配对代理项,但含糊地暗示 \u 转义用于编码 Unicode“字符”(即 Unicode 标量值?),这意味着未配对代理项应被禁止。相比之下,ECMA-404(另一项与之竞争或兼容的 JSON 标准,JavaScript 的 JSON.parse() 遵循该标准)明确允许未配对代理项。本实现禁止 \u 序列中的未配对代理项:若 \u 序列出现高位代理项,其后必须立即跟随以 \u 形式表示的低位代理项。
//! * RFC 8259 允许实现“接受非 JSON 形式或扩展”,本实现均不接受。
//! * RFC 8259 允许实现限制“文本大小”“最大嵌套深度”“数值范围与精度”以及“字符串长度和字符内容”。除上述限制,以及嵌套深度需要分配内存外,此底层实现不施加这些限制。注意,此底层接口并不按数值解释数字,而是输出其原始文本形式,供上层代码解释。
//! * 此底层实现允许对象键重复,键值对按其在输入中出现的顺序输出。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

const Scanner = @This();
const std = @import("std");

const Allocator = std.mem.Allocator;
const assert = std.debug.assert;
const BitStack = std.BitStack;

state: State = .value,
string_is_object_key: bool = false,
stack: BitStack,
value_start: usize = undefined,
utf16_code_units: [2]u16 = undefined,

input: []const u8 = "",
cursor: usize = 0,
is_end_of_input: bool = false,
diagnostics: ?*Diagnostics = null,

/// 分配器仅用于跟踪 `[]` 和 `{}` 的嵌套层级。
pub fn initStreaming(allocator: Allocator) @This() {
    return .{
        .stack = BitStack.init(allocator),
    };
}
/// 如果输入是单个切片,请使用此方法。
/// 这实际上等价于:
/// ```
/// initStreaming(allocator);
/// feedInput(complete_input);
/// endInput();
/// ```
pub fn initCompleteInput(allocator: Allocator, complete_input: []const u8) @This() {
    return .{
        .stack = BitStack.init(allocator),
        .input = complete_input,
        .is_end_of_input = true,
    };
}
pub fn deinit(self: *@This()) void {
    self.stack.deinit();
    self.* = undefined;
}

pub fn enableDiagnostics(self: *@This(), diagnostics: *Diagnostics) void {
    diagnostics.cursor_pointer = &self.cursor;
    self.diagnostics = diagnostics;
}

/// 每当从 `next()` 得到 `error.BufferUnderrun` 时调用此函数。
/// 没有更多输入可提供时,调用 `endInput()`。
pub fn feedInput(self: *@This(), input: []const u8) void {
    assert(self.cursor == self.input.len); // 尚未处理完上一个输入切片。
    if (self.diagnostics) |diag| {
        diag.total_bytes_before_current_input += self.input.len;
        // 此值通常变为“负数”,用于衡量当前行起点
        // 位于新缓冲区开头之前多远。
        diag.line_start_cursor -%= self.cursor;
    }
    self.input = input;
    self.cursor = 0;
    self.value_start = 0;
}
/// 不再调用 `feedInput()` 时调用此函数。
/// 可以在最后一次 `feedInput()` 之后立即调用,
/// 也可以稍后调用,例如当 `next()` 返回 `error.BufferUnderrun` 时。
/// 调用 `endInput()` 后,务必继续调用 `next*()`,直到获得 `.end_of_document`。
pub fn endInput(self: *@This()) void {
    self.is_end_of_input = true;
}

pub const NextError = Error || Allocator.Error || error{BufferUnderrun};
pub const AllocError = Error || Allocator.Error || error{ValueTooLong};
pub const PeekError = Error || error{BufferUnderrun};
pub const SkipError = Error || Allocator.Error;
pub const AllocIntoArrayListError = AllocError || error{BufferUnderrun};

/// 等同于 `nextAllocMax(allocator, when, default_max_value_len);`。
/// 只有调用 `endInput()` 或 `initCompleteInput()` 后才能使用此函数。
/// `nextAlloc*()` 函数行为的文档另请参见 `std.json.Token`。
pub fn nextAlloc(self: *@This(), allocator: Allocator, when: AllocWhen) AllocError!Token {
    return self.nextAllocMax(allocator, when, default_max_value_len);
}

/// 此函数仅在调用 `endInput()`(或 `initCompleteInput()`)后可用。
/// 有关 `nextAlloc*()` 函数行为的文档,另见 `std.json.Token`。
pub fn nextAllocMax(self: *@This(), allocator: Allocator, when: AllocWhen, max_value_len: usize) AllocError!Token {
    assert(self.is_end_of_input); // 此函数在流式模式下不可用。
    const token_type = self.peekNextTokenType() catch |e| switch (e) {
        error.BufferUnderrun => unreachable,
        else => |err| return err,
    };
    switch (token_type) {
        .number, .string => {
            var value_list = std.array_list.Managed(u8).init(allocator);
            errdefer {
                value_list.deinit();
            }
            if (self.allocNextIntoArrayListMax(&value_list, when, max_value_len) catch |e| switch (e) {
                error.BufferUnderrun => unreachable,
                else => |err| return err,
            }) |slice| {
                return if (token_type == .number)
                    Token{ .number = slice }
                else
                    Token{ .string = slice };
            } else {
                return if (token_type == .number)
                    Token{ .allocated_number = try value_list.toOwnedSlice() }
                else
                    Token{ .allocated_string = try value_list.toOwnedSlice() };
            }
        },

        // 简单词元从不分配内存。
        .object_begin,
        .object_end,
        .array_begin,
        .array_end,
        .true,
        .false,
        .null,
        .end_of_document,
        => return self.next() catch |e| switch (e) {
            error.BufferUnderrun => unreachable,
            else => |err| return err,
        },
    }
}

/// 等价于 `allocNextIntoArrayListMax(value_list, when, default_max_value_len);`。
pub fn allocNextIntoArrayList(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen) AllocIntoArrayListError!?[]const u8 {
    return self.allocNextIntoArrayListMax(value_list, when, default_max_value_len);
}
/// 下一个标记的类型必须为 `.number` 或 `.string`。参见 `peekNextTokenType()`。
/// 采用 `.alloc_if_needed` 且无需分配时,
/// 此方法返回输入缓冲区中的内容切片,不修改 `value_list`。
/// 需要分配或采用 `.alloc_always` 时,此方法将部分标记拼接到给定的 `value_list` 中,
/// 返回 `null` 的条件是最终的 `.number` 或 `.string` 标记已写入。
/// 发生 `error.BufferUnderrun` 时,部分值会保留在给定的 value_list 中。
/// 此方法从不重置给定的 `value_list`,因此发生 `error.BufferUnderrun` 后,
/// 可再次传入同一数组列表来继续处理。
/// 此方法不会指出返回内容属于 `.number` 还是 `.string` 标记类型;
/// 调用方应自行知道当前处理的标记类型。
pub fn allocNextIntoArrayListMax(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen, max_value_len: usize) AllocIntoArrayListError!?[]const u8 {
    while (true) {
        const token = try self.next();
        switch (token) {
            // 累积部分值。
            .partial_number, .partial_string => |slice| {
                try appendSlice(value_list, slice, max_value_len);
            },
            .partial_string_escaped_1 => |buf| {
                try appendSlice(value_list, buf[0..], max_value_len);
            },
            .partial_string_escaped_2 => |buf| {
                try appendSlice(value_list, buf[0..], max_value_len);
            },
            .partial_string_escaped_3 => |buf| {
                try appendSlice(value_list, buf[0..], max_value_len);
            },
            .partial_string_escaped_4 => |buf| {
                try appendSlice(value_list, buf[0..], max_value_len);
            },

            // 返回完整的值。
            .number => |slice| {
                if (when == .alloc_if_needed and value_list.items.len == 0) {
                    // 无需分配。
                    return slice;
                }
                try appendSlice(value_list, slice, max_value_len);
                // 词法标记已完整。
                return null;
            },
            .string => |slice| {
                if (when == .alloc_if_needed and value_list.items.len == 0) {
                    // 无需分配。
                    return slice;
                }
                try appendSlice(value_list, slice, max_value_len);
                // 词法标记已完整。
                return null;
            },

            .object_begin,
            .object_end,
            .array_begin,
            .array_end,
            .true,
            .false,
            .null,
            .end_of_document,
            => unreachable, // 这里只允许 .number 和 .string 词法标记类型。调用前请检查 peekNextTokenType()。

            .allocated_number, .allocated_string => unreachable,
        }
    }
}

/// 只有调用 `endInput()` 或 `initCompleteInput()` 后才能使用此函数。
/// 如果下一个词元类型为 `.object_begin` 或 `.array_begin`,
/// 则反复调用 `next()`,直到找到对应的 `.object_end` 或 `.array_end`。
/// 如果下一个词元类型为 `.number` 或 `.string`,
/// 则反复调用 `next()`,直到找到非 `.partial_*` 的 `.number` 或 `.string` 词元。
/// 如果下一个词元类型为 `.true`、`.false` 或 `.null`,则调用一次 `next()`。
/// 下一个词元类型不得为 `.object_end`、`.array_end` 或 `.end_of_document`;
/// 参见 `peekNextTokenType()`。
pub fn skipValue(self: *@This()) SkipError!void {
    assert(self.is_end_of_input); // 此函数在流式模式下不可用。
    switch (self.peekNextTokenType() catch |e| switch (e) {
        error.BufferUnderrun => unreachable,
        else => |err| return err,
    }) {
        .object_begin, .array_begin => {
            self.skipUntilStackHeight(self.stackHeight()) catch |e| switch (e) {
                error.BufferUnderrun => unreachable,
                else => |err| return err,
            };
        },
        .number, .string => {
            while (true) {
                switch (self.next() catch |e| switch (e) {
                    error.BufferUnderrun => unreachable,
                    else => |err| return err,
                }) {
                    .partial_number,
                    .partial_string,
                    .partial_string_escaped_1,
                    .partial_string_escaped_2,
                    .partial_string_escaped_3,
                    .partial_string_escaped_4,
                    => continue,

                    .number, .string => break,

                    else => unreachable,
                }
            }
        },
        .true, .false, .null => {
            _ = self.next() catch |e| switch (e) {
                error.BufferUnderrun => unreachable,
                else => |err| return err,
            };
        },

        .object_end, .array_end, .end_of_document => unreachable, // 尝试跳过非值词元。
    }
}

/// 跳过标记,直到某个 `.object_end` 或 `.array_end` 标记使 `stackHeight()` 等于给定栈高度。
/// 与 `skipValue()` 不同,此函数可在流式模式下使用。
pub fn skipUntilStackHeight(self: *@This(), terminal_stack_height: usize) NextError!void {
    while (true) {
        switch (try self.next()) {
            .object_end, .array_end => {
                if (self.stackHeight() == terminal_stack_height) break;
            },
            .end_of_document => unreachable,
            else => continue,
        }
    }
}

/// 当前位置 `{}` 或 `[]` 的嵌套深度。
pub fn stackHeight(self: *const @This()) usize {
    return self.stack.bit_len;
}

/// 预先分配足以容纳给定嵌套层数的内存。
/// `stackHeight()` 不超过该数值时,不会发生分配。
pub fn ensureTotalStackCapacity(self: *@This(), height: usize) Allocator.Error!void {
    try self.stack.ensureTotalCapacity(height);
}

/// 此函数的文档见 `std.json.Token`。
pub fn next(self: *@This()) NextError!Token {
    state_loop: while (true) {
        switch (self.state) {
            .value => {
                switch (try self.skipWhitespaceExpectByte()) {
                    // 对象、数组
                    '{' => {
                        try self.stack.push(OBJECT_MODE);
                        self.cursor += 1;
                        self.state = .object_start;
                        return .object_begin;
                    },
                    '[' => {
                        try self.stack.push(ARRAY_MODE);
                        self.cursor += 1;
                        self.state = .array_start;
                        return .array_begin;
                    },

                    // 字符串
                    '"' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        continue :state_loop;
                    },

                    // 数字
                    '1'...'9' => {
                        self.value_start = self.cursor;
                        self.cursor += 1;
                        self.state = .number_int;
                        continue :state_loop;
                    },
                    '0' => {
                        self.value_start = self.cursor;
                        self.cursor += 1;
                        self.state = .number_leading_zero;
                        continue :state_loop;
                    },
                    '-' => {
                        self.value_start = self.cursor;
                        self.cursor += 1;
                        self.state = .number_minus;
                        continue :state_loop;
                    },

                    // 字面量值
                    't' => {
                        self.cursor += 1;
                        self.state = .literal_t;
                        continue :state_loop;
                    },
                    'f' => {
                        self.cursor += 1;
                        self.state = .literal_f;
                        continue :state_loop;
                    },
                    'n' => {
                        self.cursor += 1;
                        self.state = .literal_n;
                        continue :state_loop;
                    },

                    else => return error.SyntaxError,
                }
            },

            .post_value => {
                if (try self.skipWhitespaceCheckEnd()) return .end_of_document;

                const c = self.input[self.cursor];
                if (self.string_is_object_key) {
                    self.string_is_object_key = false;
                    switch (c) {
                        ':' => {
                            self.cursor += 1;
                            self.state = .value;
                            continue :state_loop;
                        },
                        else => return error.SyntaxError,
                    }
                }

                switch (c) {
                    '}' => {
                        if (self.stack.pop() != OBJECT_MODE) return error.SyntaxError;
                        self.cursor += 1;
                        // 保持 .post_value 状态。
                        return .object_end;
                    },
                    ']' => {
                        if (self.stack.pop() != ARRAY_MODE) return error.SyntaxError;
                        self.cursor += 1;
                        // 保持 .post_value 状态。
                        return .array_end;
                    },
                    ',' => {
                        switch (self.stack.peek()) {
                            OBJECT_MODE => {
                                self.state = .object_post_comma;
                            },
                            ARRAY_MODE => {
                                self.state = .value;
                            },
                        }
                        self.cursor += 1;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },

            .object_start => {
                switch (try self.skipWhitespaceExpectByte()) {
                    '"' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        self.string_is_object_key = true;
                        continue :state_loop;
                    },
                    '}' => {
                        self.cursor += 1;
                        _ = self.stack.pop();
                        self.state = .post_value;
                        return .object_end;
                    },
                    else => return error.SyntaxError,
                }
            },
            .object_post_comma => {
                switch (try self.skipWhitespaceExpectByte()) {
                    '"' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        self.string_is_object_key = true;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },

            .array_start => {
                switch (try self.skipWhitespaceExpectByte()) {
                    ']' => {
                        self.cursor += 1;
                        _ = self.stack.pop();
                        self.state = .post_value;
                        return .array_end;
                    },
                    else => {
                        self.state = .value;
                        continue :state_loop;
                    },
                }
            },

            .number_minus => {
                if (self.cursor >= self.input.len) return self.endOfBufferInNumber(false);
                switch (self.input[self.cursor]) {
                    '0' => {
                        self.cursor += 1;
                        self.state = .number_leading_zero;
                        continue :state_loop;
                    },
                    '1'...'9' => {
                        self.cursor += 1;
                        self.state = .number_int;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .number_leading_zero => {
                if (self.cursor >= self.input.len) return self.endOfBufferInNumber(true);
                switch (self.input[self.cursor]) {
                    '.' => {
                        self.cursor += 1;
                        self.state = .number_post_dot;
                        continue :state_loop;
                    },
                    'e', 'E' => {
                        self.cursor += 1;
                        self.state = .number_post_e;
                        continue :state_loop;
                    },
                    else => {
                        self.state = .post_value;
                        return Token{ .number = self.takeValueSlice() };
                    },
                }
            },
            .number_int => {
                while (self.cursor < self.input.len) : (self.cursor += 1) {
                    switch (self.input[self.cursor]) {
                        '0'...'9' => continue,
                        '.' => {
                            self.cursor += 1;
                            self.state = .number_post_dot;
                            continue :state_loop;
                        },
                        'e', 'E' => {
                            self.cursor += 1;
                            self.state = .number_post_e;
                            continue :state_loop;
                        },
                        else => {
                            self.state = .post_value;
                            return Token{ .number = self.takeValueSlice() };
                        },
                    }
                }
                return self.endOfBufferInNumber(true);
            },
            .number_post_dot => {
                if (self.cursor >= self.input.len) return self.endOfBufferInNumber(false);
                switch (self.input[self.cursor]) {
                    '0'...'9' => {
                        self.cursor += 1;
                        self.state = .number_frac;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .number_frac => {
                while (self.cursor < self.input.len) : (self.cursor += 1) {
                    switch (self.input[self.cursor]) {
                        '0'...'9' => continue,
                        'e', 'E' => {
                            self.cursor += 1;
                            self.state = .number_post_e;
                            continue :state_loop;
                        },
                        else => {
                            self.state = .post_value;
                            return Token{ .number = self.takeValueSlice() };
                        },
                    }
                }
                return self.endOfBufferInNumber(true);
            },
            .number_post_e => {
                if (self.cursor >= self.input.len) return self.endOfBufferInNumber(false);
                switch (self.input[self.cursor]) {
                    '0'...'9' => {
                        self.cursor += 1;
                        self.state = .number_exp;
                        continue :state_loop;
                    },
                    '+', '-' => {
                        self.cursor += 1;
                        self.state = .number_post_e_sign;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .number_post_e_sign => {
                if (self.cursor >= self.input.len) return self.endOfBufferInNumber(false);
                switch (self.input[self.cursor]) {
                    '0'...'9' => {
                        self.cursor += 1;
                        self.state = .number_exp;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .number_exp => {
                while (self.cursor < self.input.len) : (self.cursor += 1) {
                    switch (self.input[self.cursor]) {
                        '0'...'9' => continue,
                        else => {
                            self.state = .post_value;
                            return Token{ .number = self.takeValueSlice() };
                        },
                    }
                }
                return self.endOfBufferInNumber(true);
            },

            .string => {
                while (self.cursor < self.input.len) : (self.cursor += 1) {
                    switch (self.input[self.cursor]) {
                        0...0x1f => return error.SyntaxError, // 字符串中存在未转义的 ASCII 控制码。

                        // ASCII 纯文本。
                        0x20...('"' - 1), ('"' + 1)...('\\' - 1), ('\\' + 1)...0x7F => continue,

                        // 特殊字符。
                        '"' => {
                            const result = Token{ .string = self.takeValueSlice() };
                            self.cursor += 1;
                            self.state = .post_value;
                            return result;
                        },
                        '\\' => {
                            const slice = self.takeValueSlice();
                            self.cursor += 1;
                            self.state = .string_backslash;
                            if (slice.len > 0) return Token{ .partial_string = slice };
                            continue :state_loop;
                        },

                        // UTF-8 验证。
                        // 参见 http://unicode.org/mail-arch/unicode-ml/y2003-m02/att-0467/01-The_Algorithm_to_Valide_an_UTF-8_String
                        0xC2...0xDF => {
                            self.cursor += 1;
                            self.state = .string_utf8_last_byte;
                            continue :state_loop;
                        },
                        0xE0 => {
                            self.cursor += 1;
                            self.state = .string_utf8_second_to_last_byte_guard_against_overlong;
                            continue :state_loop;
                        },
                        0xE1...0xEC, 0xEE...0xEF => {
                            self.cursor += 1;
                            self.state = .string_utf8_second_to_last_byte;
                            continue :state_loop;
                        },
                        0xED => {
                            self.cursor += 1;
                            self.state = .string_utf8_second_to_last_byte_guard_against_surrogate_half;
                            continue :state_loop;
                        },
                        0xF0 => {
                            self.cursor += 1;
                            self.state = .string_utf8_third_to_last_byte_guard_against_overlong;
                            continue :state_loop;
                        },
                        0xF1...0xF3 => {
                            self.cursor += 1;
                            self.state = .string_utf8_third_to_last_byte;
                            continue :state_loop;
                        },
                        0xF4 => {
                            self.cursor += 1;
                            self.state = .string_utf8_third_to_last_byte_guard_against_too_large;
                            continue :state_loop;
                        },
                        0x80...0xC1, 0xF5...0xFF => return error.SyntaxError, // 无效的 UTF-8。
                    }
                }
                if (self.is_end_of_input) return error.UnexpectedEndOfInput;
                const slice = self.takeValueSlice();
                if (slice.len > 0) return Token{ .partial_string = slice };
                return error.BufferUnderrun;
            },
            .string_backslash => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    '"', '\\', '/' => {
                        // 由于这些字符现在按字面表示自身,
                        // 可直接从此处开始下一个明文切片。
                        self.value_start = self.cursor;
                        self.cursor += 1;
                        self.state = .string;
                        continue :state_loop;
                    },
                    'b' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        return Token{ .partial_string_escaped_1 = [_]u8{0x08} };
                    },
                    'f' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        return Token{ .partial_string_escaped_1 = [_]u8{0x0c} };
                    },
                    'n' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        return Token{ .partial_string_escaped_1 = [_]u8{'\n'} };
                    },
                    'r' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        return Token{ .partial_string_escaped_1 = [_]u8{'\r'} };
                    },
                    't' => {
                        self.cursor += 1;
                        self.value_start = self.cursor;
                        self.state = .string;
                        return Token{ .partial_string_escaped_1 = [_]u8{'\t'} };
                    },
                    'u' => {
                        self.cursor += 1;
                        self.state = .string_backslash_u;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .string_backslash_u => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                const c = self.input[self.cursor];
                switch (c) {
                    '0'...'9' => {
                        self.utf16_code_units[0] = @as(u16, c - '0') << 12;
                    },
                    'A'...'F' => {
                        self.utf16_code_units[0] = @as(u16, c - 'A' + 10) << 12;
                    },
                    'a'...'f' => {
                        self.utf16_code_units[0] = @as(u16, c - 'a' + 10) << 12;
                    },
                    else => return error.SyntaxError,
                }
                self.cursor += 1;
                self.state = .string_backslash_u_1;
                continue :state_loop;
            },
            .string_backslash_u_1 => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                const c = self.input[self.cursor];
                switch (c) {
                    '0'...'9' => {
                        self.utf16_code_units[0] |= @as(u16, c - '0') << 8;
                    },
                    'A'...'F' => {
                        self.utf16_code_units[0] |= @as(u16, c - 'A' + 10) << 8;
                    },
                    'a'...'f' => {
                        self.utf16_code_units[0] |= @as(u16, c - 'a' + 10) << 8;
                    },
                    else => return error.SyntaxError,
                }
                self.cursor += 1;
                self.state = .string_backslash_u_2;
                continue :state_loop;
            },
            .string_backslash_u_2 => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                const c = self.input[self.cursor];
                switch (c) {
                    '0'...'9' => {
                        self.utf16_code_units[0] |= @as(u16, c - '0') << 4;
                    },
                    'A'...'F' => {
                        self.utf16_code_units[0] |= @as(u16, c - 'A' + 10) << 4;
                    },
                    'a'...'f' => {
                        self.utf16_code_units[0] |= @as(u16, c - 'a' + 10) << 4;
                    },
                    else => return error.SyntaxError,
                }
                self.cursor += 1;
                self.state = .string_backslash_u_3;
                continue :state_loop;
            },
            .string_backslash_u_3 => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                const c = self.input[self.cursor];
                switch (c) {
                    '0'...'9' => {
                        self.utf16_code_units[0] |= c - '0';
                    },
                    'A'...'F' => {
                        self.utf16_code_units[0] |= c - 'A' + 10;
                    },
                    'a'...'f' => {
                        self.utf16_code_units[0] |= c - 'a' + 10;
                    },
                    else => return error.SyntaxError,
                }
                self.cursor += 1;
                if (std.unicode.utf16IsHighSurrogate(self.utf16_code_units[0])) {
                    self.state = .string_surrogate_half;
                    continue :state_loop;
                } else if (std.unicode.utf16IsLowSurrogate(self.utf16_code_units[0])) {
                    return error.SyntaxError; // 意外的低位代理项。
                } else {
                    self.value_start = self.cursor;
                    self.state = .string;
                    return partialStringCodepoint(self.utf16_code_units[0]);
                }
            },
            .string_surrogate_half => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    '\\' => {
                        self.cursor += 1;
                        self.state = .string_surrogate_half_backslash;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 预期为低代理项。
                }
            },
            .string_surrogate_half_backslash => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    'u' => {
                        self.cursor += 1;
                        self.state = .string_surrogate_half_backslash_u;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 预期为低代理项。
                }
            },
            .string_surrogate_half_backslash_u => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    'D', 'd' => {
                        self.cursor += 1;
                        self.utf16_code_units[1] = 0xD << 12;
                        self.state = .string_surrogate_half_backslash_u_1;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 预期为低代理项。
                }
            },
            .string_surrogate_half_backslash_u_1 => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                const c = self.input[self.cursor];
                switch (c) {
                    'C'...'F' => {
                        self.cursor += 1;
                        self.utf16_code_units[1] |= @as(u16, c - 'A' + 10) << 8;
                        self.state = .string_surrogate_half_backslash_u_2;
                        continue :state_loop;
                    },
                    'c'...'f' => {
                        self.cursor += 1;
                        self.utf16_code_units[1] |= @as(u16, c - 'a' + 10) << 8;
                        self.state = .string_surrogate_half_backslash_u_2;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 预期为低代理项。
                }
            },
            .string_surrogate_half_backslash_u_2 => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                const c = self.input[self.cursor];
                switch (c) {
                    '0'...'9' => {
                        self.cursor += 1;
                        self.utf16_code_units[1] |= @as(u16, c - '0') << 4;
                        self.state = .string_surrogate_half_backslash_u_3;
                        continue :state_loop;
                    },
                    'A'...'F' => {
                        self.cursor += 1;
                        self.utf16_code_units[1] |= @as(u16, c - 'A' + 10) << 4;
                        self.state = .string_surrogate_half_backslash_u_3;
                        continue :state_loop;
                    },
                    'a'...'f' => {
                        self.cursor += 1;
                        self.utf16_code_units[1] |= @as(u16, c - 'a' + 10) << 4;
                        self.state = .string_surrogate_half_backslash_u_3;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .string_surrogate_half_backslash_u_3 => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                const c = self.input[self.cursor];
                switch (c) {
                    '0'...'9' => {
                        self.utf16_code_units[1] |= c - '0';
                    },
                    'A'...'F' => {
                        self.utf16_code_units[1] |= c - 'A' + 10;
                    },
                    'a'...'f' => {
                        self.utf16_code_units[1] |= c - 'a' + 10;
                    },
                    else => return error.SyntaxError,
                }
                self.cursor += 1;
                self.value_start = self.cursor;
                self.state = .string;
                const code_point = std.unicode.utf16DecodeSurrogatePair(&self.utf16_code_units) catch unreachable;
                return partialStringCodepoint(code_point);
            },

            .string_utf8_last_byte => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    0x80...0xBF => {
                        self.cursor += 1;
                        self.state = .string;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 无效的 UTF-8。
                }
            },
            .string_utf8_second_to_last_byte => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    0x80...0xBF => {
                        self.cursor += 1;
                        self.state = .string_utf8_last_byte;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 无效的 UTF-8。
                }
            },
            .string_utf8_second_to_last_byte_guard_against_overlong => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    0xA0...0xBF => {
                        self.cursor += 1;
                        self.state = .string_utf8_last_byte;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 无效的 UTF-8。
                }
            },
            .string_utf8_second_to_last_byte_guard_against_surrogate_half => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    0x80...0x9F => {
                        self.cursor += 1;
                        self.state = .string_utf8_last_byte;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 无效的 UTF-8。
                }
            },
            .string_utf8_third_to_last_byte => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    0x80...0xBF => {
                        self.cursor += 1;
                        self.state = .string_utf8_second_to_last_byte;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 无效的 UTF-8。
                }
            },
            .string_utf8_third_to_last_byte_guard_against_overlong => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    0x90...0xBF => {
                        self.cursor += 1;
                        self.state = .string_utf8_second_to_last_byte;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 无效的 UTF-8。
                }
            },
            .string_utf8_third_to_last_byte_guard_against_too_large => {
                if (self.cursor >= self.input.len) return self.endOfBufferInString();
                switch (self.input[self.cursor]) {
                    0x80...0x8F => {
                        self.cursor += 1;
                        self.state = .string_utf8_second_to_last_byte;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError, // 无效的 UTF-8。
                }
            },

            .literal_t => {
                switch (try self.expectByte()) {
                    'r' => {
                        self.cursor += 1;
                        self.state = .literal_tr;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_tr => {
                switch (try self.expectByte()) {
                    'u' => {
                        self.cursor += 1;
                        self.state = .literal_tru;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_tru => {
                switch (try self.expectByte()) {
                    'e' => {
                        self.cursor += 1;
                        self.state = .post_value;
                        return .true;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_f => {
                switch (try self.expectByte()) {
                    'a' => {
                        self.cursor += 1;
                        self.state = .literal_fa;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_fa => {
                switch (try self.expectByte()) {
                    'l' => {
                        self.cursor += 1;
                        self.state = .literal_fal;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_fal => {
                switch (try self.expectByte()) {
                    's' => {
                        self.cursor += 1;
                        self.state = .literal_fals;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_fals => {
                switch (try self.expectByte()) {
                    'e' => {
                        self.cursor += 1;
                        self.state = .post_value;
                        return .false;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_n => {
                switch (try self.expectByte()) {
                    'u' => {
                        self.cursor += 1;
                        self.state = .literal_nu;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_nu => {
                switch (try self.expectByte()) {
                    'l' => {
                        self.cursor += 1;
                        self.state = .literal_nul;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },
            .literal_nul => {
                switch (try self.expectByte()) {
                    'l' => {
                        self.cursor += 1;
                        self.state = .post_value;
                        return .null;
                    },
                    else => return error.SyntaxError,
                }
            },
        }
        unreachable;
    }
}

/// 在输入中向前扫描,直到下一个词元的首字节或输入末尾,
/// 确定下次调用 `next*()` 将返回的词元类型。
/// 此函数幂等,只会越过逗号、冒号及词元之间的空白。
pub fn peekNextTokenType(self: *@This()) PeekError!TokenType {
    state_loop: while (true) {
        switch (self.state) {
            .value => {
                switch (try self.skipWhitespaceExpectByte()) {
                    '{' => return .object_begin,
                    '[' => return .array_begin,
                    '"' => return .string,
                    '-', '0'...'9' => return .number,
                    't' => return .true,
                    'f' => return .false,
                    'n' => return .null,
                    else => return error.SyntaxError,
                }
            },

            .post_value => {
                if (try self.skipWhitespaceCheckEnd()) return .end_of_document;

                const c = self.input[self.cursor];
                if (self.string_is_object_key) {
                    self.string_is_object_key = false;
                    switch (c) {
                        ':' => {
                            self.cursor += 1;
                            self.state = .value;
                            continue :state_loop;
                        },
                        else => return error.SyntaxError,
                    }
                }

                switch (c) {
                    '}' => return .object_end,
                    ']' => return .array_end,
                    ',' => {
                        switch (self.stack.peek()) {
                            OBJECT_MODE => {
                                self.state = .object_post_comma;
                            },
                            ARRAY_MODE => {
                                self.state = .value;
                            },
                        }
                        self.cursor += 1;
                        continue :state_loop;
                    },
                    else => return error.SyntaxError,
                }
            },

            .object_start => {
                switch (try self.skipWhitespaceExpectByte()) {
                    '"' => return .string,
                    '}' => return .object_end,
                    else => return error.SyntaxError,
                }
            },
            .object_post_comma => {
                switch (try self.skipWhitespaceExpectByte()) {
                    '"' => return .string,
                    else => return error.SyntaxError,
                }
            },

            .array_start => {
                switch (try self.skipWhitespaceExpectByte()) {
                    ']' => return .array_end,
                    else => {
                        self.state = .value;
                        continue :state_loop;
                    },
                }
            },

            .number_minus,
            .number_leading_zero,
            .number_int,
            .number_post_dot,
            .number_frac,
            .number_post_e,
            .number_post_e_sign,
            .number_exp,
            => return .number,

            .string,
            .string_backslash,
            .string_backslash_u,
            .string_backslash_u_1,
            .string_backslash_u_2,
            .string_backslash_u_3,
            .string_surrogate_half,
            .string_surrogate_half_backslash,
            .string_surrogate_half_backslash_u,
            .string_surrogate_half_backslash_u_1,
            .string_surrogate_half_backslash_u_2,
            .string_surrogate_half_backslash_u_3,
            => return .string,

            .string_utf8_last_byte,
            .string_utf8_second_to_last_byte,
            .string_utf8_second_to_last_byte_guard_against_overlong,
            .string_utf8_second_to_last_byte_guard_against_surrogate_half,
            .string_utf8_third_to_last_byte,
            .string_utf8_third_to_last_byte_guard_against_overlong,
            .string_utf8_third_to_last_byte_guard_against_too_large,
            => return .string,

            .literal_t,
            .literal_tr,
            .literal_tru,
            => return .true,
            .literal_f,
            .literal_fa,
            .literal_fal,
            .literal_fals,
            => return .false,
            .literal_n,
            .literal_nu,
            .literal_nul,
            => return .null,
        }
        unreachable;
    }
}

const State = enum {
    value,
    post_value,

    object_start,
    object_post_comma,

    array_start,

    number_minus,
    number_leading_zero,
    number_int,
    number_post_dot,
    number_frac,
    number_post_e,
    number_post_e_sign,
    number_exp,

    string,
    string_backslash,
    string_backslash_u,
    string_backslash_u_1,
    string_backslash_u_2,
    string_backslash_u_3,
    string_surrogate_half,
    string_surrogate_half_backslash,
    string_surrogate_half_backslash_u,
    string_surrogate_half_backslash_u_1,
    string_surrogate_half_backslash_u_2,
    string_surrogate_half_backslash_u_3,

    // 取自 http://unicode.org/mail-arch/unicode-ml/y2003-m02/att-0467/01-The_Algorithm_to_Valide_an_UTF-8_String
    string_utf8_last_byte, // 状态 A
    string_utf8_second_to_last_byte, // 状态 B
    string_utf8_second_to_last_byte_guard_against_overlong, // 状态 C
    string_utf8_second_to_last_byte_guard_against_surrogate_half, // 状态 D
    string_utf8_third_to_last_byte, // 状态 E
    string_utf8_third_to_last_byte_guard_against_overlong, // 状态 F
    string_utf8_third_to_last_byte_guard_against_too_large, // 状态 G

    literal_t,
    literal_tr,
    literal_tru,
    literal_f,
    literal_fa,
    literal_fal,
    literal_fals,
    literal_n,
    literal_nu,
    literal_nul,
};

fn expectByte(self: *const @This()) !u8 {
    if (self.cursor < self.input.len) {
        return self.input[self.cursor];
    }
    // 无字节。
    if (self.is_end_of_input) return error.UnexpectedEndOfInput;
    return error.BufferUnderrun;
}

fn skipWhitespace(self: *@This()) void {
    while (self.cursor < self.input.len) : (self.cursor += 1) {
        switch (self.input[self.cursor]) {
            // 空白字符
            ' ', '\t', '\r' => continue,
            '\n' => {
                if (self.diagnostics) |diag| {
                    diag.line_number += 1;
                    // 这里会计入换行符本身,
                    // 因此直接相减即可得到从 1 开始的列号。
                    diag.line_start_cursor = self.cursor;
                }
                continue;
            },
            else => return,
        }
    }
}

fn skipWhitespaceExpectByte(self: *@This()) !u8 {
    self.skipWhitespace();
    return self.expectByte();
}

fn skipWhitespaceCheckEnd(self: *@This()) !bool {
    self.skipWhitespace();
    if (self.cursor >= self.input.len) {
        // 缓冲区末尾。
        if (self.is_end_of_input) {
            // 所有内容的末尾。
            if (self.stackHeight() == 0) {
                // 成功了!
                return true;
            }
            return error.UnexpectedEndOfInput;
        }
        return error.BufferUnderrun;
    }
    if (self.stackHeight() == 0) return error.SyntaxError;
    return false;
}

fn takeValueSlice(self: *@This()) []const u8 {
    const slice = self.input[self.value_start..self.cursor];
    self.value_start = self.cursor;
    return slice;
}
fn takeValueSliceMinusTrailingOffset(self: *@This(), trailing_negative_offset: usize) []const u8 {
    // 检查转义序列是否始于当前输入缓冲区之前。
    // 此处的代数形式为避免无符号下溢而较为复杂,
    // 但目的只是保证下一行的切片不引发未定义行为。
    if (self.cursor <= self.value_start + trailing_negative_offset) return "";
    const slice = self.input[self.value_start .. self.cursor - trailing_negative_offset];
    // trailing_negative_offset 非零时,设置 self.value_start 没有影响,
    // 因为生成 .partial_string_escaped_* 时总会再次设置它。
    self.value_start = self.cursor;
    return slice;
}

fn endOfBufferInNumber(self: *@This(), allow_end: bool) !Token {
    const slice = self.takeValueSlice();
    if (self.is_end_of_input) {
        if (!allow_end) return error.UnexpectedEndOfInput;
        self.state = .post_value;
        return Token{ .number = slice };
    }
    if (slice.len == 0) return error.BufferUnderrun;
    return Token{ .partial_number = slice };
}

fn endOfBufferInString(self: *@This()) !Token {
    if (self.is_end_of_input) return error.UnexpectedEndOfInput;
    const slice = self.takeValueSliceMinusTrailingOffset(switch (self.state) {
        // 不要在部分字符串中包含转义序列。
        .string_backslash => 1,
        .string_backslash_u => 2,
        .string_backslash_u_1 => 3,
        .string_backslash_u_2 => 4,
        .string_backslash_u_3 => 5,
        .string_surrogate_half => 6,
        .string_surrogate_half_backslash => 7,
        .string_surrogate_half_backslash_u => 8,
        .string_surrogate_half_backslash_u_1 => 9,
        .string_surrogate_half_backslash_u_2 => 10,
        .string_surrogate_half_backslash_u_3 => 11,

        // 否则,包含游标之前的所有内容。
        .string,
        .string_utf8_last_byte,
        .string_utf8_second_to_last_byte,
        .string_utf8_second_to_last_byte_guard_against_overlong,
        .string_utf8_second_to_last_byte_guard_against_surrogate_half,
        .string_utf8_third_to_last_byte,
        .string_utf8_third_to_last_byte_guard_against_overlong,
        .string_utf8_third_to_last_byte_guard_against_too_large,
        => 0,

        else => unreachable,
    });
    if (slice.len == 0) return error.BufferUnderrun;
    return Token{ .partial_string = slice };
}

fn partialStringCodepoint(code_point: u21) Token {
    var buf: [4]u8 = undefined;
    switch (std.unicode.utf8Encode(code_point, &buf) catch unreachable) {
        1 => return Token{ .partial_string_escaped_1 = buf[0..1].* },
        2 => return Token{ .partial_string_escaped_2 = buf[0..2].* },
        3 => return Token{ .partial_string_escaped_3 = buf[0..3].* },
        4 => return Token{ .partial_string_escaped_4 = buf[0..4].* },
        else => unreachable,
    }
}

/// 扫描输入,检查 JSON 格式是否有误。
/// 遇到 `SyntaxError` 或 `UnexpectedEndOfInput` 时返回 `false`。
/// 原样返回分配器的任何错误;这种情况不太常见,
/// 但输入嵌套极深时可能发生。
pub fn validate(allocator: Allocator, s: []const u8) Allocator.Error!bool {
    var scanner = Scanner.initCompleteInput(allocator, s);
    defer scanner.deinit();

    while (true) {
        const token = scanner.next() catch |err| switch (err) {
            error.SyntaxError, error.UnexpectedEndOfInput => return false,
            error.OutOfMemory => |e| return e,
            error.BufferUnderrun => unreachable,
        };
        if (token == .end_of_document) break;
    }

    return true;
}

/// 解析错误分为两类:
///  * `SyntaxError` 表示明显格式错误的 JSON 文档,
///    例如输入文档根本不是 JSON。
///  * `UnexpectedEndOfInput` 表示此前的内容均
///    有效,但输入似乎因某种原因被截断。
/// 注意,完全为空或仅包含空白的输入会产生 `UnexpectedEndOfInput`。
pub const Error = error{ SyntaxError, UnexpectedEndOfInput };

/// 由 `json.reader` 使用。
pub const default_buffer_size = 0x1000;

/// `std.json.Scanner` 和 `std.json.Reader` 的 `.next*()` 函数生成的标记遵循以下语法:
/// ```
///  <document> = <value> .end_of_document
///  <value> =
///    | <object>
///    | <array>
///    | <number>
///    | <string>
///    | .true
///    | .false
///    | .null
///  <object> = .object_begin ( <string> <value> )* .object_end
///  <array> = .array_begin ( <value> )* .array_end
///  <number> = <It depends. See below.>
///  <string> = <It depends. See below.>
/// ```
///
/// `<number>` 和 `<string>` 的具体形式取决于调用哪个 `next*()` 方法:
///
/// ```
/// next():
///  <number> = ( .partial_number )* .number
///  <string> = ( <partial_string> )* .string
///  <partial_string> =
///    | .partial_string
///    | .partial_string_escaped_1
///    | .partial_string_escaped_2
///    | .partial_string_escaped_3
///    | .partial_string_escaped_4
///
/// nextAlloc*(..., .alloc_always):
///  <number> = .allocated_number
///  <string> = .allocated_string
///
/// nextAlloc*(..., .alloc_if_needed):
///  <number> =
///    | .number
///    | .allocated_number
///  <string> =
///    | .string
///    | .allocated_string
/// ```
///
/// 对于所有载荷类型为 `[]const u8`、`[]u8` 或 `[n]u8` 的标记,载荷表示该值的内容。数字载荷保留其在输入中的精确文本表示;字符串载荷则是解析转义序列后的内容。
///
/// 对于 `.allocated_number` 和 `.allocated_string`,`[]u8` 载荷由给定分配器分配。你负责管理这些内存;`json.Reader.deinit()` **不会**释放它们。
///
/// `.partial_*` 标记表示值跨越多个输入缓冲区,或者字符串包含转义序列。若要在内存中取得完整值,需要自行拼接;调用 `nextAlloc*()` 可以代为完成,并返回包含结果的 `.allocated_*` 标记。
///
/// 对于载荷为 `[]const u8` 的标记,载荷是当前输入缓冲区的切片。下一次调用 `json.Scanner.feedInput()`,或调用返回错误集合包含 `json.Error` 的任意 `json.Reader` 方法时,该内存可能变为未定义。若要持久保留值,建议复制,或使用会代为复制的 `.alloc_always`。
///
/// 注意,跟在 `.partial_*` 后的 `.number` 和 `.string` 标记长度可能为 `0`,表示之前的部分值已经完整,且没有额外字节。当输入缓冲区恰好在值的末尾分界时会出现这种情况,例如 `"[1234"`、`"]"`。`.partial_*` 标记的长度绝不会为 `0`。
///
/// 建议按如下策略使用不同的 `next*()` 方法:
///
/// 预期对象键时使用 `.alloc_if_needed`。通常无须长期保留键字符串的副本,只需检查它属于哪个字段;若键恰好需要分配内存,检查后立即释放。
///
/// 预期有实际含义的字符串值(例如 `:` 右侧)时,使用 `.alloc_always`,使其在继续解析文档其他部分时保持有效。
///
/// 预期数字值时,使用 `.alloc_if_needed`。通常会将数字字符串解析为数值,因此只临时需要完整字符串表示。
///
/// 跳过无法识别的值时,使用 `skipValue()`。
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
pub const Token = union(enum) {
    object_begin,
    object_end,
    array_begin,
    array_end,

    true,
    false,
    null,

    number: []const u8,
    partial_number: []const u8,
    allocated_number: []u8,

    string: []const u8,
    partial_string: []const u8,
    partial_string_escaped_1: [1]u8,
    partial_string_escaped_2: [2]u8,
    partial_string_escaped_3: [3]u8,
    partial_string_escaped_4: [4]u8,
    allocated_string: []u8,

    end_of_document,
};

/// 仅用于 `peekNextTokenType()`;根据 `next*()` 调用将生成的下一个标记的首字节进行分类。
pub const TokenType = enum {
    object_begin,
    object_end,
    array_begin,
    array_end,
    true,
    false,
    null,
    number,
    string,
    end_of_document,
};

/// 要启用诊断,请声明 `var diagnostics = Diagnostics{};`,然后调用 `source.enableDiagnostics(&diagnostics);`,
/// 其中 `source` 是刚初始化的 `std.json.Reader` 或 `std.json.Scanner`。
/// 在任意时刻,尤其是刚发生错误之后,调用 `getLine()`、`getColumn()` 和/或 `getByteOffset()`,
/// 即可取得有意义的信息。
pub const Diagnostics = struct {
    line_number: u64 = 1,
    line_start_cursor: usize = @as(usize, @bitCast(@as(isize, -1))), // 从输入缓冲区恰好“之前”开始,使第 1 行的列号从 1 起算。
    total_bytes_before_current_input: u64 = 0,
    cursor_pointer: *const usize = undefined,

    /// 从 1 开始。
    pub fn getLine(self: *const @This()) u64 {
        return self.line_number;
    }
    /// 从 1 开始。
    pub fn getColumn(self: *const @This()) u64 {
        return self.cursor_pointer.* -% self.line_start_cursor;
    }
    /// 从 0 开始。表示自输入起点以来的字节偏移。
    pub fn getByteOffset(self: *const @This()) u64 {
        return self.total_bytes_before_current_input + self.cursor_pointer.*;
    }
};

/// 参见 `std.json.Token` 的文档。
pub const AllocWhen = enum { alloc_if_needed, alloc_always };

/// 为保证安全,默认将单个字符串或数值的存储分配大小上限设为 4MiB。
/// 可通过调用 `nextAllocMax()` 而非 `nextAlloc()` 指定此限制。
pub const default_max_value_len = 4 * 1024 * 1024;

/// 此处所有 `next*()` 方法均处理来自 `std.json.Scanner` 的 `error.BufferUnderrun`,然后从读取器读取。
pub const Reader = struct {
    scanner: Scanner,
    reader: *std.Io.Reader,

    /// 分配器仅用于跟踪 `[]` 和 `{}` 的嵌套层级。
    pub fn init(allocator: Allocator, io_reader: *std.Io.Reader) @This() {
        return .{
            .scanner = Scanner.initStreaming(allocator),
            .reader = io_reader,
        };
    }
    pub fn deinit(self: *@This()) void {
        self.scanner.deinit();
        self.* = undefined;
    }

    /// 调用 `std.json.Scanner.enableDiagnostics`。
    pub fn enableDiagnostics(self: *@This(), diagnostics: *Diagnostics) void {
        self.scanner.enableDiagnostics(diagnostics);
    }

    pub const NextError = std.Io.Reader.Error || Error || Allocator.Error;
    pub const SkipError = Reader.NextError;
    pub const AllocError = Reader.NextError || error{ValueTooLong};
    pub const PeekError = std.Io.Reader.Error || Error;

    /// 等同于 `nextAllocMax(allocator, when, default_max_value_len);`
    /// `nextAlloc*()` 函数的行为文档另见 `std.json.Token`。
    pub fn nextAlloc(self: *@This(), allocator: Allocator, when: AllocWhen) Reader.AllocError!Token {
        return self.nextAllocMax(allocator, when, default_max_value_len);
    }
    /// 关于 `nextAlloc*()` 函数行为的文档,另请参见 `std.json.Token`。
    pub fn nextAllocMax(self: *@This(), allocator: Allocator, when: AllocWhen, max_value_len: usize) Reader.AllocError!Token {
        const token_type = try self.peekNextTokenType();
        switch (token_type) {
            .number, .string => {
                var value_list = std.array_list.Managed(u8).init(allocator);
                errdefer {
                    value_list.deinit();
                }
                if (try self.allocNextIntoArrayListMax(&value_list, when, max_value_len)) |slice| {
                    return if (token_type == .number)
                        Token{ .number = slice }
                    else
                        Token{ .string = slice };
                } else {
                    return if (token_type == .number)
                        Token{ .allocated_number = try value_list.toOwnedSlice() }
                    else
                        Token{ .allocated_string = try value_list.toOwnedSlice() };
                }
            },

            // 简单词元从不分配内存。
            .object_begin,
            .object_end,
            .array_begin,
            .array_end,
            .true,
            .false,
            .null,
            .end_of_document,
            => return try self.next(),
        }
    }

    /// 等价于 `allocNextIntoArrayListMax(value_list, when, default_max_value_len);`。
    pub fn allocNextIntoArrayList(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen) Reader.AllocError!?[]const u8 {
        return self.allocNextIntoArrayListMax(value_list, when, default_max_value_len);
    }
    /// 调用 `std.json.Scanner.allocNextIntoArrayListMax`,并处理 `error.BufferUnderrun`。
    pub fn allocNextIntoArrayListMax(self: *@This(), value_list: *std.array_list.Managed(u8), when: AllocWhen, max_value_len: usize) Reader.AllocError!?[]const u8 {
        while (true) {
            return self.scanner.allocNextIntoArrayListMax(value_list, when, max_value_len) catch |err| switch (err) {
                error.BufferUnderrun => {
                    try self.refillBuffer();
                    continue;
                },
                else => |other_err| return other_err,
            };
        }
    }

    /// 类似于 `std.json.Scanner.skipValue`,但处理 `error.BufferUnderrun`。
    pub fn skipValue(self: *@This()) Reader.SkipError!void {
        switch (try self.peekNextTokenType()) {
            .object_begin, .array_begin => {
                try self.skipUntilStackHeight(self.stackHeight());
            },
            .number, .string => {
                while (true) {
                    switch (try self.next()) {
                        .partial_number,
                        .partial_string,
                        .partial_string_escaped_1,
                        .partial_string_escaped_2,
                        .partial_string_escaped_3,
                        .partial_string_escaped_4,
                        => continue,

                        .number, .string => break,

                        else => unreachable,
                    }
                }
            },
            .true, .false, .null => {
                _ = try self.next();
            },

            .object_end, .array_end, .end_of_document => unreachable, // 尝试跳过非值词元。
        }
    }
    /// 类似于 `std.json.Scanner.skipUntilStackHeight()`,但会处理 `error.BufferUnderrun`。
    pub fn skipUntilStackHeight(self: *@This(), terminal_stack_height: usize) Reader.NextError!void {
        while (true) {
            return self.scanner.skipUntilStackHeight(terminal_stack_height) catch |err| switch (err) {
                error.BufferUnderrun => {
                    try self.refillBuffer();
                    continue;
                },
                else => |other_err| return other_err,
            };
        }
    }

    /// 调用 `std.json.Scanner.stackHeight`。
    pub fn stackHeight(self: *const @This()) usize {
        return self.scanner.stackHeight();
    }
    /// 调用 `std.json.Scanner.ensureTotalStackCapacity`。
    pub fn ensureTotalStackCapacity(self: *@This(), height: usize) Allocator.Error!void {
        try self.scanner.ensureTotalStackCapacity(height);
    }

    /// 此函数的文档见 `std.json.Token`。
    pub fn next(self: *@This()) Reader.NextError!Token {
        while (true) {
            return self.scanner.next() catch |err| switch (err) {
                error.BufferUnderrun => {
                    try self.refillBuffer();
                    continue;
                },
                else => |other_err| return other_err,
            };
        }
    }

    /// 参见 `std.json.Scanner.peekNextTokenType()`。
    pub fn peekNextTokenType(self: *@This()) Reader.PeekError!TokenType {
        while (true) {
            return self.scanner.peekNextTokenType() catch |err| switch (err) {
                error.BufferUnderrun => {
                    try self.refillBuffer();
                    continue;
                },
                else => |other_err| return other_err,
            };
        }
    }

    fn refillBuffer(self: *@This()) std.Io.Reader.Error!void {
        const input = self.reader.peekGreedy(1) catch |err| switch (err) {
            error.ReadFailed => |e| return e,
            error.EndOfStream => return self.scanner.endInput(),
        };
        self.reader.toss(input.len);
        self.scanner.feedInput(input);
    }
};

const OBJECT_MODE = 0;
const ARRAY_MODE = 1;

fn appendSlice(list: *std.array_list.Managed(u8), buf: []const u8, max_value_len: usize) !void {
    const new_len = std.math.add(usize, list.items.len, buf.len) catch return error.ValueTooLong;
    if (new_len > max_value_len) return error.ValueTooLong;
    try list.appendSlice(buf);
}

/// 对于从 `Token.number` 或 `Token.allocated_number` 获取的切片,
/// 若数字不含小数部分或指数部分,且不是 `-0`,此函数返回 true。
/// 注意,所编码的数值本身仍可能是整数,例如 `1.0`。
/// 此函数用于提示应对该值使用整数解析还是浮点解析。
/// 对于非数字输入,结果无意义。
pub fn isNumberFormattedLikeAnInteger(value: []const u8) bool {
    if (std.mem.eql(u8, value, "-0")) return false;
    return std.mem.findAny(u8, value, ".eE") == null;
}

test {
    _ = @import("./scanner_test.zig");
}