authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-07-15 10:03:07-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-07-15 10:04:45-07:00
logf521aa0520ac1b881ddbc533b03b4745f7f49820
tree7ef8bd689e21285beffebecb99baec86ea1bcf0c
parent0cb558ba3abb0ac7b48c1a30c9a13c924f950172

std.io.Reader: add more docs for rebase

closes #24418

1 files changed, 14 insertions(+), 0 deletions(-)

lib/std/Io/Reader.zig+14
...@@ -1303,6 +1303,13 @@ fn takeMultipleOf7Leb128(r: *Reader, comptime Result: type) TakeLeb128Error!Resu...@@ -1303,6 +1303,13 @@ fn takeMultipleOf7Leb128(r: *Reader, comptime Result: type) TakeLeb128Error!Resu
1303}1303}
13041304
1305/// Left-aligns data such that `r.seek` becomes zero.1305/// Left-aligns data such that `r.seek` becomes zero.
1306///
1307/// If `r.seek` is not already zero then `buffer` is mutated, making it illegal
1308/// to call this function with a const-casted `buffer`, such as in the case of
1309/// `fixed`. This issue can be avoided:
1310/// * in implementations, by attempting a read before a rebase, in which
1311/// case the read will return `error.EndOfStream`, preventing the rebase.
1312/// * in usage, by copying into a mutable buffer before initializing `fixed`.
1306pub fn rebase(r: *Reader) void {1313pub fn rebase(r: *Reader) void {
1307 if (r.seek == 0) return;1314 if (r.seek == 0) return;
1308 const data = r.buffer[r.seek..r.end];1315 const data = r.buffer[r.seek..r.end];
...@@ -1315,6 +1322,13 @@ pub fn rebase(r: *Reader) void {...@@ -1315,6 +1322,13 @@ pub fn rebase(r: *Reader) void {
1315/// if necessary.1322/// if necessary.
1316///1323///
1317/// Asserts `capacity` is within the buffer capacity.1324/// Asserts `capacity` is within the buffer capacity.
1325///
1326/// If the rebase occurs then `buffer` is mutated, making it illegal to call
1327/// this function with a const-casted `buffer`, such as in the case of `fixed`.
1328/// This issue can be avoided:
1329/// * in implementations, by attempting a read before a rebase, in which
1330/// case the read will return `error.EndOfStream`, preventing the rebase.
1331/// * in usage, by copying into a mutable buffer before initializing `fixed`.
1318pub fn rebaseCapacity(r: *Reader, capacity: usize) void {1332pub fn rebaseCapacity(r: *Reader, capacity: usize) void {
1319 if (r.end > r.buffer.len - capacity) rebase(r);1333 if (r.end > r.buffer.len - capacity) rebase(r);
1320}1334}