authorgravatar for squeek502@hotmail.comRyan Liptak <squeek502@hotmail.com> 2026-05-26 18:57:29-07:00
committergravatar for squeek502@hotmail.comRyan Liptak <squeek502@hotmail.com> 2026-05-29 21:23:13+02:00
logb3c6a3b047cb248afb0d61ae723ae41aeab9289b
treef8a475696d3119271b8f341b526bb08395afb48f
parent18b3c78a9e2f2b89efcca63501fffb9edf67e88c

Writer/Reader: Clarify preserve functionality in doc comments

Addresses part of https://github.com/ziglang/zig/issues/24767

2 files changed, 33 insertions(+), 7 deletions(-)

lib/std/Io/Reader.zig+10-4
......@@ -226,10 +226,16 @@ pub fn streamExact64(r: *Reader, w: *Writer, n: u64) StreamError!void {
226226
227227/// "Pump" exactly `n` bytes from the reader to the writer.
228228///
229/// When draining `w`, ensures that at least `preserve_len` bytes remain
230/// buffered.
231///
232/// Asserts `Writer.buffer` capacity exceeds `preserve_len`.
229/// On success, at least `preserve_len` bytes will remain buffered if there are
230/// enough buffered bytes to do so.
231/// The amount buffered by the writer after the call will only be less than
232/// `preserve_len` if `w.end + n` is less than `preserve_len` before the call.
233/// The intentionally preserved bytes will include up to `preserve_len -| n` bytes from
234/// the previously buffered bytes, plus `@min(n, preserve_len)` of the newly
235/// "pumped" bytes.
236///
237/// Asserts `Writer.buffer` capacity is at least `preserve_len`.
238/// `n` can be greater than the `Writer.buffer` capacity.
233239pub fn streamExactPreserve(r: *Reader, w: *Writer, preserve_len: usize, n: usize) StreamError!void {
234240 if (w.end + n <= w.buffer.len) {
235241 @branchHint(.likely);
lib/std/Io/Writer.zig+23-3
......@@ -417,7 +417,8 @@ pub fn writableSliceGreedyPreserve(w: *Writer, preserve: usize, minimum_len: usi
417417 return w.buffer[w.end..];
418418}
419419
420/// Asserts the provided buffer has total capacity enough for `len`.
420/// Asserts the provided buffer has total capacity enough for `len`
421/// and `preserve` combined.
421422///
422423/// Advances the buffer end position by `len`.
423424///
......@@ -755,8 +756,14 @@ pub fn writeByte(w: *Writer, byte: u8) Error!void {
755756 }
756757}
757758
758/// When draining the buffer, ensures that at least `preserve` bytes
759/// remain buffered.
759/// On success, at least `preserve` bytes will remain buffered if there are
760/// enough buffered bytes to do so.
761/// The amount buffered by the writer after the call will only be less than
762/// `preserve` if `w.end + 1` is less than `preserve` before the call.
763/// The intentionally preserved bytes will include up to `preserve -| 1` bytes from
764/// the previously buffered bytes, plus the newly written byte.
765///
766/// Asserts buffer capacity is at least `preserve`.
760767pub fn writeBytePreserve(w: *Writer, preserve: usize, byte: u8) Error!void {
761768 if (w.buffer.len - w.end != 0) {
762769 @branchHint(.likely);
......@@ -784,6 +791,19 @@ test splatByteAll {
784791 try testing.expectEqualStrings(&@as([45]u8, @splat('7')), aw.writer.buffered());
785792}
786793
794/// Writes the same byte many times, performing the underlying write call as
795/// many times as necessary.
796///
797/// On success, at least `preserve` bytes will remain buffered if there are
798/// enough buffered bytes to do so.
799/// The amount buffered by the writer after the call will only be less than
800/// `preserve` if `w.end + n` is less than `preserve` before the call.
801/// The intentionally preserved bytes will include up to `preserve -| n` bytes from
802/// the previously buffered bytes, plus `@min(n, preserve_len)` of the newly
803/// written bytes.
804///
805/// Asserts buffer capacity is at least `preserve`.
806/// `n` can be greater than the buffer capacity.
787807pub fn splatBytePreserve(w: *Writer, preserve: usize, byte: u8, n: usize) Error!void {
788808 const new_end = w.end + n;
789809 if (new_end <= w.buffer.len) {