字段
vtable: *const VTable
buffer: []u8
seek: usize已从 buffer 消费的字节数。
end: usizebuffer 中此位置之前是已缓冲的字节,之后是 undefined。
Readerbuiltinnative_endianstdWriterLimitasserttestingAllocatorArrayListLimitedVTableStreamErrorErrorStreamRemainingErrorShortErrorRebaseErrorfailingending_instanceendinglimitedfixedstreamdiscarddefaultDiscardstreamExactstreamExact64streamExactPreservestreamRemainingdiscardRemainingLimitedAllocErrorallocRemainingallocRemainingAlignedSentinelAppendExactErrorappendExactappendRemainingappendRemainingAlignedUnlimitedAllocErrorappendRemainingUnlimitedreadVecdefaultReadVecbufferedbufferedLenhashedreadVecAllpeekpeekGreedytosstossBufferedtaketakeArraypeekArraydiscardAlldiscardAll64discardShortreadSliceAllreadSliceShortreadSliceEndianReadAllocErrorreadSliceEndianAllocreadAllocreadAllocAllreadAllocShortDelimiterErrortakeSentinelpeekSentineltakeDelimiterInclusivepeekDelimiterInclusivetakeDelimiterExclusivetakeDelimiterpeekDelimiterExclusivestreamDelimiterstreamDelimiterEndingStreamDelimiterLimitErrorstreamDelimiterLimitdiscardDelimiterInclusivediscardDelimiterExclusiveDiscardDelimiterLimitErrordiscardDelimiterLimitfillfillUnbufferedfillMorepeekBytetakeBytetakeByteSignedtakeIntpeekInttakeVarInttakeStructPointerpeekStructPointertakeStructpeekStructTakeEnumErrortakeEnumtakeEnumNonexhaustiveTakeLeb128ErrortakeLeb128rebasedefaultRebaseendingStreamendingReadVecendingDiscardendingRebasefailingStreamfailingDiscardHashedwritableVectorPosixwritableVectorWsawritableVectortestLeb128testStreamExactPreserve
std.Io.Reader.Allocator
别名
别名目标 std.mem.Allocator
std.Io.Reader.allocRemaining
函数
从当前位置传输到流末尾的全部字节,最多
limit 个,并将它们作为调用方拥有的已分配切片返回。
若超过 limit,改为返回 error.StreamTooLong。
此时下一个待读字节位于第一个超出 limit
的字节之后,之前的所有字节均已丢弃。
另请参见:
pub fn allocRemaining(r: *Reader, gpa: Allocator, limit: Limit) LimitedAllocError![]u8
参数
错误
- OutOfMemory Error
- ReadFailed ShortError
详细诊断参见
Reader的实现。- StreamTooLong
用法示例
test allocRemaining {
{
var r: Reader = .fixed("abc");
const str = try r.allocRemaining(testing.allocator, .unlimited);
defer testing.allocator.free(str);
try testing.expectEqualStrings("abc", str);
}
{
var r: Reader = .fixed("abc");
const str = try r.allocRemaining(testing.allocator, .limited(5));
defer testing.allocator.free(str);
try testing.expectEqualStrings("abc", str);
}
{
var r: Reader = .fixed("abc");
const str = try r.allocRemaining(testing.allocator, .limited(3));
defer testing.allocator.free(str);
try testing.expectEqualStrings("abc", str);
}
{
var r: Reader = .fixed("abcd");
try testing.expectError(error.StreamTooLong, r.allocRemaining(testing.allocator, .limited(3)));
}
}
std.Io.Reader.allocRemainingAlignedSentinel
函数
pub fn allocRemainingAlignedSentinel( r: *Reader, gpa: Allocator, limit: Limit, comptime alignment: std.mem.Alignment, comptime sentinel: ?u8, ) LimitedAllocError!(if (sentinel) |s| [:s]align(alignment.toByteUnits()) u8 else []align(alignment.toByteUnits()) u8)
参数
错误
- OutOfMemory Error
- ReadFailed ShortError
详细诊断参见
Reader的实现。- StreamTooLong
std.Io.Reader.appendExact
函数
pub fn appendExact( r: *Reader, gpa: Allocator, list: *ArrayList(u8), n: usize, ) AppendExactError!void
参数
错误
std.Io.Reader.AppendExactError
错误集合
错误
std.Io.Reader.appendRemaining
函数
将当前位置到流末尾的所有字节追加到 list,
最多传输 limit。
如果达到或超过 limit,则改为返回 error.StreamTooLong。
此时下一个将要读取的字节是第一个
超出 limit 的字节,而此前所有字节均已追加到
list。
另请参见:
pub fn appendRemaining( r: *Reader, gpa: Allocator, list: *ArrayList(u8), limit: Limit, ) LimitedAllocError!void
参数
错误
- OutOfMemory Error
- ReadFailed ShortError
详细诊断参见
Reader的实现。- StreamTooLong
std.Io.Reader.appendRemainingAligned
函数
从当前位置传输字节直到流结束,最多 limit 字节,并追加到 list。
若达到或超过 limit,则改为返回 error.StreamTooLong。此时,下一个将读取的字节是首个超出 limit 的字节,此前的全部字节都已追加到 list。
另见:
appendRemainingallocRemainingAligned
pub fn appendRemainingAligned( r: *Reader, gpa: Allocator, comptime alignment: std.mem.Alignment, list: *std.array_list.Aligned(u8, alignment), limit: Limit, ) LimitedAllocError!void
参数
r: *Reader
gpa: Allocator
alignment: std.mem.Alignment
list: *std.array_list.Aligned(u8, alignment)
limit: Limit
错误
- OutOfMemory Error
- ReadFailed ShortError
详细诊断参见
Reader的实现。- StreamTooLong
std.Io.Reader.appendRemainingUnlimited
函数
pub fn appendRemainingUnlimited(r: *Reader, gpa: Allocator, list: *ArrayList(u8)) UnlimitedAllocError!void
参数
错误
- OutOfMemory Error
- ReadFailed ShortError
详细诊断参见
Reader的实现。
std.Io.Reader.ArrayList
别名
别名目标 std.ArrayList
std.Io.Reader.assert
别名
别名目标 std.debug.assert
std.Io.Reader.buffered
函数
pub fn buffered(r: *Reader) []u8
参数
r: *Reader
std.Io.Reader.bufferedLen
函数
pub fn bufferedLen(r: *const Reader) usize
参数
r: *const Reader
std.Io.Reader.builtin
常量
std.Io.Reader.defaultDiscard
函数
pub fn defaultDiscard(r: *Reader, limit: Limit) Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.defaultReadVec
函数
写入 Reader.buffer 或 data 中容量较大的一个。
pub fn defaultReadVec(r: *Reader, data: [][]u8) Error!usize
参数
r: *Reader
data: [][]u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.defaultRebase
函数
pub fn defaultRebase(r: *Reader, capacity: usize) Error!void
参数
r: *Reader
capacity: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.DelimiterError
错误集合
错误
std.Io.Reader.discard
函数
pub fn discard(r: *Reader, limit: Limit) Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.discardAll
函数
pub fn discardAll(r: *Reader, n: usize) Error!void
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test discardAll {
var r: Reader = .fixed("foobar");
try r.discardAll(3);
try testing.expectEqualStrings("bar", try r.take(3));
try r.discardAll(0);
try testing.expectError(error.EndOfStream, r.discardAll(1));
}
std.Io.Reader.discardAll64
函数
pub fn discardAll64(r: *Reader, n: u64) Error!void
参数
r: *Reader
n: u64
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.discardDelimiterExclusive
函数
从流中读取直到发现指定字节,丢弃所有数据, 但不包括分隔符。
返回丢弃的字节数。
在找到分隔符之前流就结束时也会成功。可通过检查 分隔符是否已缓冲来判断流是否结束。
另见:
pub fn discardDelimiterExclusive(r: *Reader, delimiter: u8) ShortError!usize
参数
r: *Reader
delimiter: u8
错误
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test discardDelimiterExclusive {
var r: Reader = .fixed("foob\nar");
try testing.expectEqual(4, try r.discardDelimiterExclusive('\n'));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqual(2, try r.discardDelimiterExclusive('\n'));
try testing.expectEqual(0, try r.discardDelimiterExclusive('\n'));
}
std.Io.Reader.discardDelimiterInclusive
函数
从流中读取直到找到指定字节,丢弃所有数据, 包括分隔符。
返回丢弃的字节数;未找到分隔符时返回 error.EndOfStream。
另见:
pub fn discardDelimiterInclusive(r: *Reader, delimiter: u8) Error!usize
参数
r: *Reader
delimiter: u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test discardDelimiterInclusive {
var r: Reader = .fixed("foob\nar");
try testing.expectEqual(5, try r.discardDelimiterInclusive('\n'));
try testing.expectError(error.EndOfStream, r.discardDelimiterInclusive('\n'));
}
std.Io.Reader.discardDelimiterLimit
函数
从流中读取直到发现指定字节,丢弃所有数据, 但不包括分隔符。
返回丢弃的字节数。
在找到分隔符之前流就结束时也会成功。可通过检查 分隔符是否已缓冲来判断流是否结束。
pub fn discardDelimiterLimit(r: *Reader, delimiter: u8, limit: Limit) DiscardDelimiterLimitError!usize
参数
错误
- ReadFailed
- StreamTooLong
在限制内未找到分隔符。
用法示例
test discardDelimiterLimit {
var r: Reader = .fixed("foob\nar");
try testing.expectError(error.StreamTooLong, r.discardDelimiterLimit('\n', .limited(4)));
try testing.expectEqual(0, try r.discardDelimiterLimit('\n', .limited(2)));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqual(2, try r.discardDelimiterLimit('\n', .unlimited));
try testing.expectEqual(0, try r.discardDelimiterLimit('\n', .unlimited));
}
std.Io.Reader.DiscardDelimiterLimitError
错误集合
错误
- ReadFailed
- StreamTooLong
在限制内未找到分隔符。
std.Io.Reader.discardRemaining
函数
消费流直至末尾,忽略全部数据, 返回丢弃的字节数。
pub fn discardRemaining(r: *Reader) ShortError!usize
参数
r: *Reader
错误
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test discardRemaining {
var r: Reader = .fixed("foobar");
r.toss(1);
try testing.expectEqual(5, try r.discardRemaining());
try testing.expectEqual(0, try r.discardRemaining());
}
std.Io.Reader.discardShort
函数
pub fn discardShort(r: *Reader, n: usize) ShortError!usize
参数
r: *Reader
n: usize
错误
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.ending
常量
*Reader
std.Io.Reader.ending_instance
常量
通常可以安全地对其使用 @constCast,因为缓冲区为空,
因此实际上没有意外尝试修改这些字段的途径。
Reader
std.Io.Reader.endingDiscard
函数
fn endingDiscard(r: *Reader, limit: Limit) Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.endingReadVec
函数
fn endingReadVec(r: *Reader, data: [][]u8) Error!usize
参数
r: *Reader
data: [][]u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.endingRebase
函数
fn endingRebase(r: *Reader, capacity: usize) RebaseError!void
参数
r: *Reader
capacity: usize
错误
std.Io.Reader.endingStream
函数
fn endingStream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize
参数
错误
std.Io.Reader.Error
错误集合
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.failing
常量
Reader
std.Io.Reader.failingDiscard
函数
fn failingDiscard(r: *Reader, limit: Limit) Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.failingStream
函数
fn failingStream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize
参数
错误
std.Io.Reader.fill
函数
填充缓冲区,使其至少包含 n 个字节,
不推进寻址位置。
当且仅当剩余字节数小于 n 时,返回
error.EndOfStream。
如果未遇到流结束,则断言缓冲区容量
至少为 n。
pub fn fill(r: *Reader, n: usize) Error!void
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test fill {
var r: Reader = .fixed("abc");
try r.fill(1);
try r.fill(3);
}
std.Io.Reader.fillMore
函数
不推进查找位置,仅执行一次底层读取,尽可能
填满缓冲区。这可能不向缓冲区添加任何字节,但这不表示流
已结束。通过返回 error.EndOfStream 表示流结束。
断言缓冲区容量至少为 1。
pub fn fillMore(r: *Reader) Error!void
参数
r: *Reader
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.fillUnbuffered
函数
将此内部函数与 fill 分离,以促使优化器内联 fill,从而
将其 @branchHint 传播到使用位置。如果将它们合并,fill 会大到
LLVM 不愿内联它,迫使 takeInt 等 API 的使用方执行
代价高昂的运行时函数调用,仅仅为了确认数据其实已经位于
缓冲区中。
缺少此优化可能使受影响最严重的基准测试的实际耗时 增加到原来的 5 倍甚至更多。
fn fillUnbuffered(r: *Reader, n: usize) Error!void
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.fixed
函数
构造一个 Reader,从 buffer 读取,然后结束。
pub fn fixed(buffer: []const u8) Reader
参数
buffer: []const u8
用法示例
test fixed {
var r: Reader = .fixed("a\x02");
try testing.expect((try r.takeByte()) == 'a');
try testing.expect((try r.takeEnum(enum(u8) {
a = 0,
b = 99,
c = 2,
d = 3,
}, builtin.cpu.arch.endian())) == .c);
try testing.expectError(error.EndOfStream, r.takeByte());
}
std.Io.Reader.hashed
函数
pub fn hashed(r: *Reader, hasher: anytype, buffer: []u8) Hashed(@TypeOf(hasher))
参数
r: *Reader
buffer: []u8
std.Io.Reader.Hashed
类型函数
提供 Reader 实现,将底层读取器
提供的数据传给 Hasher.update。
底层读取器最好不设缓冲。
由于实现需要通用性,其缓冲策略 并非最优。更好的方案是为每个哈希函数 创建读取器,使丢弃缓冲区能够针对哈希 实现细节定制。
pub fn Hashed(comptime Hasher: type) type
参数
Hasher: type
字段
std.Io.Reader.Hashed.discard
函数
fn discard(r: *Reader, limit: Limit) Error!usize
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.Hashed.init
函数
pub fn init(in: *Reader, hasher: Hasher, buffer: []u8) @This()
参数
std.Io.Reader.Hashed.readVec
函数
fn readVec(r: *Reader, data: [][]u8) Error!usize
参数
r: *Reader
data: [][]u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.Hashed.stream
函数
fn stream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize
参数
错误
std.Io.Reader.Limit
别名
别名目标 std.Io.Limit
std.Io.Reader.limited
函数
pub fn limited(r: *Reader, limit: Limit, buffer: []u8) Limited
参数
std.Io.Reader.Limited
别名
std.Io.Reader.LimitedAllocError
错误集合
错误
- OutOfMemory Error
- ReadFailed ShortError
详细诊断参见
Reader的实现。- StreamTooLong
std.Io.Reader.native_endian
常量
std.Io.Reader.peek
函数
返回流中的后续 n 字节,并按需填充
缓冲区。
使之前由 peek 返回的值失效。
断言初始化 Reader 时使用的缓冲区容量
至少为 n。
如果流中剩余字节少于 n,
则改为返回 error.EndOfStream。
另见:
pub fn peek(r: *Reader, n: usize) Error![]u8
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test peek {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.peek(2));
try testing.expectEqualStrings("a", try r.peek(1));
}
std.Io.Reader.peekArray
函数
将流中接下来的 n 个字节作为数组返回,按需填充缓冲区,
不推进寻址位置。
断言 Reader 初始化时的缓冲区容量
至少为 n。
如果流中剩余字节数小于 n,则改为返回
error.EndOfStream。
另请参见:
pub fn peekArray(r: *Reader, comptime n: usize) Error!*[n]u8
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test peekArray {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.peekArray(2));
try testing.expectEqualStrings("a", try r.peekArray(1));
}
std.Io.Reader.peekByte
函数
返回流中的下一个字节,或返回 error.EndOfStream。
不推进查找位置。
断言缓冲区容量非零。
pub fn peekByte(r: *Reader) Error!u8
参数
r: *Reader
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.peekDelimiterExclusive
函数
返回流中接下来缓冲数据的切片,直到找到
delimiter,不前移查找位置。
返回的切片不含分隔符。流结束等同于
遇到分隔符;但若这会返回长度为 0 的切片,
则改为返回 error.EndOfStream。
若检查了与此 Reader 容量相同数量的
字节后仍未找到分隔符,返回 error.StreamTooLong。
此时流状态不变,就像从未调用过
此函数。
此前 peek 返回的值将失效。
另请参见:
pub fn peekDelimiterExclusive(r: *Reader, delimiter: u8) DelimiterError![]u8
参数
r: *Reader
delimiter: u8
错误
- EndOfStream
对于“包含分隔符”的函数,流在找到分隔符前结束。 对于“不包含分隔符”的函数,流已结束, 没有更多字节可返回。
- ReadFailed
详细诊断参见
Reader的实现。- StreamTooLong
在与
Reader容量相等的字节数范围内 未找到分隔符。
用法示例
test peekDelimiterExclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.peekDelimiterExclusive('\n'));
try testing.expectEqualStrings("ab", try r.peekDelimiterExclusive('\n'));
r.toss(2);
try testing.expectEqualStrings("", try r.peekDelimiterExclusive('\n'));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqualStrings("c", try r.peekDelimiterExclusive('\n'));
try testing.expectEqualStrings("c", try r.peekDelimiterExclusive('\n'));
r.toss(1);
try testing.expectError(error.EndOfStream, r.peekDelimiterExclusive('\n'));
}
std.Io.Reader.peekDelimiterInclusive
函数
pub fn peekDelimiterInclusive(r: *Reader, delimiter: u8) DelimiterError![]u8
参数
r: *Reader
delimiter: u8
错误
- EndOfStream
对于“包含分隔符”的函数,流在找到分隔符前结束。 对于“不包含分隔符”的函数,流已结束, 没有更多字节可返回。
- ReadFailed
详细诊断参见
Reader的实现。- StreamTooLong
在与
Reader容量相等的字节数范围内 未找到分隔符。
用法示例
test peekDelimiterInclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab\n", try r.peekDelimiterInclusive('\n'));
try testing.expectEqualStrings("ab\n", try r.peekDelimiterInclusive('\n'));
r.toss(3);
try testing.expectError(error.EndOfStream, r.peekDelimiterInclusive('\n'));
try testing.expectEqualStrings("c", try r.peek(1));
}
std.Io.Reader.peekGreedy
函数
填充缓冲区,确保至少包含 n 个字节后,
返回接下来所有已缓冲字节。
使此前由 peek 和 peekGreedy 返回的值失效。
断言 Reader 初始化时的缓冲区容量
至少为 n。
如果流中剩余字节数小于 n,则改为返回
error.EndOfStream。
另请参见:
pub fn peekGreedy(r: *Reader, n: usize) Error![]u8
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test peekGreedy {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("abc", try r.peekGreedy(1));
}
std.Io.Reader.peekInt
函数
断言缓冲区初始化时容量至少为 @bitSizeOf(T) / 8。
pub inline fn peekInt(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.peekSentinel
函数
pub fn peekSentinel(r: *Reader, comptime sentinel: u8) DelimiterError![:sentinel]u8
参数
r: *Reader
sentinel: u8
错误
- EndOfStream
对于“包含分隔符”的函数,流在找到分隔符前结束。 对于“不包含分隔符”的函数,流已结束, 没有更多字节可返回。
- ReadFailed
详细诊断参见
Reader的实现。- StreamTooLong
在与
Reader容量相等的字节数范围内 未找到分隔符。
用法示例
test peekSentinel {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.peekSentinel('\n'));
try testing.expectEqualStrings("ab", try r.peekSentinel('\n'));
r.toss(3);
try testing.expectError(error.EndOfStream, r.peekSentinel('\n'));
try testing.expectEqualStrings("c", try r.peek(1));
}
std.Io.Reader.peekStruct
函数
pub inline fn peekStruct(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test peekStruct {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), try r.peekStruct(S, .big));
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), try r.peekStruct(S, .little));
}
std.Io.Reader.peekStructPointer
函数
取得指向流起始位置的未对齐指针,重新解释为 指向给定类型的指针,不推进寻址位置。
断言缓冲区初始化容量至少为 @sizeOf(T)。
另请参见:
pub fn peekStructPointer(r: *Reader, comptime T: type) Error!*align(1) T
参数
r: *Reader
T: type
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test peekStructPointer {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
switch (native_endian) {
.little => {
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), (try r.peekStructPointer(S)).*);
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), (try r.peekStructPointer(S)).*);
},
.big => {
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), (try r.peekStructPointer(S)).*);
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), (try r.peekStructPointer(S)).*);
},
}
}
std.Io.Reader.readAlloc
别名
已弃用;请使用 readAllocAll。将在 0.17 之后移除。
std.Io.Reader.readAllocAll
函数
使用 allocator 提供的缓冲区调用 readSliceAll 的快捷操作。
pub fn readAllocAll(r: *Reader, allocator: Allocator, len: usize) ReadAllocError![]u8
参数
错误
用法示例
test readAllocAll {
const allocator = testing.allocator;
var r: Reader = .fixed("HelloFren");
const s1 = try r.readAllocAll(allocator, 5);
defer allocator.free(s1);
try testing.expectEqualStrings("Hello", s1);
const s2 = try r.readAllocAll(allocator, 4);
defer allocator.free(s2);
try testing.expectEqualStrings("Fren", s2);
}
std.Io.Reader.ReadAllocError
错误集合
错误
std.Io.Reader.readAllocShort
函数
使用 allocator 提供的缓冲区调用 readSliceShort 的快捷方法;若流到达末尾,则收缩分配。
pub fn readAllocShort(r: *Reader, allocator: Allocator, len: usize) ReadAllocError![]u8
参数
错误
用法示例
test readAllocShort {
var r: Reader = .fixed("HelloFren");
const s1 = try r.readAllocShort(testing.allocator, 5);
defer testing.allocator.free(s1);
try testing.expectEqualStrings("Hello", s1);
const s2 = try r.readAllocShort(testing.allocator, 10);
defer testing.allocator.free(s2);
try testing.expectEqualStrings("Fren", s2);
const s3 = try r.readAllocShort(testing.allocator, 10);
defer testing.allocator.free(s3);
try testing.expectEqual(0, s3.len);
}
std.Io.Reader.Reader
别名
别名目标 std.Io.Reader
std.Io.Reader.readSliceAll
函数
使用流中的后续 buffer.len 字节填满 buffer,推进
查找位置。
使之前由 peek 返回的值失效。
如果无法完全填满提供的缓冲区,则改为返回
error.EndOfStream。
另见:
pub fn readSliceAll(r: *Reader, buffer: []u8) Error!void
参数
r: *Reader
buffer: []u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.readSliceEndian
函数
填充 buffer,使用流中接下来的 buffer.len 个字节,并推进查找位置。
使此前从 peek 返回的值失效。
若无法完整填充给定缓冲区,则返回 error.EndOfStream。
此函数采用内联,以便在 endian 编译期已知且与宿主字节序一致时,消除无用代码。
另见:
pub inline fn readSliceEndian( r: *Reader, comptime Elem: type, buffer: []Elem, endian: std.builtin.Endian, ) Error!void
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.readSliceEndianAlloc
函数
函数采用内联,以便在 endian 在编译期已知且
与宿主端序相同时,避免生成无用代码。
pub inline fn readSliceEndianAlloc( r: *Reader, allocator: Allocator, comptime Elem: type, len: usize, endian: std.builtin.Endian, ) ReadAllocError![]Elem
参数
错误
std.Io.Reader.readSliceShort
函数
用流中接下来的 buffer.len 个字节填充 buffer,推进
寻址位置。
使此前由 peek 返回的值失效。
返回读取的字节数;当且仅当流到达
末尾时,该数量小于 buffer.len。
另请参见:
pub fn readSliceShort(r: *Reader, buffer: []u8) ShortError!usize
参数
r: *Reader
buffer: []u8
错误
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test readSliceShort {
var r: Reader = .fixed("HelloFren");
var buf: [5]u8 = undefined;
try testing.expectEqual(5, try r.readSliceShort(&buf));
try testing.expectEqualStrings("Hello", buf[0..5]);
try testing.expectEqual(4, try r.readSliceShort(&buf));
try testing.expectEqualStrings("Fren", buf[0..4]);
try testing.expectEqual(0, try r.readSliceShort(&buf));
}
std.Io.Reader.readVec
函数
从内部跟踪的流位置向 data 写入字节。
返回写入字节数,最少为 0,
最多为所有 data 切片长度之和。读取字节数,
包括零,都不表示流结束。
读取器内部的逻辑寻址位置,按此函数 返回的字节数向前移动。
pub fn readVec(r: *Reader, data: [][]u8) Error!usize
参数
r: *Reader
data: [][]u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test readVec {
var r: Reader = .fixed(std.ascii.letters);
var flat_buffer: [52]u8 = undefined;
var bufs: [2][]u8 = .{
flat_buffer[0..26],
flat_buffer[26..],
};
// 此函数可能发生短读,但 fixed 不会。
try testing.expectEqual(26 * 2, try r.readVec(&bufs));
try testing.expectEqualStrings(std.ascii.letters[0..26], bufs[0]);
try testing.expectEqualStrings(std.ascii.letters[26..], bufs[1]);
}
std.Io.Reader.readVecAll
函数
pub fn readVecAll(r: *Reader, data: [][]u8) Error!void
参数
r: *Reader
data: [][]u8
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.rebase
函数
确保无需调整基址即可缓冲 capacity 大小的数据。
pub fn rebase(r: *Reader, capacity: usize) Error!void
参数
r: *Reader
capacity: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.RebaseError
别名
别名目标 std.Io.Reader.Error
std.Io.Reader.ShortError
错误集合
错误
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.std
别名
别名目标 std
std.Io.Reader.stream
函数
pub fn stream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize
参数
错误
用法示例
test stream {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foobar");
var w: Writer = .fixed(&out_buffer);
// 此函数支持短流,而 fixed 不支持。
try testing.expectEqual(2, try r.stream(&w, .limited(2)));
try testing.expectEqualStrings("fo", w.buffered());
try testing.expectEqual(4, try r.stream(&w, .unlimited));
try testing.expectEqualStrings("foobar", w.buffered());
}
std.Io.Reader.streamDelimiter
函数
从流读取并追加到 w,直到找到 delimiter。不写入分隔符本身。
不从 Reader 丢弃分隔符。
返回传输的字节数,可能为零;若未找到分隔符,则返回 error.EndOfStream。
断言缓冲区容量至少为一。更大的缓冲区可提高此函数的性能。
另见:
pub fn streamDelimiter(r: *Reader, w: *Writer, delimiter: u8) StreamError!usize
参数
错误
用法示例
test streamDelimiter {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foo\nbars");
var w: Writer = .fixed(&out_buffer);
try testing.expectEqual(3, try r.streamDelimiter(&w, '\n'));
try testing.expectEqualStrings("foo", w.buffered());
try testing.expectEqual(0, try r.streamDelimiter(&w, '\n'));
r.toss(1);
try testing.expectError(error.EndOfStream, r.streamDelimiter(&w, '\n'));
}
std.Io.Reader.streamDelimiterEnding
函数
向 w 追加从流中读取的内容,直到找到 delimiter。
不写入分隔符本身。
返回流式传输的字节数,可以为零。若流到达 末尾,此函数返回时读取器缓冲区为空。 否则,缓冲区至少包含一个字节,且第一个字节 为分隔符。
断言缓冲区容量至少为一。 缓冲区越大,此函数性能越好。
另请参见:
pub fn streamDelimiterEnding( r: *Reader, w: *Writer, delimiter: u8, ) StreamRemainingError!usize
参数
错误
用法示例
test streamDelimiterEnding {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foo\nbars");
var w: Writer = .fixed(&out_buffer);
try testing.expectEqual(3, try r.streamDelimiterEnding(&w, '\n'));
try testing.expectEqualStrings("foo", w.buffered());
r.toss(1);
try testing.expectEqual(4, try r.streamDelimiterEnding(&w, '\n'));
try testing.expectEqualStrings("foobars", w.buffered());
try testing.expectEqual(0, try r.streamDelimiterEnding(&w, '\n'));
try testing.expectEqual(0, try r.streamDelimiterEnding(&w, '\n'));
}
std.Io.Reader.streamDelimiterLimit
函数
从流读取并追加到 w,直到找到 delimiter。
不写入分隔符本身。
不从 Reader 丢弃分隔符。
返回传输的字节数,可能为零。可以检查流中的下一个字节是否为分隔符,以检测流结束。
断言缓冲区容量至少为一。更大的缓冲区可提高此函数的性能。
pub fn streamDelimiterLimit( r: *Reader, w: *Writer, delimiter: u8, limit: Limit, ) StreamDelimiterLimitError!usize
参数
错误
- ReadFailed
- StreamTooLong
在限制内未找到分隔符。
- WriteFailed
用法示例
test streamDelimiterLimit {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foo\nbars");
var w: Writer = .fixed(&out_buffer);
try testing.expectError(error.StreamTooLong, r.streamDelimiterLimit(&w, '\n', .limited(2)));
try testing.expectEqual(1, try r.streamDelimiterLimit(&w, '\n', .limited(3)));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqual(4, try r.streamDelimiterLimit(&w, '\n', .unlimited));
try testing.expectEqualStrings("foobars", w.buffered());
}
std.Io.Reader.StreamDelimiterLimitError
错误集合
错误
- ReadFailed
- StreamTooLong
在限制内未找到分隔符。
- WriteFailed
std.Io.Reader.StreamError
错误集合
错误
std.Io.Reader.streamExact
函数
从读取器向写入器恰好“泵送” n 字节。
pub fn streamExact(r: *Reader, w: *Writer, n: usize) StreamError!void
参数
错误
std.Io.Reader.streamExact64
函数
从读取器向写入器恰好“泵送” n 字节。
pub fn streamExact64(r: *Reader, w: *Writer, n: u64) StreamError!void
参数
错误
std.Io.Reader.streamExactPreserve
函数
从读取器向写入器准确“泵送” n 个字节。
成功后,若缓冲字节足够,至少会保留 preserve_len 个字节
在缓冲区中。
调用后写入器的缓冲字节数仅在以下情况会小于
preserve_len:调用之前 w.end + n 小于 preserve_len。
刻意保留的字节包括原有缓冲字节中的至多 preserve_len -| n 字节,
再加上新“泵送”字节中的 @min(n, preserve_len)
字节。
断言 Writer.buffer 的容量至少为 preserve_len。
n 可以大于 Writer.buffer 的容量。
pub fn streamExactPreserve(r: *Reader, w: *Writer, preserve_len: usize, n: usize) StreamError!void
参数
错误
用法示例
test streamExactPreserve {
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 5, .stream_len = 5 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 9, .preserve = 5, .stream_len = 2 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 5, .stream_len = 6 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 6 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 5, .stream_len = 10 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 10 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 11 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 80 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 85 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 6 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 11 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 80 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 85 });
}
std.Io.Reader.streamRemaining
函数
将数据从读取器“泵送”到写入器,将 error.EndOfStream 视为成功情况。
返回写入 w 的总字节数。
pub fn streamRemaining(r: *Reader, w: *Writer) StreamRemainingError!usize
参数
错误
std.Io.Reader.StreamRemainingError
错误集合
错误
std.Io.Reader.take
函数
pub fn take(r: *Reader, n: usize) Error![]u8
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test take {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.take(2));
try testing.expectEqualStrings("c", try r.take(1));
}
std.Io.Reader.takeArray
函数
以数组形式返回流中接下来的 n 个字节,必要时填充缓冲区,并将查找位置向前推进 n 字节。
断言 Reader 初始化时的缓冲区容量至少为 n。
若流中剩余字节少于 n,则改为返回 error.EndOfStream。
另见:
pub fn takeArray(r: *Reader, comptime n: usize) Error!*[n]u8
参数
r: *Reader
n: usize
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test takeArray {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.takeArray(2));
try testing.expectEqualStrings("c", try r.takeArray(1));
}
std.Io.Reader.takeByte
函数
从流中读取 1 字节,否则返回 error.EndOfStream。
断言缓冲区容量非零。
pub fn takeByte(r: *Reader) Error!u8
参数
r: *Reader
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test takeByte {
var r: Reader = .fixed("ab");
try testing.expectEqual('a', try r.takeByte());
try testing.expectEqual('b', try r.takeByte());
try testing.expectError(error.EndOfStream, r.takeByte());
}
std.Io.Reader.takeByteSigned
函数
与 takeByte 相同,但返回的字节有符号。
pub fn takeByteSigned(r: *Reader) Error!i8
参数
r: *Reader
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test takeByteSigned {
var r: Reader = .fixed(&.{ 255, 5 });
try testing.expectEqual(-1, try r.takeByteSigned());
try testing.expectEqual(5, try r.takeByteSigned());
try testing.expectError(error.EndOfStream, r.takeByteSigned());
}
std.Io.Reader.takeDelimiter
函数
返回流中接下来的缓冲数据字节的切片,直到找到
delimiter,并将寻址位置推进到分隔符之后。
返回切片不含分隔符。流结束等同于
分隔符,但如果这会返回长度为 0 的切片,
则改为返回 null。
如果在等于此 Reader 容量的字节范围内
未找到分隔符,则返回 error.StreamTooLong。
此时流状态保持不变,如同未曾调用
此函数。
使此前由 peek 返回的值失效。
另请参见:
pub fn takeDelimiter(r: *Reader, delimiter: u8) error{ ReadFailed, StreamTooLong }!?[]u8
参数
r: *Reader
delimiter: u8
错误
- ReadFailed
- StreamTooLong
用法示例
test takeDelimiter {
var r: Reader = .fixed("ab\nc\n\nd");
try testing.expectEqualStrings("ab", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("c", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("d", (try r.takeDelimiter('\n')).?);
try testing.expectEqual(null, try r.takeDelimiter('\n'));
try testing.expectEqual(null, try r.takeDelimiter('\n'));
r = .fixed("ab\nc\n\nd\n"); // 单个尾随换行符不影响行为
try testing.expectEqualStrings("ab", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("c", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("d", (try r.takeDelimiter('\n')).?);
try testing.expectEqual(null, try r.takeDelimiter('\n'));
try testing.expectEqual(null, try r.takeDelimiter('\n'));
}
std.Io.Reader.takeDelimiterExclusive
函数
返回流中接下来缓冲数据的切片,直到找到
delimiter,并将查找位置前移至分隔符之前,
但不越过分隔符。
返回的切片不含分隔符。流结束等同于
遇到分隔符;但若这会返回长度为 0 的切片,
则改为返回 error.EndOfStream。
若检查了与此 Reader 容量相同数量的
字节后仍未找到分隔符,返回 error.StreamTooLong。
此时流状态不变,就像从未调用过
此函数。
此前 peek 返回的值将失效。
另请参见:
pub fn takeDelimiterExclusive(r: *Reader, delimiter: u8) DelimiterError![]u8
参数
r: *Reader
delimiter: u8
错误
- EndOfStream
对于“包含分隔符”的函数,流在找到分隔符前结束。 对于“不包含分隔符”的函数,流已结束, 没有更多字节可返回。
- ReadFailed
详细诊断参见
Reader的实现。- StreamTooLong
在与
Reader容量相等的字节数范围内 未找到分隔符。
用法示例
test takeDelimiterExclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.takeDelimiterExclusive('\n'));
try testing.expectEqualStrings("", try r.takeDelimiterExclusive('\n'));
try testing.expectEqualStrings("", try r.takeDelimiterExclusive('\n'));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqualStrings("c", try r.takeDelimiterExclusive('\n'));
try testing.expectError(error.EndOfStream, r.takeDelimiterExclusive('\n'));
}
std.Io.Reader.takeDelimiterInclusive
函数
pub fn takeDelimiterInclusive(r: *Reader, delimiter: u8) DelimiterError![]u8
参数
r: *Reader
delimiter: u8
错误
- EndOfStream
对于“包含分隔符”的函数,流在找到分隔符前结束。 对于“不包含分隔符”的函数,流已结束, 没有更多字节可返回。
- ReadFailed
详细诊断参见
Reader的实现。- StreamTooLong
在与
Reader容量相等的字节数范围内 未找到分隔符。
用法示例
test takeDelimiterInclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab\n", try r.takeDelimiterInclusive('\n'));
try testing.expectError(error.EndOfStream, r.takeDelimiterInclusive('\n'));
}
std.Io.Reader.takeEnum
函数
读取与给定枚举标签类型大小相同的整数。
若整数匹配某个枚举标签,将其转换为该标签并返回;否则返回 error.InvalidEnumTag。
断言初始化缓冲区时的容量至少为 @sizeOf(Enum)。
pub fn takeEnum(r: *Reader, comptime Enum: type, endian: std.builtin.Endian) TakeEnumError!Enum
参数
错误
用法示例
test takeEnum {
var r: Reader = .fixed(&.{ 2, 0, 1 });
const E1 = enum(u8) { a, b, c };
const E2 = enum(u16) { _ };
try testing.expectEqual(E1.c, try r.takeEnum(E1, .little));
try testing.expectEqual(@as(E2, @fromBackingInt(@intCast(0x0001))), try r.takeEnum(E2, .big));
}
std.Io.Reader.TakeEnumError
错误集合
错误
std.Io.Reader.takeEnumNonexhaustive
函数
读取一个与给定非穷尽枚举标签类型大小相同的整数。
断言缓冲区初始化容量至少为 @sizeOf(Enum)。
pub fn takeEnumNonexhaustive(r: *Reader, comptime Enum: type, endian: std.builtin.Endian) Error!Enum
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.takeInt
函数
断言缓冲区初始化时容量至少为 @bitSizeOf(T) / 8。
pub inline fn takeInt(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test takeInt {
var r: Reader = .fixed(&.{ 0x12, 0x34, 0x56 });
try testing.expectEqual(0x1234, try r.takeInt(u16, .big));
try testing.expectError(error.EndOfStream, r.takeInt(u16, .little));
}
std.Io.Reader.takeLeb128
函数
读取单个 LEB128 值为类型 T;若无法表示该值,则返回 error.Overflow。
pub fn takeLeb128(r: *Reader, comptime T: type) TakeLeb128Error!T
参数
r: *Reader
T: type
错误
std.Io.Reader.TakeLeb128Error
错误集合
错误
std.Io.Reader.takeSentinel
函数
pub fn takeSentinel(r: *Reader, comptime sentinel: u8) DelimiterError![:sentinel]u8
参数
r: *Reader
sentinel: u8
错误
- EndOfStream
对于“包含分隔符”的函数,流在找到分隔符前结束。 对于“不包含分隔符”的函数,流已结束, 没有更多字节可返回。
- ReadFailed
详细诊断参见
Reader的实现。- StreamTooLong
在与
Reader容量相等的字节数范围内 未找到分隔符。
用法示例
test takeSentinel {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.takeSentinel('\n'));
try testing.expectError(error.EndOfStream, r.takeSentinel('\n'));
try testing.expectEqualStrings("c", try r.peek(1));
}
std.Io.Reader.takeStruct
函数
pub inline fn takeStruct(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test takeStruct {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), try r.takeStruct(S, .big));
try testing.expectError(error.EndOfStream, r.takeStruct(S, .little));
}
std.Io.Reader.takeStructPointer
函数
获取指向流开头的未对齐指针,将其重新解释为 指向所提供类型的指针,并推进查找位置。
断言缓冲区初始化时的容量至少为 @sizeOf(T)。
另见:
pub fn takeStructPointer(r: *Reader, comptime T: type) Error!*align(1) T
参数
r: *Reader
T: type
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test takeStructPointer {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
switch (native_endian) {
.little => try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), (try r.takeStructPointer(S)).*),
.big => try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), (try r.takeStructPointer(S)).*),
}
try testing.expectError(error.EndOfStream, r.takeStructPointer(S));
}
std.Io.Reader.takeVarInt
函数
断言缓冲区初始化时容量至少为 n。
pub fn takeVarInt(r: *Reader, comptime Int: type, endian: std.builtin.Endian, n: usize) Error!Int
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
用法示例
test takeVarInt {
var r: Reader = .fixed(&.{ 0x12, 0x34, 0x56 });
try testing.expectEqual(0x123456, try r.takeVarInt(u64, .big, 3));
try testing.expectError(error.EndOfStream, r.takeVarInt(u16, .little, 1));
}
std.Io.Reader.testing
别名
别名目标 std.testing
std.Io.Reader.testLeb128
函数
fn testLeb128(comptime T: type, encoded: []const u8) !T
参数
T: type
encoded: []const u8
std.Io.Reader.testStreamExactPreserve
函数
fn testStreamExactPreserve(options: struct { buf_len: u4, fill_len: u4, preserve: u4, stream_len: u8 }) !void
参数
options: struct { buf_len: u4, fill_len: u4, preserve: u4, stream_len: u8 }
std.Io.Reader.toss
函数
pub fn toss(r: *Reader, n: usize) void
参数
r: *Reader
n: usize
用法示例
test toss {
var r: Reader = .fixed("abc");
r.toss(1);
try testing.expectEqualStrings("bc", r.buffered());
}
std.Io.Reader.tossBuffered
函数
等价于 toss(r.bufferedLen())。
pub fn tossBuffered(r: *Reader) void
参数
r: *Reader
std.Io.Reader.UnlimitedAllocError
错误集合
错误
- OutOfMemory Error
- ReadFailed ShortError
详细诊断参见
Reader的实现。
std.Io.Reader.VTable
容器
字段
stream: *const fn (r: *Reader, w: *Writer, limit: Limit) StreamError!usize将内部跟踪的逻辑位置起始处的字节写入 w。
返回写入的字节数,最小为 0,
最大为 limit。返回值(包括零)均不表示
流结束。
读取器内部的逻辑查找位置根据 此函数返回的字节数向前移动。
建议实现结合强制的最小缓冲区
大小与短读取(返回小于 limit 的值),
以降低复杂度。
虽然此函数通常在 buffer 为空时调用,但
当 API 使用者要求连续内存、需要进一步填充
缓冲区时也会调用。不论哪种情况,均应忽略已有缓冲区数据,
将新数据写入 w。
实现除了向 w 写入外,也可以选择
将数据保存在 buffer 中,并相应修改 seek 和 end。
若这能简化逻辑,
建议实现利用此机制。
discard: *const fn (r: *Reader, limit: Limit) Error!usize = defaultDiscard从内部跟踪的流位置消耗字节,但不提供对这些字节的访问。
返回丢弃的字节数,最少为 0,最多为 limit。返回数量,包括零,都不表示流结束。
读取器内部的逻辑查找位置,按此函数返回的字节数向前移动。
建议实现结合强制的最小缓冲区大小与短读取(返回小于 limit 的值),以尽量降低复杂度。
默认实现调用 stream,借用 buffer 构造临时 Writer,并忽略写入的数据。
仅在 buffer 为空时调用此函数。
readVec: *const fn (r: *Reader, data: [][]u8) Error!usize = defaultReadVec返回写入 data 的字节数。
data 的长度必须非零。data[0] 的长度可以为零,
此时实现必须写入 Reader.buffer。
data 不得包含 Reader.buffer 的别名。
data 是可变的,因为实现可能临时修改其
字段以处理部分读取。实现必须在返回前恢复
原值。
实现可以忽略 data,直接写入 Reader.buffer,
相应修改 seek 和 end,并从此函数返回 0。
若这能简化逻辑,
建议实现利用此机制。
默认实现调用 stream,传入 data[0] 或
Reader.buffer 中较大的一个。
rebase: *const fn (r: *Reader, capacity: usize) RebaseError!void = defaultRebase确保无需重新定位缓冲数据即可缓冲 capacity 的数据量。
断言 capacity 不超过缓冲区容量,或者流在
capacity 字节内结束。
仅当 buffer 的未用容量无法满足 capacity 时调用。
默认实现将已缓冲数据移至 buffer 的起始位置,
将 seek 设为零,并且不会失败。
std.Io.Reader.writableVector
函数
pub fn writableVector(r: *Reader, buffer: [][]u8, data: []const []u8) Error!struct { usize, usize }
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.writableVectorPosix
函数
pub fn writableVectorPosix(r: *Reader, buffer: []std.posix.iovec, data: []const []u8) Error!struct { usize, usize }
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.writableVectorWsa
函数
pub fn writableVectorWsa( r: *Reader, buffer: []std.os.windows.AFD.WSABUF(.@"var"), data: []const []u8, ) Error!struct { usize, usize }
参数
错误
- EndOfStream
- ReadFailed
详细诊断参见
Reader的实现。
std.Io.Reader.Writer
别名
别名目标 std.Io.Writer
源码
std/Io/Reader.zig
const Reader = @This();
const builtin = @import("builtin");
const native_endian = builtin.target.cpu.arch.endian();
const std = @import("../std.zig");
const Writer = std.Io.Writer;
const Limit = std.Io.Limit;
const assert = std.debug.assert;
const testing = std.testing;
const Allocator = std.mem.Allocator;
const ArrayList = std.ArrayList;
pub const Limited = @import("Reader/Limited.zig");
vtable: *const VTable,
buffer: []u8,
/// 已从 `buffer` 消费的字节数。
seek: usize,
/// `buffer` 中此位置之前是已缓冲的字节,之后是 `undefined`。
end: usize,
pub const VTable = struct {
/// 将内部跟踪的逻辑位置起始处的字节写入 `w`。
///
/// 返回写入的字节数,最小为 `0`,
/// 最大为 `limit`。返回值(包括零)均不表示
/// 流结束。
///
/// 读取器内部的逻辑查找位置根据
/// 此函数返回的字节数向前移动。
///
/// 建议实现结合强制的最小缓冲区
/// 大小与短读取(返回小于 `limit` 的值),
/// 以降低复杂度。
///
/// 虽然此函数通常在 `buffer` 为空时调用,但
/// 当 API 使用者要求连续内存、需要进一步填充
/// 缓冲区时也会调用。不论哪种情况,均应忽略已有缓冲区数据,
/// 将新数据写入 `w`。
///
/// 实现除了向 `w` 写入外,也可以选择
/// 将数据保存在 `buffer` 中,并相应修改 `seek` 和 `end`。
/// 若这能简化逻辑,
/// 建议实现利用此机制。
stream: *const fn (r: *Reader, w: *Writer, limit: Limit) StreamError!usize,
/// 从内部跟踪的流位置消耗字节,但不提供对这些字节的访问。
///
/// 返回丢弃的字节数,最少为 `0`,最多为 `limit`。返回数量,包括零,都不表示流结束。
///
/// 读取器内部的逻辑查找位置,按此函数返回的字节数向前移动。
///
/// 建议实现结合强制的最小缓冲区大小与短读取(返回小于 `limit` 的值),以尽量降低复杂度。
///
/// 默认实现调用 `stream`,借用 `buffer` 构造临时 `Writer`,并忽略写入的数据。
///
/// 仅在 `buffer` 为空时调用此函数。
///
///
///
///
///
///
///
///
discard: *const fn (r: *Reader, limit: Limit) Error!usize = defaultDiscard,
/// 返回写入 `data` 的字节数。
///
/// `data` 的长度必须非零。`data[0]` 的长度可以为零,
/// 此时实现必须写入 `Reader.buffer`。
///
/// `data` 不得包含 `Reader.buffer` 的别名。
///
/// `data` 是可变的,因为实现可能临时修改其
/// 字段以处理部分读取。实现必须在返回前恢复
/// 原值。
///
/// 实现可以忽略 `data`,直接写入 `Reader.buffer`,
/// 相应修改 `seek` 和 `end`,并从此函数返回 0。
/// 若这能简化逻辑,
/// 建议实现利用此机制。
///
/// 默认实现调用 `stream`,传入 `data[0]` 或
/// `Reader.buffer` 中较大的一个。
readVec: *const fn (r: *Reader, data: [][]u8) Error!usize = defaultReadVec,
/// 确保无需重新定位缓冲数据即可缓冲 `capacity` 的数据量。
///
/// 断言 `capacity` 不超过缓冲区容量,或者流在
/// `capacity` 字节内结束。
///
/// 仅当 `buffer` 的未用容量无法满足 `capacity` 时调用。
///
/// 默认实现将已缓冲数据移至 `buffer` 的起始位置,
/// 将 `seek` 设为零,并且不会失败。
///
rebase: *const fn (r: *Reader, capacity: usize) RebaseError!void = defaultRebase,
};
pub const StreamError = error{
/// 详细诊断参见 `Reader` 的实现。
ReadFailed,
/// 详细诊断信息见 `Writer` 实现。
WriteFailed,
/// `Reader` 指示流结束。此错误不会从 `Writer` 产生。
///
EndOfStream,
};
pub const Error = error{
/// 详细诊断参见 `Reader` 的实现。
ReadFailed,
EndOfStream,
};
pub const StreamRemainingError = error{
/// 详细诊断参见 `Reader` 的实现。
ReadFailed,
/// 详细诊断信息见 `Writer` 实现。
WriteFailed,
};
pub const ShortError = error{
/// 详细诊断参见 `Reader` 的实现。
ReadFailed,
};
pub const RebaseError = Error;
pub const failing: Reader = .{
.vtable = &.{
.stream = failingStream,
.discard = failingDiscard,
},
.buffer = &.{},
.seek = 0,
.end = 0,
};
/// 通常可以安全地对其使用 `@constCast`,因为缓冲区为空,
/// 因此实际上没有意外尝试修改这些字段的途径。
pub const ending_instance: Reader = .fixed(&.{});
pub const ending: *Reader = @constCast(&ending_instance);
pub fn limited(r: *Reader, limit: Limit, buffer: []u8) Limited {
return .init(r, limit, buffer);
}
/// 构造一个 `Reader`,从 `buffer` 读取,然后结束。
pub fn fixed(buffer: []const u8) Reader {
return .{
.vtable = &.{
.stream = endingStream,
.discard = endingDiscard,
.readVec = endingReadVec,
.rebase = endingRebase,
},
// 此转换是安全的,因为对它的所有潜在写入
// 都会改为返回 `error.EndOfStream`。
.buffer = @constCast(buffer),
.end = buffer.len,
.seek = 0,
};
}
pub fn stream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize {
const buffer = limit.slice(r.buffer[r.seek..r.end]);
if (buffer.len > 0) {
@branchHint(.likely);
const n = try w.write(buffer);
r.seek += n;
return n;
}
const n = try r.vtable.stream(r, w, limit);
assert(n <= @backingInt(limit));
return n;
}
pub fn discard(r: *Reader, limit: Limit) Error!usize {
const buffered_len = r.end - r.seek;
const remaining: Limit = if (limit.toInt()) |n| l: {
if (buffered_len >= n) {
r.seek += n;
return n;
}
break :l .limited(n - buffered_len);
} else .unlimited;
r.seek = r.end;
const n = try r.vtable.discard(r, remaining);
assert(n <= @backingInt(remaining));
return buffered_len + n;
}
pub fn defaultDiscard(r: *Reader, limit: Limit) Error!usize {
assert(r.seek == r.end);
r.seek = 0;
r.end = 0;
var d: Writer.Discarding = .init(r.buffer);
var n = r.stream(&d.writer, limit) catch |err| switch (err) {
error.WriteFailed => unreachable,
error.ReadFailed, error.EndOfStream => |e| return e,
};
// 若 `stream` 未经过写入器就写入 `r.buffer`,则需要尽可能丢弃缓冲数据。
//
const remaining = @backingInt(limit) - n;
const buffered_n_to_discard = @min(remaining, r.end - r.seek);
n += buffered_n_to_discard;
r.seek += buffered_n_to_discard;
assert(n <= @backingInt(limit));
return n;
}
/// 从读取器向写入器恰好“泵送” `n` 字节。
pub fn streamExact(r: *Reader, w: *Writer, n: usize) StreamError!void {
var remaining = n;
while (remaining != 0) remaining -= try r.stream(w, .limited(remaining));
}
/// 从读取器向写入器恰好“泵送” `n` 字节。
pub fn streamExact64(r: *Reader, w: *Writer, n: u64) StreamError!void {
var remaining = n;
while (remaining != 0) remaining -= try r.stream(w, .limited64(remaining));
}
/// 从读取器向写入器准确“泵送” `n` 个字节。
///
/// 成功后,若缓冲字节足够,至少会保留 `preserve_len` 个字节
/// 在缓冲区中。
/// 调用后写入器的缓冲字节数仅在以下情况会小于
/// `preserve_len`:调用之前 `w.end + n` 小于 `preserve_len`。
/// 刻意保留的字节包括原有缓冲字节中的至多 `preserve_len -| n` 字节,
/// 再加上新“泵送”字节中的 `@min(n, preserve_len)`
/// 字节。
///
/// 断言 `Writer.buffer` 的容量至少为 `preserve_len`。
/// `n` 可以大于 `Writer.buffer` 的容量。
pub fn streamExactPreserve(r: *Reader, w: *Writer, preserve_len: usize, n: usize) StreamError!void {
if (w.end + n <= w.buffer.len) {
@branchHint(.likely);
return streamExact(r, w, n);
}
// `n` 较大时,可以在一定程度上忽略 `preserve_len`。
var remaining = n;
while (remaining > preserve_len) {
assert(remaining != 0);
remaining -= try r.stream(w, .limited(remaining - preserve_len));
if (w.end + remaining <= w.buffer.len) return streamExact(r, w, remaining);
}
// 按尚待流式传输的字节数调整保留量,
// 因为剩余字节必定包含在
// 保留部分中。
try w.rebase(preserve_len -| remaining, remaining);
return streamExact(r, w, remaining);
}
/// 将数据从读取器“泵送”到写入器,将 `error.EndOfStream` 视为成功情况。
///
/// 返回写入 `w` 的总字节数。
///
pub fn streamRemaining(r: *Reader, w: *Writer) StreamRemainingError!usize {
var offset: usize = 0;
while (true) {
offset += r.stream(w, .unlimited) catch |err| switch (err) {
error.EndOfStream => return offset,
else => |e| return e,
};
}
}
/// 消费流直至末尾,忽略全部数据,
/// 返回丢弃的字节数。
pub fn discardRemaining(r: *Reader) ShortError!usize {
var offset: usize = r.end - r.seek;
r.seek = r.end;
while (true) {
offset += r.vtable.discard(r, .unlimited) catch |err| switch (err) {
error.EndOfStream => return offset,
else => |e| return e,
};
}
}
pub const LimitedAllocError = Allocator.Error || ShortError || error{StreamTooLong};
/// 从当前位置传输到流末尾的全部字节,最多
/// `limit` 个,并将它们作为调用方拥有的已分配切片返回。
///
/// 若超过 `limit`,改为返回 `error.StreamTooLong`。
/// 此时下一个待读字节位于第一个超出 `limit`
/// 的字节之后,之前的所有字节均已丢弃。
///
/// 另请参见:
/// * `appendRemaining`
pub fn allocRemaining(r: *Reader, gpa: Allocator, limit: Limit) LimitedAllocError![]u8 {
var buffer: ArrayList(u8) = .empty;
defer buffer.deinit(gpa);
try appendRemaining(r, gpa, &buffer, switch (limit) {
.unlimited => limit,
.nothing, _ => .limited(@backingInt(limit) + 1),
});
return buffer.toOwnedSlice(gpa);
}
pub fn allocRemainingAlignedSentinel(
r: *Reader,
gpa: Allocator,
limit: Limit,
comptime alignment: std.mem.Alignment,
comptime sentinel: ?u8,
) LimitedAllocError!(if (sentinel) |s| [:s]align(alignment.toByteUnits()) u8 else []align(alignment.toByteUnits()) u8) {
var buffer: std.array_list.Aligned(u8, alignment) = .empty;
defer buffer.deinit(gpa);
try appendRemainingAligned(r, gpa, alignment, &buffer, limit);
if (sentinel) |s| {
return buffer.toOwnedSliceSentinel(gpa, s);
} else {
return buffer.toOwnedSlice(gpa);
}
}
pub const AppendExactError = Allocator.Error || Error;
/// 从读取器向 `ArrayList` 恰好传输 `n` 字节。
///
/// 另请参见:
/// * `appendRemaining`
pub fn appendExact(
r: *Reader,
gpa: Allocator,
list: *ArrayList(u8),
n: usize,
) AppendExactError!void {
try list.ensureUnusedCapacity(gpa, n);
var a = std.Io.Writer.Allocating.fromArrayList(gpa, list);
defer list.* = a.toArrayList();
streamExact(r, &a.writer, n) catch |err| switch (err) {
error.ReadFailed, error.EndOfStream => |e| return e,
error.WriteFailed => unreachable,
};
}
/// 将当前位置到流末尾的所有字节追加到 `list`,
/// 最多传输 `limit`。
///
/// 如果达到或超过 `limit`,则改为返回 `error.StreamTooLong`。
/// 此时下一个将要读取的字节是第一个
/// 超出 `limit` 的字节,而此前所有字节均已追加到
/// `list`。
///
/// 另请参见:
/// * `allocRemaining`
pub fn appendRemaining(
r: *Reader,
gpa: Allocator,
list: *ArrayList(u8),
limit: Limit,
) LimitedAllocError!void {
return appendRemainingAligned(r, gpa, .of(u8), list, limit);
}
/// 从当前位置传输字节直到流结束,最多 `limit` 字节,并追加到 `list`。
///
/// 若达到或超过 `limit`,则改为返回 `error.StreamTooLong`。此时,下一个将读取的字节是首个超出 `limit` 的字节,此前的全部字节都已追加到 `list`。
///
/// 另见:
/// * `appendRemaining`
/// * `allocRemainingAligned`
///
///
///
///
pub fn appendRemainingAligned(
r: *Reader,
gpa: Allocator,
comptime alignment: std.mem.Alignment,
list: *std.array_list.Aligned(u8, alignment),
limit: Limit,
) LimitedAllocError!void {
var a = std.Io.Writer.Allocating.fromArrayListAligned(gpa, alignment, list);
defer list.* = a.toArrayListAligned(alignment);
var remaining = limit;
while (remaining != .nothing) {
const n = stream(r, &a.writer, remaining) catch |err| switch (err) {
error.EndOfStream => return,
error.WriteFailed => return error.OutOfMemory,
error.ReadFailed => |e| return e,
};
remaining = remaining.subtract(n).?;
}
return error.StreamTooLong;
}
pub const UnlimitedAllocError = Allocator.Error || ShortError;
pub fn appendRemainingUnlimited(r: *Reader, gpa: Allocator, list: *ArrayList(u8)) UnlimitedAllocError!void {
list.pointer_stability.assertUnlocked();
var a: std.Io.Writer.Allocating = .initOwnedSlice(gpa, list.allocatedSlice());
a.writer.end = list.items.len;
list.* = .empty;
defer {
list.* = .{
.items = a.writer.buffer[0..a.writer.end],
.capacity = a.writer.buffer.len,
.pointer_stability = .{},
};
}
_ = streamRemaining(r, &a.writer) catch |err| switch (err) {
error.WriteFailed => return error.OutOfMemory,
error.ReadFailed => |e| return e,
};
}
/// 从内部跟踪的流位置向 `data` 写入字节。
///
/// 返回写入字节数,最少为 `0`,
/// 最多为所有 data 切片长度之和。读取字节数,
/// 包括零,都不表示流结束。
///
/// 读取器内部的逻辑寻址位置,按此函数
/// 返回的字节数向前移动。
pub fn readVec(r: *Reader, data: [][]u8) Error!usize {
var seek = r.seek;
for (data, 0..) |buf, i| {
const contents = r.buffer[seek..r.end];
const copy_len = @min(contents.len, buf.len);
@memcpy(buf[0..copy_len], contents[0..copy_len]);
seek += copy_len;
if (buf.len - copy_len == 0) continue;
// `buffer` 的全部内容已复制到 `data`。
const n = seek - r.seek;
r.seek = seek;
data[i] = buf[copy_len..];
defer data[i] = buf;
return n + (r.vtable.readVec(r, data[i..]) catch |err| switch (err) {
error.EndOfStream => if (n == 0) return error.EndOfStream else 0,
error.ReadFailed => |e| return e,
});
}
const n = seek - r.seek;
r.seek = seek;
return n;
}
/// 写入 `Reader.buffer` 或 `data` 中容量较大的一个。
pub fn defaultReadVec(r: *Reader, data: [][]u8) Error!usize {
const first = data[0];
if (first.len >= r.buffer.len - r.end) {
var writer: Writer = .{
.buffer = first,
.end = 0,
.vtable = &.{ .drain = Writer.fixedDrain },
};
const limit: Limit = .limited(writer.buffer.len - writer.end);
return r.vtable.stream(r, &writer, limit) catch |err| switch (err) {
error.WriteFailed => unreachable,
else => |e| return e,
};
}
var writer: Writer = .{
.buffer = r.buffer,
.end = r.end,
.vtable = &.{ .drain = Writer.fixedDrain },
};
const limit: Limit = .limited(writer.buffer.len - writer.end);
const n = r.vtable.stream(r, &writer, limit) catch |err| switch (err) {
error.WriteFailed => unreachable,
else => |e| return e,
};
r.end += n;
return 0;
}
pub fn buffered(r: *Reader) []u8 {
return r.buffer[r.seek..r.end];
}
pub fn bufferedLen(r: *const Reader) usize {
return r.end - r.seek;
}
pub fn hashed(r: *Reader, hasher: anytype, buffer: []u8) Hashed(@TypeOf(hasher)) {
return .init(r, hasher, buffer);
}
pub fn readVecAll(r: *Reader, data: [][]u8) Error!void {
var index: usize = 0;
var truncate: usize = 0;
while (index < data.len) {
{
const untruncated = data[index];
data[index] = untruncated[truncate..];
defer data[index] = untruncated;
truncate += try r.readVec(data[index..]);
}
while (index < data.len and truncate >= data[index].len) {
truncate -= data[index].len;
index += 1;
}
}
}
/// 返回流中的后续 `n` 字节,并按需填充
/// 缓冲区。
///
/// 使之前由 `peek` 返回的值失效。
///
/// 断言初始化 `Reader` 时使用的缓冲区容量
/// 至少为 `n`。
///
/// 如果流中剩余字节少于 `n`,
/// 则改为返回 `error.EndOfStream`。
///
/// 另见:
/// * `toss`
pub fn peek(r: *Reader, n: usize) Error![]u8 {
try r.fill(n);
return r.buffer[r.seek..][0..n];
}
/// 填充缓冲区,确保至少包含 `n` 个字节后,
/// 返回接下来所有已缓冲字节。
///
/// 使此前由 `peek` 和 `peekGreedy` 返回的值失效。
///
/// 断言 `Reader` 初始化时的缓冲区容量
/// 至少为 `n`。
///
/// 如果流中剩余字节数小于 `n`,则改为返回
/// `error.EndOfStream`。
///
/// 另请参见:
/// * `peek`
/// * `toss`
pub fn peekGreedy(r: *Reader, n: usize) Error![]u8 {
try r.fill(n);
return r.buffer[r.seek..r.end];
}
/// 跳过流中的后续 `n` 字节,推进查找位置。通常
/// 在 `peek` 之后安全地使用此函数。
///
/// 断言已缓冲字节数至少为 `n`。
///
/// 被“丢弃”的内存在发生“窥视”操作之前仍保持有效。
///
/// 另见:
/// * `peek`。
/// * `discard`。
pub fn toss(r: *Reader, n: usize) void {
r.seek += n;
assert(r.seek <= r.end);
}
/// 等价于 `toss(r.bufferedLen())`。
pub fn tossBuffered(r: *Reader) void {
r.seek = r.end;
}
/// 等同于先调用 `peek`,再调用 `toss`。
///
/// 下次调用 `take`、`peek`、`fill` 或以这些名称为前缀的函数时,返回数据失效。
///
pub fn take(r: *Reader, n: usize) Error![]u8 {
const result = try r.peek(n);
r.toss(n);
return result;
}
/// 以数组形式返回流中接下来的 `n` 个字节,必要时填充缓冲区,并将查找位置向前推进 `n` 字节。
///
/// 断言 `Reader` 初始化时的缓冲区容量至少为 `n`。
///
/// 若流中剩余字节少于 `n`,则改为返回 `error.EndOfStream`。
///
/// 另见:
/// * `take`
///
///
///
pub fn takeArray(r: *Reader, comptime n: usize) Error!*[n]u8 {
return (try r.take(n))[0..n];
}
/// 将流中接下来的 `n` 个字节作为数组返回,按需填充缓冲区,
/// 不推进寻址位置。
///
/// 断言 `Reader` 初始化时的缓冲区容量
/// 至少为 `n`。
///
/// 如果流中剩余字节数小于 `n`,则改为返回
/// `error.EndOfStream`。
///
/// 另请参见:
/// * `peek`
/// * `takeArray`
pub fn peekArray(r: *Reader, comptime n: usize) Error!*[n]u8 {
return (try r.peek(n))[0..n];
}
/// 跳过流中的后续 `n` 字节,推进查找位置。
///
/// 与不会失败的 `toss` 不同,此函数的 `n` 可以是任意大小。
///
/// 如果能够丢弃的字节少于 `n`,则返回 `error.EndOfStream`。
///
/// 另见:
/// * `toss`
/// * `discardRemaining`
/// * `discardShort`
/// * `discard`
pub fn discardAll(r: *Reader, n: usize) Error!void {
if ((try r.discardShort(n)) != n) return error.EndOfStream;
}
pub fn discardAll64(r: *Reader, n: u64) Error!void {
var remaining: u64 = n;
while (remaining > 0) {
const limited_remaining = std.math.cast(usize, remaining) orelse std.math.maxInt(usize);
try discardAll(r, limited_remaining);
remaining -= limited_remaining;
}
}
/// 跳过流中接下来的 `n` 个字节,推进寻址位置。
///
/// 与不会失败的 `toss` 不同,此函数中的 `n` 可以为任意数量。
///
/// 返回丢弃的字节数;当且仅当流到达
/// 末尾时,该数量小于 `n`。
///
/// 另请参见:
/// * `discardAll`
/// * `discardRemaining`
/// * `discard`
pub fn discardShort(r: *Reader, n: usize) ShortError!usize {
const proposed_seek = r.seek + n;
if (proposed_seek <= r.end) {
@branchHint(.likely);
r.seek = proposed_seek;
return n;
}
var remaining = n - (r.end - r.seek);
r.seek = r.end;
while (true) {
const discard_len = r.vtable.discard(r, .limited(remaining)) catch |err| switch (err) {
error.EndOfStream => return n - remaining,
error.ReadFailed => |e| return e,
};
remaining -= discard_len;
if (remaining == 0) return n;
}
}
/// 使用流中的后续 `buffer.len` 字节填满 `buffer`,推进
/// 查找位置。
///
/// 使之前由 `peek` 返回的值失效。
///
/// 如果无法完全填满提供的缓冲区,则改为返回
/// `error.EndOfStream`。
///
/// 另见:
/// * `peek`
/// * `readSliceShort`
pub fn readSliceAll(r: *Reader, buffer: []u8) Error!void {
const n = try readSliceShort(r, buffer);
if (n != buffer.len) return error.EndOfStream;
}
/// 用流中接下来的 `buffer.len` 个字节填充 `buffer`,推进
/// 寻址位置。
///
/// 使此前由 `peek` 返回的值失效。
///
/// 返回读取的字节数;当且仅当流到达
/// 末尾时,该数量小于 `buffer.len`。
///
/// 另请参见:
/// * `readSliceAll`
pub fn readSliceShort(r: *Reader, buffer: []u8) ShortError!usize {
const contents = r.buffer[r.seek..r.end];
const copy_len = @min(buffer.len, contents.len);
@memcpy(buffer[0..copy_len], contents[0..copy_len]);
r.seek += copy_len;
if (buffer.len - copy_len == 0) {
@branchHint(.likely);
return buffer.len;
}
var i: usize = copy_len;
var data: [1][]u8 = undefined;
while (true) {
data[0] = buffer[i..];
i += readVec(r, &data) catch |err| switch (err) {
error.EndOfStream => return i,
error.ReadFailed => |e| return e,
};
if (buffer.len - i == 0) return buffer.len;
}
}
/// 填充 `buffer`,使用流中接下来的 `buffer.len` 个字节,并推进查找位置。
///
/// 使此前从 `peek` 返回的值失效。
///
/// 若无法完整填充给定缓冲区,则返回 `error.EndOfStream`。
///
/// 此函数采用内联,以便在 `endian` 编译期已知且与宿主字节序一致时,消除无用代码。
///
/// 另见:
/// * `readSliceAll`
/// * `readSliceEndianAlloc`
///
///
///
pub inline fn readSliceEndian(
r: *Reader,
comptime Elem: type,
buffer: []Elem,
endian: std.builtin.Endian,
) Error!void {
try readSliceAll(r, @ptrCast(buffer));
if (native_endian != endian) std.mem.byteSwapAllElements(Elem, buffer);
}
pub const ReadAllocError = Error || Allocator.Error;
/// 函数采用内联,以便在 `endian` 在编译期已知且
/// 与宿主端序相同时,避免生成无用代码。
pub inline fn readSliceEndianAlloc(
r: *Reader,
allocator: Allocator,
comptime Elem: type,
len: usize,
endian: std.builtin.Endian,
) ReadAllocError![]Elem {
const dest = try allocator.alloc(Elem, len);
errdefer allocator.free(dest);
try r.readSliceEndian(Elem, dest, endian);
return dest;
}
/// 已弃用;请使用 readAllocAll。将在 0.17 之后移除。
pub const readAlloc = readAllocAll;
/// 使用 `allocator` 提供的缓冲区调用 `readSliceAll` 的快捷操作。
pub fn readAllocAll(r: *Reader, allocator: Allocator, len: usize) ReadAllocError![]u8 {
const dest = try allocator.alloc(u8, len);
errdefer allocator.free(dest);
try readSliceAll(r, dest);
return dest;
}
/// 使用 `allocator` 提供的缓冲区调用 `readSliceShort` 的快捷方法;若流到达末尾,则收缩分配。
///
pub fn readAllocShort(r: *Reader, allocator: Allocator, len: usize) ReadAllocError![]u8 {
const dest = try allocator.alloc(u8, len);
errdefer allocator.free(dest);
const n = try readSliceShort(r, dest);
if (n == dest.len) return dest;
return try allocator.realloc(dest, n);
}
pub const DelimiterError = error{
/// 详细诊断参见 `Reader` 的实现。
ReadFailed,
/// 对于“包含分隔符”的函数,流在找到分隔符前结束。
/// 对于“不包含分隔符”的函数,流已结束,
/// 没有更多字节可返回。
EndOfStream,
/// 在与 `Reader` 容量相等的字节数范围内
/// 未找到分隔符。
StreamTooLong,
};
/// 返回流中接下来的缓冲数据切片,直到找到 `sentinel`,并将查找位置推进到哨兵之后。
///
/// 返回的切片带有哨兵。
///
/// 使此前从 `peek` 返回的值失效。
///
/// 另见:
/// * `peekSentinel`
/// * `takeDelimiterExclusive`
/// * `takeDelimiterInclusive`
///
pub fn takeSentinel(r: *Reader, comptime sentinel: u8) DelimiterError![:sentinel]u8 {
const result = try r.peekSentinel(sentinel);
r.toss(result.len + 1);
return result;
}
/// 返回流中接下来的缓冲数据切片,直到找到 `sentinel`,不推进查找位置。
///
/// 返回的切片带有哨兵;流结束不视为分隔符。
///
/// 使此前从 `peek` 返回的值失效。
///
/// 另见:
/// * `takeSentinel`
/// * `peekDelimiterExclusive`
/// * `peekDelimiterInclusive`
///
pub fn peekSentinel(r: *Reader, comptime sentinel: u8) DelimiterError![:sentinel]u8 {
const result = try r.peekDelimiterInclusive(sentinel);
return result[0 .. result.len - 1 :sentinel];
}
/// 返回流中接下来的缓冲数据切片,直到找到 `delimiter`,并将查找位置推进到分隔符之后。
///
/// 返回切片的最后一个字节包含该分隔符。
///
/// 使此前从 `peek` 返回的值失效。
///
/// 另见:
/// * `takeSentinel`
/// * `takeDelimiterExclusive`
/// * `peekDelimiterInclusive`
///
pub fn takeDelimiterInclusive(r: *Reader, delimiter: u8) DelimiterError![]u8 {
const result = try r.peekDelimiterInclusive(delimiter);
r.toss(result.len);
return result;
}
/// 返回流中接下来的缓冲数据字节的切片,直到找到
/// `delimiter`,不推进寻址位置。
///
/// 返回切片包括分隔符,分隔符为最后一个字节。
///
/// 使此前由 `peek` 返回的值失效。
///
/// 另请参见:
/// * `peekSentinel`
/// * `peekDelimiterExclusive`
/// * `takeDelimiterInclusive`
pub fn peekDelimiterInclusive(r: *Reader, delimiter: u8) DelimiterError![]u8 {
{
const contents = r.buffer[0..r.end];
const seek = r.seek;
if (std.mem.findScalarPos(u8, contents, seek, delimiter)) |end| {
@branchHint(.likely);
return contents[seek .. end + 1];
}
}
while (true) {
const content_len = r.end - r.seek;
if (r.buffer.len - content_len == 0) break;
try fillMore(r);
const seek = r.seek;
const contents = r.buffer[0..r.end];
if (std.mem.findScalarPos(u8, contents, seek + content_len, delimiter)) |end| {
return contents[seek .. end + 1];
}
}
// 此时可能已到流末尾,也可能没有,但已无剩余缓冲空间来区分。
// 若将 `StreamTooLong` 添加到 `RebaseError`,即可移除上述 while 循环的退出条件,替代此处逻辑。该错误码可用于表示 `buffer` 容量不足以执行操作,替代当前的断言。
//
//
//
var failing_writer = Writer.failing;
while (r.vtable.stream(r, &failing_writer, .limited(1))) |n| {
assert(n == 0);
} else |err| switch (err) {
error.WriteFailed => return error.StreamTooLong,
error.ReadFailed => |e| return e,
error.EndOfStream => |e| return e,
}
}
/// 返回流中接下来缓冲数据的切片,直到找到
/// `delimiter`,并将查找位置前移至分隔符之前,
/// 但不越过分隔符。
///
/// 返回的切片不含分隔符。流结束等同于
/// 遇到分隔符;但若这会返回长度为 0 的切片,
/// 则改为返回 `error.EndOfStream`。
///
/// 若检查了与此 `Reader` 容量相同数量的
/// 字节后仍未找到分隔符,返回 `error.StreamTooLong`。
/// 此时流状态不变,就像从未调用过
/// 此函数。
///
/// 此前 `peek` 返回的值将失效。
///
/// 另请参见:
/// * `takeDelimiter`
/// * `takeDelimiterInclusive`
/// * `peekDelimiterExclusive`
pub fn takeDelimiterExclusive(r: *Reader, delimiter: u8) DelimiterError![]u8 {
const result = try r.peekDelimiterExclusive(delimiter);
r.toss(result.len);
return result;
}
/// 返回流中接下来的缓冲数据字节的切片,直到找到
/// `delimiter`,并将寻址位置推进到分隔符之后。
///
/// 返回切片不含分隔符。流结束等同于
/// 分隔符,但如果这会返回长度为 0 的切片,
/// 则改为返回 `null`。
///
/// 如果在等于此 `Reader` 容量的字节范围内
/// 未找到分隔符,则返回 `error.StreamTooLong`。
/// 此时流状态保持不变,如同未曾调用
/// 此函数。
///
/// 使此前由 `peek` 返回的值失效。
///
/// 另请参见:
/// * `takeDelimiterInclusive`
/// * `takeDelimiterExclusive`
pub fn takeDelimiter(r: *Reader, delimiter: u8) error{ ReadFailed, StreamTooLong }!?[]u8 {
const inclusive = r.peekDelimiterInclusive(delimiter) catch |err| switch (err) {
error.EndOfStream => {
const remaining = r.buffer[r.seek..r.end];
if (remaining.len == 0) return null;
r.toss(remaining.len);
return remaining;
},
else => |e| return e,
};
r.toss(inclusive.len);
return inclusive[0 .. inclusive.len - 1];
}
/// 返回流中接下来缓冲数据的切片,直到找到
/// `delimiter`,不前移查找位置。
///
/// 返回的切片不含分隔符。流结束等同于
/// 遇到分隔符;但若这会返回长度为 0 的切片,
/// 则改为返回 `error.EndOfStream`。
///
/// 若检查了与此 `Reader` 容量相同数量的
/// 字节后仍未找到分隔符,返回 `error.StreamTooLong`。
/// 此时流状态不变,就像从未调用过
/// 此函数。
///
/// 此前 `peek` 返回的值将失效。
///
/// 另请参见:
/// * `peekDelimiterInclusive`
/// * `takeDelimiterExclusive`
pub fn peekDelimiterExclusive(r: *Reader, delimiter: u8) DelimiterError![]u8 {
const result = r.peekDelimiterInclusive(delimiter) catch |err| switch (err) {
error.EndOfStream => {
const remaining = r.buffer[r.seek..r.end];
if (remaining.len == 0) return error.EndOfStream;
return remaining;
},
else => |e| return e,
};
return result[0 .. result.len - 1];
}
/// 从流读取并追加到 `w`,直到找到 `delimiter`。不写入分隔符本身。
///
/// 不从 `Reader` 丢弃分隔符。
///
/// 返回传输的字节数,可能为零;若未找到分隔符,则返回 error.EndOfStream。
///
/// 断言缓冲区容量至少为一。更大的缓冲区可提高此函数的性能。
///
/// 另见:
/// * `streamDelimiterEnding`
/// * `streamDelimiterLimit`
///
///
///
pub fn streamDelimiter(r: *Reader, w: *Writer, delimiter: u8) StreamError!usize {
const n = streamDelimiterLimit(r, w, delimiter, .unlimited) catch |err| switch (err) {
error.StreamTooLong => unreachable, // 传入 unlimited
else => |e| return e,
};
if (r.seek == r.end) return error.EndOfStream;
return n;
}
/// 向 `w` 追加从流中读取的内容,直到找到 `delimiter`。
/// 不写入分隔符本身。
///
/// 返回流式传输的字节数,可以为零。若流到达
/// 末尾,此函数返回时读取器缓冲区为空。
/// 否则,缓冲区至少包含一个字节,且第一个字节
/// 为分隔符。
///
/// 断言缓冲区容量至少为一。
/// 缓冲区越大,此函数性能越好。
///
/// 另请参见:
/// * `streamDelimiter`
/// * `streamDelimiterLimit`
pub fn streamDelimiterEnding(
r: *Reader,
w: *Writer,
delimiter: u8,
) StreamRemainingError!usize {
return streamDelimiterLimit(r, w, delimiter, .unlimited) catch |err| switch (err) {
error.StreamTooLong => unreachable, // 传入 unlimited
else => |e| return e,
};
}
pub const StreamDelimiterLimitError = error{
ReadFailed,
WriteFailed,
/// 在限制内未找到分隔符。
StreamTooLong,
};
/// 从流读取并追加到 `w`,直到找到 `delimiter`。
/// 不写入分隔符本身。
///
/// 不从 `Reader` 丢弃分隔符。
///
/// 返回传输的字节数,可能为零。可以检查流中的下一个字节是否为分隔符,以检测流结束。
///
/// 断言缓冲区容量至少为一。更大的缓冲区可提高此函数的性能。
///
///
pub fn streamDelimiterLimit(
r: *Reader,
w: *Writer,
delimiter: u8,
limit: Limit,
) StreamDelimiterLimitError!usize {
var remaining = @backingInt(limit);
while (remaining != 0) {
const available = Limit.limited(remaining).slice(r.peekGreedy(1) catch |err| switch (err) {
error.ReadFailed => |e| return e,
error.EndOfStream => return @backingInt(limit) - remaining,
});
if (std.mem.findScalar(u8, available, delimiter)) |delimiter_index| {
try w.writeAll(available[0..delimiter_index]);
r.toss(delimiter_index);
remaining -= delimiter_index;
return @backingInt(limit) - remaining;
}
try w.writeAll(available);
r.toss(available.len);
remaining -= available.len;
}
return error.StreamTooLong;
}
/// 从流中读取直到找到指定字节,丢弃所有数据,
/// 包括分隔符。
///
/// 返回丢弃的字节数;未找到分隔符时返回 `error.EndOfStream`。
///
/// 另见:
/// * `discardDelimiterExclusive`
/// * `discardDelimiterLimit`
///
pub fn discardDelimiterInclusive(r: *Reader, delimiter: u8) Error!usize {
const n = discardDelimiterLimit(r, delimiter, .unlimited) catch |err| switch (err) {
error.StreamTooLong => unreachable, // 传入 unlimited
else => |e| return e,
};
if (r.seek == r.end) return error.EndOfStream;
assert(r.buffer[r.seek] == delimiter);
toss(r, 1);
return n + 1;
}
/// 从流中读取直到发现指定字节,丢弃所有数据,
/// 但不包括分隔符。
///
/// 返回丢弃的字节数。
///
/// 在找到分隔符之前流就结束时也会成功。可通过检查
/// 分隔符是否已缓冲来判断流是否结束。
///
/// 另见:
/// * `discardDelimiterInclusive`
/// * `discardDelimiterLimit`
pub fn discardDelimiterExclusive(r: *Reader, delimiter: u8) ShortError!usize {
return discardDelimiterLimit(r, delimiter, .unlimited) catch |err| switch (err) {
error.StreamTooLong => unreachable, // 传入 unlimited
else => |e| return e,
};
}
pub const DiscardDelimiterLimitError = error{
ReadFailed,
/// 在限制内未找到分隔符。
StreamTooLong,
};
/// 从流中读取直到发现指定字节,丢弃所有数据,
/// 但不包括分隔符。
///
/// 返回丢弃的字节数。
///
/// 在找到分隔符之前流就结束时也会成功。可通过检查
/// 分隔符是否已缓冲来判断流是否结束。
pub fn discardDelimiterLimit(r: *Reader, delimiter: u8, limit: Limit) DiscardDelimiterLimitError!usize {
var remaining = @backingInt(limit);
while (remaining != 0) {
const available = Limit.limited(remaining).slice(r.peekGreedy(1) catch |err| switch (err) {
error.ReadFailed => |e| return e,
error.EndOfStream => return @backingInt(limit) - remaining,
});
if (std.mem.findScalar(u8, available, delimiter)) |delimiter_index| {
r.toss(delimiter_index);
remaining -= delimiter_index;
return @backingInt(limit) - remaining;
}
r.toss(available.len);
remaining -= available.len;
}
return error.StreamTooLong;
}
/// 填充缓冲区,使其至少包含 `n` 个字节,
/// 不推进寻址位置。
///
/// 当且仅当剩余字节数小于 `n` 时,返回
/// `error.EndOfStream`。
///
/// 如果未遇到流结束,则断言缓冲区容量
/// 至少为 `n`。
pub fn fill(r: *Reader, n: usize) Error!void {
if (r.seek + n <= r.end) {
@branchHint(.likely);
return;
}
return fillUnbuffered(r, n);
}
/// 将此内部函数与 `fill` 分离,以促使优化器内联 `fill`,从而
/// 将其 `@branchHint` 传播到使用位置。如果将它们合并,`fill` 会大到
/// LLVM 不愿内联它,迫使 `takeInt` 等 API 的使用方执行
/// 代价高昂的运行时函数调用,仅仅为了确认数据其实已经位于
/// 缓冲区中。
///
/// 缺少此优化可能使受影响最严重的基准测试的实际耗时
/// 增加到原来的 5 倍甚至更多。
fn fillUnbuffered(r: *Reader, n: usize) Error!void {
try rebase(r, n);
var bufs: [1][]u8 = .{""};
while (r.end < r.seek + n) _ = try r.vtable.readVec(r, &bufs);
}
/// 不推进查找位置,仅执行一次底层读取,尽可能
/// 填满缓冲区。这可能不向缓冲区添加任何字节,但这不表示流
/// 已结束。通过返回 `error.EndOfStream` 表示流结束。
///
/// 断言缓冲区容量至少为 1。
pub fn fillMore(r: *Reader) Error!void {
try rebase(r, r.end - r.seek + 1);
var bufs: [1][]u8 = .{""};
_ = try r.vtable.readVec(r, &bufs);
}
/// 返回流中的下一个字节,或返回 `error.EndOfStream`。
///
/// 不推进查找位置。
///
/// 断言缓冲区容量非零。
pub fn peekByte(r: *Reader) Error!u8 {
const buffer = r.buffer[0..r.end];
const seek = r.seek;
if (seek < buffer.len) {
@branchHint(.likely);
return buffer[seek];
}
try fill(r, 1);
return r.buffer[r.seek];
}
/// 从流中读取 1 字节,否则返回 `error.EndOfStream`。
///
/// 断言缓冲区容量非零。
pub fn takeByte(r: *Reader) Error!u8 {
const result = try peekByte(r);
r.seek += 1;
return result;
}
/// 与 `takeByte` 相同,但返回的字节有符号。
pub fn takeByteSigned(r: *Reader) Error!i8 {
return @bitCast(try r.takeByte());
}
/// 断言缓冲区初始化时容量至少为 `@bitSizeOf(T) / 8`。
pub inline fn takeInt(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T {
const n = @divExact(@typeInfo(T).int.bits, 8);
return std.mem.readInt(T, try r.takeArray(n), endian);
}
/// 断言缓冲区初始化时容量至少为 `@bitSizeOf(T) / 8`。
pub inline fn peekInt(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T {
const n = @divExact(@typeInfo(T).int.bits, 8);
return std.mem.readInt(T, try r.peekArray(n), endian);
}
/// 断言缓冲区初始化时容量至少为 `n`。
pub fn takeVarInt(r: *Reader, comptime Int: type, endian: std.builtin.Endian, n: usize) Error!Int {
assert(n <= @sizeOf(Int));
return std.mem.readVarInt(Int, try r.take(n), endian);
}
/// 获取指向流开头的未对齐指针,将其重新解释为
/// 指向所提供类型的指针,并推进查找位置。
///
/// 断言缓冲区初始化时的容量至少为 `@sizeOf(T)`。
///
/// 另见:
/// * `peekStructPointer`
/// * `takeStruct`
pub fn takeStructPointer(r: *Reader, comptime T: type) Error!*align(1) T {
// 只有 extern 和 packed 结构体具有明确定义的内存布局。
comptime assert(@typeInfo(T).@"struct".layout != .auto);
return @ptrCast(try r.takeArray(@sizeOf(T)));
}
/// 取得指向流起始位置的未对齐指针,重新解释为
/// 指向给定类型的指针,不推进寻址位置。
///
/// 断言缓冲区初始化容量至少为 `@sizeOf(T)`。
///
/// 另请参见:
/// * `takeStructPointer`
/// * `peekStruct`
pub fn peekStructPointer(r: *Reader, comptime T: type) Error!*align(1) T {
// 只有 extern 和 packed 结构体具有明确定义的内存布局。
comptime assert(@typeInfo(T).@"struct".layout != .auto);
return @ptrCast(try r.peekArray(@sizeOf(T)));
}
/// 此函数内联,以免在 `endian` 编译期已知且与宿主字节序相同时,
/// 仍引用 `std.mem.byteSwapAllFields`。
///
/// 另见:
/// * `takeStructPointer`
/// * `peekStruct`
pub inline fn takeStruct(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T {
switch (@typeInfo(T)) {
.@"struct" => |info| switch (info.layout) {
.auto => @compileError("ill-defined memory layout"),
.@"extern" => {
var res: T = undefined;
try r.readSliceEndian(T, (&res)[0..1], endian);
return res;
},
.@"packed" => {
return @bitCast(try takeInt(r, info.backing_integer.?, endian));
},
},
else => @compileError("not a struct"),
}
}
/// 断言缓冲区初始化容量至少为 `@sizeOf(T)`。
///
/// 此函数内联,以便 `endian` 在编译期已知且与宿主字节序一致时,
/// 避免引用 `std.mem.byteSwapAllFields`。
///
/// 另请参见:
/// * `takeStruct`
/// * `peekStructPointer`
pub inline fn peekStruct(r: *Reader, comptime T: type, endian: std.builtin.Endian) Error!T {
switch (@typeInfo(T)) {
.@"struct" => |info| switch (info.layout) {
.auto => @compileError("ill-defined memory layout"),
.@"extern" => {
var res = (try r.peekStructPointer(T)).*;
if (native_endian != endian) std.mem.byteSwapAllFields(T, &res);
return res;
},
.@"packed" => {
return @bitCast(try peekInt(r, info.backing_integer.?, endian));
},
},
else => @compileError("not a struct"),
}
}
pub const TakeEnumError = Error || error{InvalidEnumTag};
/// 读取与给定枚举标签类型大小相同的整数。
/// 若整数匹配某个枚举标签,将其转换为该标签并返回;否则返回 `error.InvalidEnumTag`。
///
/// 断言初始化缓冲区时的容量至少为 `@sizeOf(Enum)`。
///
pub fn takeEnum(r: *Reader, comptime Enum: type, endian: std.builtin.Endian) TakeEnumError!Enum {
const Tag = @typeInfo(Enum).@"enum".tag_type;
const int = try r.takeInt(Tag, endian);
return std.enums.fromInt(Enum, int) orelse return error.InvalidEnumTag;
}
/// 读取一个与给定非穷尽枚举标签类型大小相同的整数。
///
/// 断言缓冲区初始化容量至少为 `@sizeOf(Enum)`。
pub fn takeEnumNonexhaustive(r: *Reader, comptime Enum: type, endian: std.builtin.Endian) Error!Enum {
const info = @typeInfo(Enum).@"enum";
comptime assert(info.mode != .exhaustive);
comptime assert(@bitSizeOf(info.tag_type) == @sizeOf(info.tag_type) * 8);
return takeEnum(r, Enum, endian) catch |err| switch (err) {
error.InvalidEnumTag => unreachable,
else => |e| return e,
};
}
pub const TakeLeb128Error = Error || error{Overflow};
/// 读取单个 LEB128 值为类型 T;若无法表示该值,则返回 `error.Overflow`。
pub fn takeLeb128(r: *Reader, comptime T: type) TakeLeb128Error!T {
const info = switch (@typeInfo(T)) {
.int => |info| info,
else => @compileError(@typeName(T) ++ " not supported"),
};
const Byte = packed struct { bits: u7, more: bool };
if (info.bits <= 7) {
var byte: Byte = undefined;
const Bits = @Int(info.signedness, 7);
byte = @bitCast(try r.takeByte());
const val = std.math.cast(T, @as(Bits, @bitCast(byte.bits))) orelse error.Overflow;
const allowed_bits: u7 = switch (info.signedness) {
.unsigned => 0,
.signed => @bitCast(@as(i7, @bitCast(byte.bits)) >> 6),
};
var fits = true;
while (byte.more) {
byte = @bitCast(try r.takeByte());
if (byte.bits != allowed_bits) fits = false;
}
return if (fits) blk: {
@branchHint(.likely);
break :blk val;
} else error.Overflow;
}
const Unsigned = @Int(.unsigned, info.bits);
const UInt = std.math.ByteAlignedInt(Unsigned);
const Int = std.math.ByteAlignedInt(T);
const uint_bits = @typeInfo(UInt).int.bits;
var byte: Byte = undefined;
var val: UInt = 0;
const max_bytes = @divFloor(info.bits - 1, 7) + 1;
inline for (0..max_bytes) |iteration| {
const shift = iteration * 7;
byte = @bitCast(try r.takeByte());
const extended: UInt = byte.bits;
val |= extended << shift;
const bits_written = shift + 7;
if (bits_written >= info.bits) {
const bits_overflowed = bits_written - info.bits;
const bits_remaining = @mod(info.bits, 7);
const allowed_bits: u7, var fits: bool = switch (info.signedness) {
.unsigned => blk: {
const fits = bits_remaining == 0 or byte.bits >> bits_remaining == 0;
break :blk .{ 0, fits };
},
.signed => blk: {
const bits: i7 = @bitCast(byte.bits);
// 将符号位移至最高有效位
const shifted_bits: i7 = bits << bits_overflowed;
const value_sign: i7 = shifted_bits >> 6; // 符号扩展
const bits_sign: i7 = bits >> bits_remaining; // 符号扩展
const fits = bits_remaining == 0 or bits_sign == value_sign;
if (uint_bits != info.bits and value_sign != 0) {
const sign_extend_mask = @as(UInt, std.math.maxInt(UInt)) << info.bits;
val |= sign_extend_mask;
}
break :blk .{ @bitCast(value_sign), fits };
},
};
switch (info.signedness) {
.signed => assert(allowed_bits == 0 or allowed_bits == 0x7F),
.unsigned => comptime assert(allowed_bits == 0),
}
while (byte.more) {
byte = @bitCast(try r.takeByte());
if (byte.bits != allowed_bits) fits = false;
}
return if (fits) blk: {
@branchHint(.likely);
break :blk std.math.cast(T, @as(Int, @bitCast(val))) orelse error.Overflow;
} else error.Overflow;
}
comptime assert(bits_written < info.bits);
if (!byte.more) {
if (info.signedness == .signed and // 可以为负数
byte.bits & 0x40 != 0) // 为负数
{
const sign_extend_mask = @as(UInt, std.math.maxInt(UInt)) << bits_written;
val |= sign_extend_mask;
}
return std.math.cast(T, @as(Int, @bitCast(val))) orelse error.Overflow;
}
}
}
/// 确保无需调整基址即可缓冲 `capacity` 大小的数据。
pub fn rebase(r: *Reader, capacity: usize) Error!void {
if (r.buffer.len - r.seek >= capacity) {
@branchHint(.likely);
return;
}
return r.vtable.rebase(r, capacity);
}
pub fn defaultRebase(r: *Reader, capacity: usize) Error!void {
assert(r.buffer.len - r.seek < capacity);
const data = r.buffer[r.seek..r.end];
@memmove(r.buffer[0..data.len], data);
r.seek = 0;
r.end = data.len;
assert(r.buffer.len - r.seek >= capacity);
}
test fixed {
var r: Reader = .fixed("a\x02");
try testing.expect((try r.takeByte()) == 'a');
try testing.expect((try r.takeEnum(enum(u8) {
a = 0,
b = 99,
c = 2,
d = 3,
}, builtin.cpu.arch.endian())) == .c);
try testing.expectError(error.EndOfStream, r.takeByte());
}
test peek {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.peek(2));
try testing.expectEqualStrings("a", try r.peek(1));
}
test peekGreedy {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("abc", try r.peekGreedy(1));
}
test toss {
var r: Reader = .fixed("abc");
r.toss(1);
try testing.expectEqualStrings("bc", r.buffered());
}
test take {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.take(2));
try testing.expectEqualStrings("c", try r.take(1));
}
test takeArray {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.takeArray(2));
try testing.expectEqualStrings("c", try r.takeArray(1));
}
test peekArray {
var r: Reader = .fixed("abc");
try testing.expectEqualStrings("ab", try r.peekArray(2));
try testing.expectEqualStrings("a", try r.peekArray(1));
}
test discardAll {
var r: Reader = .fixed("foobar");
try r.discardAll(3);
try testing.expectEqualStrings("bar", try r.take(3));
try r.discardAll(0);
try testing.expectError(error.EndOfStream, r.discardAll(1));
}
test discardRemaining {
var r: Reader = .fixed("foobar");
r.toss(1);
try testing.expectEqual(5, try r.discardRemaining());
try testing.expectEqual(0, try r.discardRemaining());
}
test stream {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foobar");
var w: Writer = .fixed(&out_buffer);
// 此函数支持短流,而 fixed 不支持。
try testing.expectEqual(2, try r.stream(&w, .limited(2)));
try testing.expectEqualStrings("fo", w.buffered());
try testing.expectEqual(4, try r.stream(&w, .unlimited));
try testing.expectEqualStrings("foobar", w.buffered());
}
test takeSentinel {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.takeSentinel('\n'));
try testing.expectError(error.EndOfStream, r.takeSentinel('\n'));
try testing.expectEqualStrings("c", try r.peek(1));
}
test peekSentinel {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.peekSentinel('\n'));
try testing.expectEqualStrings("ab", try r.peekSentinel('\n'));
r.toss(3);
try testing.expectError(error.EndOfStream, r.peekSentinel('\n'));
try testing.expectEqualStrings("c", try r.peek(1));
}
test takeDelimiterInclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab\n", try r.takeDelimiterInclusive('\n'));
try testing.expectError(error.EndOfStream, r.takeDelimiterInclusive('\n'));
}
test peekDelimiterInclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab\n", try r.peekDelimiterInclusive('\n'));
try testing.expectEqualStrings("ab\n", try r.peekDelimiterInclusive('\n'));
r.toss(3);
try testing.expectError(error.EndOfStream, r.peekDelimiterInclusive('\n'));
try testing.expectEqualStrings("c", try r.peek(1));
}
test takeDelimiterExclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.takeDelimiterExclusive('\n'));
try testing.expectEqualStrings("", try r.takeDelimiterExclusive('\n'));
try testing.expectEqualStrings("", try r.takeDelimiterExclusive('\n'));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqualStrings("c", try r.takeDelimiterExclusive('\n'));
try testing.expectError(error.EndOfStream, r.takeDelimiterExclusive('\n'));
}
test peekDelimiterExclusive {
var r: Reader = .fixed("ab\nc");
try testing.expectEqualStrings("ab", try r.peekDelimiterExclusive('\n'));
try testing.expectEqualStrings("ab", try r.peekDelimiterExclusive('\n'));
r.toss(2);
try testing.expectEqualStrings("", try r.peekDelimiterExclusive('\n'));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqualStrings("c", try r.peekDelimiterExclusive('\n'));
try testing.expectEqualStrings("c", try r.peekDelimiterExclusive('\n'));
r.toss(1);
try testing.expectError(error.EndOfStream, r.peekDelimiterExclusive('\n'));
}
test takeDelimiter {
var r: Reader = .fixed("ab\nc\n\nd");
try testing.expectEqualStrings("ab", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("c", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("d", (try r.takeDelimiter('\n')).?);
try testing.expectEqual(null, try r.takeDelimiter('\n'));
try testing.expectEqual(null, try r.takeDelimiter('\n'));
r = .fixed("ab\nc\n\nd\n"); // 单个尾随换行符不影响行为
try testing.expectEqualStrings("ab", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("c", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("", (try r.takeDelimiter('\n')).?);
try testing.expectEqualStrings("d", (try r.takeDelimiter('\n')).?);
try testing.expectEqual(null, try r.takeDelimiter('\n'));
try testing.expectEqual(null, try r.takeDelimiter('\n'));
}
test streamDelimiter {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foo\nbars");
var w: Writer = .fixed(&out_buffer);
try testing.expectEqual(3, try r.streamDelimiter(&w, '\n'));
try testing.expectEqualStrings("foo", w.buffered());
try testing.expectEqual(0, try r.streamDelimiter(&w, '\n'));
r.toss(1);
try testing.expectError(error.EndOfStream, r.streamDelimiter(&w, '\n'));
}
test streamDelimiterEnding {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foo\nbars");
var w: Writer = .fixed(&out_buffer);
try testing.expectEqual(3, try r.streamDelimiterEnding(&w, '\n'));
try testing.expectEqualStrings("foo", w.buffered());
r.toss(1);
try testing.expectEqual(4, try r.streamDelimiterEnding(&w, '\n'));
try testing.expectEqualStrings("foobars", w.buffered());
try testing.expectEqual(0, try r.streamDelimiterEnding(&w, '\n'));
try testing.expectEqual(0, try r.streamDelimiterEnding(&w, '\n'));
}
test streamDelimiterLimit {
var out_buffer: [10]u8 = undefined;
var r: Reader = .fixed("foo\nbars");
var w: Writer = .fixed(&out_buffer);
try testing.expectError(error.StreamTooLong, r.streamDelimiterLimit(&w, '\n', .limited(2)));
try testing.expectEqual(1, try r.streamDelimiterLimit(&w, '\n', .limited(3)));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqual(4, try r.streamDelimiterLimit(&w, '\n', .unlimited));
try testing.expectEqualStrings("foobars", w.buffered());
}
test discardDelimiterExclusive {
var r: Reader = .fixed("foob\nar");
try testing.expectEqual(4, try r.discardDelimiterExclusive('\n'));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqual(2, try r.discardDelimiterExclusive('\n'));
try testing.expectEqual(0, try r.discardDelimiterExclusive('\n'));
}
test discardDelimiterInclusive {
var r: Reader = .fixed("foob\nar");
try testing.expectEqual(5, try r.discardDelimiterInclusive('\n'));
try testing.expectError(error.EndOfStream, r.discardDelimiterInclusive('\n'));
}
test discardDelimiterLimit {
var r: Reader = .fixed("foob\nar");
try testing.expectError(error.StreamTooLong, r.discardDelimiterLimit('\n', .limited(4)));
try testing.expectEqual(0, try r.discardDelimiterLimit('\n', .limited(2)));
try testing.expectEqualStrings("\n", try r.take(1));
try testing.expectEqual(2, try r.discardDelimiterLimit('\n', .unlimited));
try testing.expectEqual(0, try r.discardDelimiterLimit('\n', .unlimited));
}
test fill {
var r: Reader = .fixed("abc");
try r.fill(1);
try r.fill(3);
}
test takeByte {
var r: Reader = .fixed("ab");
try testing.expectEqual('a', try r.takeByte());
try testing.expectEqual('b', try r.takeByte());
try testing.expectError(error.EndOfStream, r.takeByte());
}
test takeByteSigned {
var r: Reader = .fixed(&.{ 255, 5 });
try testing.expectEqual(-1, try r.takeByteSigned());
try testing.expectEqual(5, try r.takeByteSigned());
try testing.expectError(error.EndOfStream, r.takeByteSigned());
}
test takeInt {
var r: Reader = .fixed(&.{ 0x12, 0x34, 0x56 });
try testing.expectEqual(0x1234, try r.takeInt(u16, .big));
try testing.expectError(error.EndOfStream, r.takeInt(u16, .little));
}
test takeVarInt {
var r: Reader = .fixed(&.{ 0x12, 0x34, 0x56 });
try testing.expectEqual(0x123456, try r.takeVarInt(u64, .big, 3));
try testing.expectError(error.EndOfStream, r.takeVarInt(u16, .little, 1));
}
test takeStructPointer {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
switch (native_endian) {
.little => try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), (try r.takeStructPointer(S)).*),
.big => try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), (try r.takeStructPointer(S)).*),
}
try testing.expectError(error.EndOfStream, r.takeStructPointer(S));
}
test peekStructPointer {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
switch (native_endian) {
.little => {
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), (try r.peekStructPointer(S)).*);
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), (try r.peekStructPointer(S)).*);
},
.big => {
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), (try r.peekStructPointer(S)).*);
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), (try r.peekStructPointer(S)).*);
},
}
}
test takeStruct {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), try r.takeStruct(S, .big));
try testing.expectError(error.EndOfStream, r.takeStruct(S, .little));
}
test peekStruct {
var r: Reader = .fixed(&.{ 0x12, 0x00, 0x34, 0x56 });
const S = extern struct { a: u8, b: u16 };
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x3456 }), try r.peekStruct(S, .big));
try testing.expectEqual(@as(S, .{ .a = 0x12, .b = 0x5634 }), try r.peekStruct(S, .little));
}
test takeEnum {
var r: Reader = .fixed(&.{ 2, 0, 1 });
const E1 = enum(u8) { a, b, c };
const E2 = enum(u16) { _ };
try testing.expectEqual(E1.c, try r.takeEnum(E1, .little));
try testing.expectEqual(@as(E2, @fromBackingInt(@intCast(0x0001))), try r.takeEnum(E2, .big));
}
test readSliceShort {
var r: Reader = .fixed("HelloFren");
var buf: [5]u8 = undefined;
try testing.expectEqual(5, try r.readSliceShort(&buf));
try testing.expectEqualStrings("Hello", buf[0..5]);
try testing.expectEqual(4, try r.readSliceShort(&buf));
try testing.expectEqualStrings("Fren", buf[0..4]);
try testing.expectEqual(0, try r.readSliceShort(&buf));
}
test "readSliceShort with smaller buffer than Reader" {
var reader_buf: [15]u8 = undefined;
const str = "This is a test";
var one_byte_stream: testing.Reader = .init(&reader_buf, &.{
.{ .buffer = str },
});
one_byte_stream.artificial_limit = .limited(1);
var buf: [14]u8 = undefined;
try testing.expectEqual(14, try one_byte_stream.interface.readSliceShort(&buf));
try testing.expectEqualStrings(str, &buf);
}
test "readSliceShort with indirect reader" {
var r: Reader = .fixed("HelloFren");
var ri_buf: [3]u8 = undefined;
var ri: std.testing.ReaderIndirect = .init(&r, &ri_buf);
var buf: [5]u8 = undefined;
try testing.expectEqual(5, try ri.interface.readSliceShort(&buf));
try testing.expectEqualStrings("Hello", buf[0..5]);
try testing.expectEqual(4, try ri.interface.readSliceShort(&buf));
try testing.expectEqualStrings("Fren", buf[0..4]);
try testing.expectEqual(0, try ri.interface.readSliceShort(&buf));
}
test readAllocAll {
const allocator = testing.allocator;
var r: Reader = .fixed("HelloFren");
const s1 = try r.readAllocAll(allocator, 5);
defer allocator.free(s1);
try testing.expectEqualStrings("Hello", s1);
const s2 = try r.readAllocAll(allocator, 4);
defer allocator.free(s2);
try testing.expectEqualStrings("Fren", s2);
}
test "readAllocAll with buffer bigger than content" {
const allocator = testing.allocator;
var r: Reader = .fixed("HelloFren");
const s1 = try r.readAllocAll(allocator, 5);
defer allocator.free(s1);
try testing.expectEqualStrings("Hello", s1);
const res = r.readAllocAll(allocator, 10);
try testing.expectError(Error.EndOfStream, res);
}
test readAllocShort {
var r: Reader = .fixed("HelloFren");
const s1 = try r.readAllocShort(testing.allocator, 5);
defer testing.allocator.free(s1);
try testing.expectEqualStrings("Hello", s1);
const s2 = try r.readAllocShort(testing.allocator, 10);
defer testing.allocator.free(s2);
try testing.expectEqualStrings("Fren", s2);
const s3 = try r.readAllocShort(testing.allocator, 10);
defer testing.allocator.free(s3);
try testing.expectEqual(0, s3.len);
}
test readVec {
var r: Reader = .fixed(std.ascii.letters);
var flat_buffer: [52]u8 = undefined;
var bufs: [2][]u8 = .{
flat_buffer[0..26],
flat_buffer[26..],
};
// 此函数可能发生短读,但 fixed 不会。
try testing.expectEqual(26 * 2, try r.readVec(&bufs));
try testing.expectEqualStrings(std.ascii.letters[0..26], bufs[0]);
try testing.expectEqualStrings(std.ascii.letters[26..], bufs[1]);
}
test "expected error.EndOfStream" {
// 单元测试受 https://github.com/ziglang/zig/issues/17733 启发
var buffer: [3]u8 = undefined;
var r: std.Io.Reader = .fixed(&buffer);
r.end = 0; // 容量为 3,但为空
try std.testing.expectError(error.EndOfStream, r.takeEnum(enum(u8) { a, b }, .little));
try std.testing.expectError(error.EndOfStream, r.take(3));
}
test "readVec at end" {
var reader_buffer: [8]u8 = "abcd1234".*;
var reader: testing.Reader = .init(&reader_buffer, &.{});
reader.interface.end = reader_buffer.len;
var out: [16]u8 = undefined;
var vecs: [1][]u8 = .{&out};
try testing.expectEqual(8, try reader.interface.readVec(&vecs));
try testing.expectEqualStrings("abcd1234", vecs[0][0..8]);
}
fn endingStream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize {
_ = r;
_ = w;
_ = limit;
return error.EndOfStream;
}
fn endingReadVec(r: *Reader, data: [][]u8) Error!usize {
_ = r;
_ = data;
return error.EndOfStream;
}
fn endingDiscard(r: *Reader, limit: Limit) Error!usize {
_ = r;
_ = limit;
return error.EndOfStream;
}
fn endingRebase(r: *Reader, capacity: usize) RebaseError!void {
_ = r;
_ = capacity;
return error.EndOfStream;
}
fn failingStream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize {
_ = r;
_ = w;
_ = limit;
return error.ReadFailed;
}
fn failingDiscard(r: *Reader, limit: Limit) Error!usize {
_ = r;
_ = limit;
return error.ReadFailed;
}
test "discardAll that has to call discard multiple times on an indirect reader" {
var fr: Reader = .fixed("ABCDEFGHIJKLMNOPQRSTUVWXYZ");
var indirect_buffer: [3]u8 = undefined;
var tri: std.testing.ReaderIndirect = .init(&fr, &indirect_buffer);
const r = &tri.interface;
try r.discardAll(10);
var remaining_buf: [16]u8 = undefined;
try r.readSliceAll(&remaining_buf);
try std.testing.expectEqualStrings(fr.buffer[10..], remaining_buf[0..]);
}
test "readAlloc when the backing reader provides one byte at a time" {
const str = "This is a test";
var tiny_buffer: [1]u8 = undefined;
var one_byte_stream: testing.Reader = .init(&tiny_buffer, &.{
.{ .buffer = str },
});
one_byte_stream.artificial_limit = .limited(1);
const res = try one_byte_stream.interface.allocRemaining(std.testing.allocator, .unlimited);
defer std.testing.allocator.free(res);
try std.testing.expectEqualStrings(str, res);
}
test "takeDelimiterInclusive when it rebases" {
const written_line = "ABCDEFGHIJKLMNOPQRSTUVWXYZ\n";
var buffer: [128]u8 = undefined;
var tr: std.testing.Reader = .init(&buffer, &.{
.{ .buffer = written_line },
.{ .buffer = written_line },
.{ .buffer = written_line },
.{ .buffer = written_line },
.{ .buffer = written_line },
.{ .buffer = written_line },
});
const r = &tr.interface;
for (0..6) |_| {
try std.testing.expectEqualStrings(written_line, try r.takeDelimiterInclusive('\n'));
}
}
test "takeDelimiterInclusive on an indirect reader when it rebases" {
const written_line = "ABCDEFGHIJKLMNOPQRSTUVWXYZ\n";
var buffer: [128]u8 = undefined;
var tr: std.testing.Reader = .init(&buffer, &.{
.{ .buffer = written_line[0..4] },
.{ .buffer = written_line[4..] },
.{ .buffer = written_line },
.{ .buffer = written_line },
.{ .buffer = written_line },
.{ .buffer = written_line },
.{ .buffer = written_line },
});
var indirect_buffer: [128]u8 = undefined;
var tri: std.testing.ReaderIndirect = .init(&tr.interface, &indirect_buffer);
const r = &tri.interface;
for (0..6) |_| {
try std.testing.expectEqualStrings(written_line, try r.takeDelimiterInclusive('\n'));
}
}
test "takeStruct and peekStruct packed" {
var r: Reader = .fixed(&.{ 0b11110000, 0b00110011 });
const S = packed struct(u16) { a: u2, b: u6, c: u7, d: u1 };
try testing.expectEqual(@as(S, .{
.a = 0b11,
.b = 0b001100,
.c = 0b1110000,
.d = 0b1,
}), try r.peekStruct(S, .big));
try testing.expectEqual(@as(S, .{
.a = 0b11,
.b = 0b001100,
.c = 0b1110000,
.d = 0b1,
}), try r.takeStruct(S, .big));
try testing.expectError(error.EndOfStream, r.takeStruct(S, .little));
}
test allocRemaining {
{
var r: Reader = .fixed("abc");
const str = try r.allocRemaining(testing.allocator, .unlimited);
defer testing.allocator.free(str);
try testing.expectEqualStrings("abc", str);
}
{
var r: Reader = .fixed("abc");
const str = try r.allocRemaining(testing.allocator, .limited(5));
defer testing.allocator.free(str);
try testing.expectEqualStrings("abc", str);
}
{
var r: Reader = .fixed("abc");
const str = try r.allocRemaining(testing.allocator, .limited(3));
defer testing.allocator.free(str);
try testing.expectEqualStrings("abc", str);
}
{
var r: Reader = .fixed("abcd");
try testing.expectError(error.StreamTooLong, r.allocRemaining(testing.allocator, .limited(3)));
}
}
/// 提供 `Reader` 实现,将底层读取器
/// 提供的数据传给 `Hasher.update`。
///
/// 底层读取器最好不设缓冲。
///
/// 由于实现需要通用性,其缓冲策略
/// 并非最优。更好的方案是为每个哈希函数
/// 创建读取器,使丢弃缓冲区能够针对哈希
/// 实现细节定制。
pub fn Hashed(comptime Hasher: type) type {
return struct {
in: *Reader,
hasher: Hasher,
reader: Reader,
pub fn init(in: *Reader, hasher: Hasher, buffer: []u8) @This() {
return .{
.in = in,
.hasher = hasher,
.reader = .{
.vtable = &.{
.stream = @This().stream,
.readVec = @This().readVec,
.discard = @This().discard,
},
.buffer = buffer,
.end = 0,
.seek = 0,
},
};
}
fn stream(r: *Reader, w: *Writer, limit: Limit) StreamError!usize {
const this: *@This() = @alignCast(@fieldParentPtr("reader", r));
const data = limit.slice(try w.writableSliceGreedy(1));
var vec: [1][]u8 = .{data};
const n = try this.in.readVec(&vec);
this.hasher.update(data[0..n]);
w.advance(n);
return n;
}
fn readVec(r: *Reader, data: [][]u8) Error!usize {
const this: *@This() = @alignCast(@fieldParentPtr("reader", r));
var vecs: [8][]u8 = undefined; // 任意选择的数量。
const dest_n, const data_size = try r.writableVector(&vecs, data);
const dest = vecs[0..dest_n];
const n = try this.in.readVec(dest);
var remaining: usize = n;
for (dest) |slice| {
if (remaining < slice.len) {
this.hasher.update(slice[0..remaining]);
remaining = 0;
break;
} else {
remaining -= slice.len;
this.hasher.update(slice);
}
}
assert(remaining == 0);
if (n > data_size) {
r.end += n - data_size;
return data_size;
}
return n;
}
fn discard(r: *Reader, limit: Limit) Error!usize {
const this: *@This() = @alignCast(@fieldParentPtr("reader", r));
const peeked = limit.slice(try this.in.peekGreedy(1));
this.hasher.update(peeked);
this.in.toss(peeked.len);
return peeked.len;
}
};
}
pub fn writableVectorPosix(r: *Reader, buffer: []std.posix.iovec, data: []const []u8) Error!struct { usize, usize } {
var i: usize = 0;
var n: usize = 0;
if (r.seek == r.end) {
for (data) |buf| {
if (buffer.len - i == 0) return .{ i, n };
if (buf.len != 0) {
buffer[i] = .{ .base = buf.ptr, .len = buf.len };
i += 1;
n += buf.len;
}
}
const buf = r.buffer;
if (buf.len != 0) {
r.seek = 0;
r.end = 0;
buffer[i] = .{ .base = buf.ptr, .len = buf.len };
i += 1;
}
} else {
const buf = r.buffer[r.end..];
buffer[i] = .{ .base = buf.ptr, .len = buf.len };
i += 1;
}
return .{ i, n };
}
pub fn writableVectorWsa(
r: *Reader,
buffer: []std.os.windows.AFD.WSABUF(.@"var"),
data: []const []u8,
) Error!struct { usize, usize } {
var i: usize = 0;
var n: usize = 0;
if (r.seek == r.end) {
for (data) |buf| {
if (buffer.len - i == 0) return .{ i, n };
if (buf.len == 0) continue;
if (std.math.cast(u32, buf.len)) |len| {
buffer[i] = .{ .buf = buf.ptr, .len = len };
i += 1;
n += len;
continue;
}
buffer[i] = .{ .buf = buf.ptr, .len = std.math.maxInt(u32) };
i += 1;
n += std.math.maxInt(u32);
return .{ i, n };
}
const buf = r.buffer;
if (buf.len != 0) {
r.seek = 0;
r.end = 0;
if (std.math.cast(u32, buf.len)) |len| {
buffer[i] = .{ .buf = buf.ptr, .len = len };
} else {
buffer[i] = .{ .buf = buf.ptr, .len = std.math.maxInt(u32) };
}
i += 1;
}
} else {
buffer[i] = .{
.buf = r.buffer.ptr + r.end,
.len = @min(std.math.maxInt(u32), r.buffer.len - r.end),
};
i += 1;
}
return .{ i, n };
}
pub fn writableVector(r: *Reader, buffer: [][]u8, data: []const []u8) Error!struct { usize, usize } {
var i: usize = 0;
var n: usize = 0;
if (r.seek == r.end) {
for (data) |buf| {
if (buffer.len - i == 0) return .{ i, n };
if (buf.len != 0) {
buffer[i] = buf;
i += 1;
n += buf.len;
}
}
if (r.buffer.len != 0) {
r.seek = 0;
r.end = 0;
buffer[i] = r.buffer;
i += 1;
}
} else {
buffer[i] = r.buffer[r.end..];
i += 1;
}
return .{ i, n };
}
test "deserialize signed LEB128" {
// 较小的值
try testing.expectEqual(5, testLeb128(i7, "\x05"));
try testing.expectEqual(53, testLeb128(i64, "\x35"));
try testing.expectEqual(-6, testLeb128(i7, "\x7A"));
try testing.expectEqual(-23, testLeb128(i64, "\x69"));
// 随机值
try testing.expectEqual(90, testLeb128(i8, "\xDA\x00"));
try testing.expectEqual(3434, testLeb128(i16, "\xEA\x1A"));
try testing.expectEqual(1505683543, testLeb128(i32, "\xD7\xD0\xFB\xCD\x05"));
try testing.expectEqual(105721575804011595, testLeb128(i64, "\xCB\x88\x92\xD7\xE8\xA6\xE6\xBB\x01"));
try testing.expectEqual(51316697993548595875823294343650416388, testLeb128(i128, "\x84\xAE\xAC\xFC\xE4\xA0\xCD\xE2\x87\xED\x83\xB2\x87\xAA\xA3\x9E\x9B\xCD\x00"));
try testing.expectEqual(-68, testLeb128(i8, "\xBC\x7F"));
try testing.expectEqual(-20174, testLeb128(i16, "\xB2\xE2\x7E"));
try testing.expectEqual(-166511141, testLeb128(i32, "\xDB\xFB\xCC\xB0\x7F"));
try testing.expectEqual(-4368809844285451825, testLeb128(i64, "\xCF\xA3\x8B\xA1\xFF\xD2\xB7\xAF\x43"));
try testing.expectEqual(-43250117698642799010758201165100952046, testLeb128(i128, "\x92\xAC\xDB\xA4\xEC\xDE\xB9\x95\xD1\xBA\xEC\xB0\xD7\x80\xA4\xAA\xF6\xBE\x7F"));
// {min,max} 值
try testing.expectEqual(std.math.maxInt(i8), testLeb128(i8, "\xFF\x00"));
try testing.expectEqual(std.math.maxInt(i16), testLeb128(i16, "\xFF\xFF\x01"));
try testing.expectEqual(std.math.maxInt(i32), testLeb128(i32, "\xFF\xFF\xFF\xFF\x07"));
try testing.expectEqual(std.math.maxInt(i64), testLeb128(i64, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x00"));
try testing.expectEqual(std.math.maxInt(i128), testLeb128(i128, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x01"));
try testing.expectEqual(std.math.minInt(i8), testLeb128(i8, "\x80\x7F"));
try testing.expectEqual(std.math.minInt(i16), testLeb128(i16, "\x80\x80\x7E"));
try testing.expectEqual(std.math.minInt(i32), testLeb128(i32, "\x80\x80\x80\x80\x78"));
try testing.expectEqual(std.math.minInt(i64), testLeb128(i64, "\x80\x80\x80\x80\x80\x80\x80\x80\x80\x7F"));
try testing.expectEqual(std.math.minInt(i128), testLeb128(i128, "\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x80\x7E"));
// 特定情况
try testing.expectEqual(0, testLeb128(i2, "\x00"));
try testing.expectEqual(0, testLeb128(i8, "\x00"));
try testing.expectEqual(1, testLeb128(i2, "\x01"));
try testing.expectEqual(1, testLeb128(i8, "\x01"));
try testing.expectEqual(-1, testLeb128(i2, "\x7F"));
try testing.expectEqual(-1, testLeb128(i8, "\x7F"));
const end_of_stream: [20]u8 = @splat(0x80);
const overflow: [21]u8 = end_of_stream ++ .{0x01};
const long_zero: [21]u8 = end_of_stream ++ .{0x00};
const long_one: [22]u8 = .{0x81} ++ end_of_stream ++ .{0x00};
const long_minus_one: [20]u8 = @as([19]u8, @splat(0xFF)) ++ .{0x7F};
// 已截断
try testing.expectError(error.EndOfStream, testLeb128(i16, "\x80\x80\x84\x80"));
try testing.expectError(error.EndOfStream, testLeb128(i16, "\x80\x80\x80\x84\x80"));
try testing.expectError(error.EndOfStream, testLeb128(i32, "\x80\x80\x80\x80\x90"));
try testing.expectError(error.EndOfStream, testLeb128(i7, ""));
try testing.expectError(error.EndOfStream, testLeb128(i8, ""));
try testing.expectError(error.EndOfStream, testLeb128(i14, ""));
try testing.expectError(error.EndOfStream, testLeb128(i128, ""));
try testing.expectError(error.EndOfStream, testLeb128(i7, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(i8, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(i14, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(i128, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(i7, &end_of_stream));
try testing.expectError(error.EndOfStream, testLeb128(i8, &end_of_stream));
try testing.expectError(error.EndOfStream, testLeb128(i14, &end_of_stream));
try testing.expectError(error.EndOfStream, testLeb128(i128, &end_of_stream));
// 溢出
try testing.expectError(error.Overflow, testLeb128(i8, "\x80\x01"));
try testing.expectError(error.Overflow, testLeb128(i8, "\xFF\x7E"));
try testing.expectError(error.Overflow, testLeb128(i8, "\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(i16, "\x80\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(i32, "\x80\x80\x80\x80\x08"));
try testing.expectError(error.Overflow, testLeb128(i32, "\x80\x80\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(i64, "\x80\x80\x80\x80\x80\x80\x80\x80\x80\x01"));
try testing.expectError(error.Overflow, testLeb128(i64, "\x80\x80\x80\x80\x80\x80\x80\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(i7, &overflow));
try testing.expectError(error.Overflow, testLeb128(i8, &overflow));
try testing.expectError(error.Overflow, testLeb128(i14, &overflow));
try testing.expectError(error.Overflow, testLeb128(i128, &overflow));
// 额外填充
try testing.expectEqual(-1, testLeb128(i32, "\xFF\xFF\xFF\xFF\x7F"));
try testing.expectEqual(-1, testLeb128(i64, "\xFF\x7F"));
try testing.expectEqual(0x7F, testLeb128(i64, "\xFF\x00"));
try testing.expectEqual(0x7F, testLeb128(i64, "\xFF\x80\x00"));
try testing.expectEqual(0x80, testLeb128(i64, "\x80\x81\x00"));
try testing.expectEqual(0x80, testLeb128(i64, "\x80\x81\x80\x00"));
try testing.expectEqual(0, testLeb128(i7, &long_zero));
try testing.expectEqual(0, testLeb128(i8, &long_zero));
try testing.expectEqual(0, testLeb128(i14, &long_zero));
try testing.expectEqual(0, testLeb128(i128, &long_zero));
try testing.expectEqual(1, testLeb128(i2, &long_one));
try testing.expectEqual(1, testLeb128(i7, &long_one));
try testing.expectEqual(1, testLeb128(i8, &long_one));
try testing.expectEqual(1, testLeb128(i14, &long_one));
try testing.expectEqual(1, testLeb128(i128, &long_one));
try testing.expectEqual(-1, testLeb128(i2, &long_minus_one));
try testing.expectEqual(-1, testLeb128(i7, &long_minus_one));
try testing.expectEqual(-1, testLeb128(i8, &long_minus_one));
try testing.expectEqual(-1, testLeb128(i14, &long_minus_one));
try testing.expectEqual(-1, testLeb128(i128, &long_minus_one));
// 解码字节边界
try testing.expectEqual(std.math.maxInt(i7), testLeb128(i7, "\x3F"));
try testing.expectEqual(std.math.maxInt(i7) + 1, testLeb128(i8, "\xC0\x00"));
try testing.expectEqual(std.math.maxInt(i14), testLeb128(i14, "\xFF\x3F"));
try testing.expectEqual(std.math.maxInt(i14) + 1, testLeb128(i15, "\x80\xC0\x00"));
try testing.expectEqual(std.math.maxInt(i49), testLeb128(i49, "\xFF\xFF\xFF\xFF\xFF\xFF\x3F"));
try testing.expectEqual(std.math.maxInt(i49) + 1, testLeb128(i50, "\x80\x80\x80\x80\x80\x80\xC0\x00"));
try testing.expectEqual(std.math.maxInt(i56), testLeb128(i56, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x3F"));
try testing.expectEqual(std.math.maxInt(i56) + 1, testLeb128(i57, "\x80\x80\x80\x80\x80\x80\x80\xC0\x00"));
try testing.expectEqual(std.math.maxInt(i63), testLeb128(i63, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x3F"));
try testing.expectEqual(std.math.maxInt(i63) + 1, testLeb128(i64, "\x80\x80\x80\x80\x80\x80\x80\x80\xC0\x00"));
try testing.expectEqual(std.math.minInt(i7), testLeb128(i7, "\x40"));
try testing.expectEqual(std.math.minInt(i7) - 1, testLeb128(i8, "\xBF\x7F"));
try testing.expectEqual(std.math.minInt(i14), testLeb128(i14, "\x80\x40"));
try testing.expectEqual(std.math.minInt(i14) - 1, testLeb128(i15, "\xFF\xBF\x7F"));
try testing.expectEqual(std.math.minInt(i49), testLeb128(i49, "\x80\x80\x80\x80\x80\x80\x40"));
try testing.expectEqual(std.math.minInt(i49) - 1, testLeb128(i50, "\xFF\xFF\xFF\xFF\xFF\xFF\xBF\x7F"));
try testing.expectEqual(std.math.minInt(i56), testLeb128(i56, "\x80\x80\x80\x80\x80\x80\x80\x40"));
try testing.expectEqual(std.math.minInt(i56) - 1, testLeb128(i57, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xBF\x7F"));
try testing.expectEqual(std.math.minInt(i63), testLeb128(i63, "\x80\x80\x80\x80\x80\x80\x80\x80\x40"));
try testing.expectEqual(std.math.minInt(i63) - 1, testLeb128(i64, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xBF\x7F"));
}
test "deserialize unsigned LEB128" {
// 较小的值
try testing.expectEqual(46, testLeb128(u7, "\x2E"));
try testing.expectEqual(117, testLeb128(u64, "\x75"));
// 随机值
try testing.expectEqual(224, testLeb128(u8, "\xE0\x01"));
try testing.expectEqual(53023, testLeb128(u16, "\x9F\x9E\x03"));
try testing.expectEqual(2609971022, testLeb128(u32, "\xCE\xFE\xC3\xDC\x09"));
try testing.expectEqual(10223253173206528843, testLeb128(u64, "\xCB\xE6\xF0\xEE\x88\xD3\x92\xF0\x8D\x01"));
try testing.expectEqual(67831258924174241363439488509570048548, testLeb128(u128, "\xA4\xC4\xD7\xE9\x8C\xD2\x86\x80\xBC\xAC\xE5\xAB\xB4\xA2\xD1\xE9\x87\x66"));
// 最大值
try testing.expectEqual(std.math.maxInt(u8), testLeb128(u8, "\xFF\x01"));
try testing.expectEqual(std.math.maxInt(u16), testLeb128(u16, "\xFF\xFF\x03"));
try testing.expectEqual(std.math.maxInt(u32), testLeb128(u32, "\xFF\xFF\xFF\xFF\x0F"));
try testing.expectEqual(std.math.maxInt(u64), testLeb128(u64, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x01"));
try testing.expectEqual(std.math.maxInt(u128), testLeb128(u128, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x03"));
// 特定情况
try testing.expectEqual(0, testLeb128(u0, "\x00"));
try testing.expectEqual(0, testLeb128(u1, "\x00"));
try testing.expectEqual(0, testLeb128(u8, "\x00"));
try testing.expectEqual(1, testLeb128(u1, "\x01"));
try testing.expectEqual(1, testLeb128(u8, "\x01"));
const end_of_stream: [20]u8 = @splat(0x80);
const overflow: [21]u8 = end_of_stream ++ .{0x01};
const long_zero: [21]u8 = end_of_stream ++ .{0x00};
const long_one: [22]u8 = .{0x81} ++ end_of_stream ++ .{0x00};
// 已截断
try testing.expectError(error.EndOfStream, testLeb128(u16, "\x80\x80\x84\x80"));
try testing.expectError(error.EndOfStream, testLeb128(u16, "\x80\x80\x80\x84\x80"));
try testing.expectError(error.EndOfStream, testLeb128(u32, "\x80\x80\x80\x80\x90"));
try testing.expectError(error.EndOfStream, testLeb128(u7, ""));
try testing.expectError(error.EndOfStream, testLeb128(u8, ""));
try testing.expectError(error.EndOfStream, testLeb128(u14, ""));
try testing.expectError(error.EndOfStream, testLeb128(u128, ""));
try testing.expectError(error.EndOfStream, testLeb128(u7, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(u8, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(u14, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(u128, "\x80"));
try testing.expectError(error.EndOfStream, testLeb128(u7, &end_of_stream));
try testing.expectError(error.EndOfStream, testLeb128(u8, &end_of_stream));
try testing.expectError(error.EndOfStream, testLeb128(u14, &end_of_stream));
try testing.expectError(error.EndOfStream, testLeb128(u128, &end_of_stream));
// 溢出
try testing.expectError(error.Overflow, testLeb128(u0, "\x01"));
try testing.expectError(error.Overflow, testLeb128(u1, "\x02"));
try testing.expectError(error.Overflow, testLeb128(u8, "\x80\x02"));
try testing.expectError(error.Overflow, testLeb128(u8, "\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(u16, "\x80\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(u32, "\x80\x80\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(u64, "\x80\x80\x80\x80\x80\x80\x80\x80\x80\x40"));
try testing.expectError(error.Overflow, testLeb128(u7, &overflow));
try testing.expectError(error.Overflow, testLeb128(u8, &overflow));
try testing.expectError(error.Overflow, testLeb128(u14, &overflow));
try testing.expectError(error.Overflow, testLeb128(u128, &overflow));
// 额外填充
try testing.expectEqual(0x7F, testLeb128(u64, "\xFF\x00"));
try testing.expectEqual(0x7F, testLeb128(u64, "\xFF\x80\x00"));
try testing.expectEqual(0x80, testLeb128(u64, "\x80\x81\x00"));
try testing.expectEqual(0x80, testLeb128(u64, "\x80\x81\x80\x80\x00"));
try testing.expectEqual(0, testLeb128(u0, &long_zero));
try testing.expectEqual(0, testLeb128(u7, &long_zero));
try testing.expectEqual(0, testLeb128(u8, &long_zero));
try testing.expectEqual(0, testLeb128(u14, &long_zero));
try testing.expectEqual(0, testLeb128(u128, &long_zero));
try testing.expectEqual(1, testLeb128(u1, &long_one));
try testing.expectEqual(1, testLeb128(u7, &long_one));
try testing.expectEqual(1, testLeb128(u8, &long_one));
try testing.expectEqual(1, testLeb128(u14, &long_one));
try testing.expectEqual(1, testLeb128(u128, &long_one));
// 解码字节边界
try testing.expectEqual(std.math.maxInt(u7), testLeb128(u7, "\x7F"));
try testing.expectEqual(std.math.maxInt(u7) + 1, testLeb128(u8, "\x80\x01"));
try testing.expectEqual(std.math.maxInt(u14), testLeb128(u14, "\xFF\x7F"));
try testing.expectEqual(std.math.maxInt(u14) + 1, testLeb128(u15, "\x80\x80\x01"));
try testing.expectEqual(std.math.maxInt(u49), testLeb128(u49, "\xFF\xFF\xFF\xFF\xFF\xFF\x7F"));
try testing.expectEqual(std.math.maxInt(u49) + 1, testLeb128(u50, "\x80\x80\x80\x80\x80\x80\x80\x01"));
try testing.expectEqual(std.math.maxInt(u56), testLeb128(u56, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x7F"));
try testing.expectEqual(std.math.maxInt(u56) + 1, testLeb128(u57, "\x80\x80\x80\x80\x80\x80\x80\x80\x01"));
try testing.expectEqual(std.math.maxInt(u63), testLeb128(u63, "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\x7F"));
try testing.expectEqual(std.math.maxInt(u63) + 1, testLeb128(u64, "\x80\x80\x80\x80\x80\x80\x80\x80\x80\x01"));
}
fn testLeb128(comptime T: type, encoded: []const u8) !T {
var reader: std.Io.Reader = .fixed(encoded);
const result = reader.takeLeb128(T);
try testing.expectEqual(reader.seek, reader.end);
return result;
}
test streamExactPreserve {
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 5, .stream_len = 5 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 9, .preserve = 5, .stream_len = 2 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 5, .stream_len = 6 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 6 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 5, .stream_len = 10 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 10 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 11 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 80 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 6, .stream_len = 85 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 6 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 11 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 80 });
try testStreamExactPreserve(.{ .buf_len = 10, .fill_len = 5, .preserve = 10, .stream_len = 85 });
}
fn testStreamExactPreserve(options: struct { buf_len: u4, fill_len: u4, preserve: u4, stream_len: u8 }) !void {
assert(options.fill_len <= options.buf_len);
assert(options.preserve <= options.buf_len);
var input: [256]u8 = undefined;
for (&input, 0..) |*val, i| {
val.* = @as(u8, @intCast(i % 26)) + 'a';
}
const expected_out = input[0 .. options.fill_len + options.stream_len];
const expected_preserved = expected_out[expected_out.len -| options.preserve..];
var r: Reader = .fixed(&input);
var out_buf: [256]u8 = undefined;
var fw: Writer = .fixed(&out_buf);
var indirect_buffer: [16]u8 = undefined;
var twi: std.testing.WriterIndirect = .init(&fw, indirect_buffer[0..options.buf_len]);
const w = &twi.interface;
try r.streamExact(w, options.fill_len);
try r.streamExactPreserve(w, options.preserve, options.stream_len);
try std.testing.expectEqualStrings(expected_preserved, w.buffer[w.end -| options.preserve..w.end]);
try w.flush();
try std.testing.expectEqualStrings(expected_out, fw.buffered());
}
test {
_ = Limited;
}