Commit b3c6a3b047cb248afb0d61ae723ae41aeab9289b | zig

author	Ryan Liptak <squeek502@hotmail.com> 2026-05-26 18:57:29-07:00
committer	Ryan Liptak <squeek502@hotmail.com> 2026-05-29 21:23:13+02:00
log	b3c6a3b047cb248afb0d61ae723ae41aeab9289b
tree	f8a475696d3119271b8f341b526bb08395afb48f
parent	18b3c78a9e2f2b89efcca63501fffb9edf67e88c

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
    Writer.zig

lib/std/Io/Reader.zig+10-4

 @@ -226,10 +226,16 @@ pub fn streamExact64(r: *Reader, w: *Writer, n: u64) StreamError!void {
 /// "Pump" exactly `n` bytes from the reader to the writer.
 ///
-/// When draining `w`, ensures that at least `preserve_len` bytes remain
+/// On success, at least `preserve_len` bytes will remain buffered if there are
-/// buffered.
+/// enough buffered bytes to do so.
-///
+/// The amount buffered by the writer after the call will only be less than
-/// Asserts `Writer.buffer` capacity exceeds `preserve_len`.
+/// `preserve_len` if `w.end + n` is less than `preserve_len` before the call.
+/// The intentionally preserved bytes will include up to `preserve_len -| n` bytes from
+/// the previously buffered bytes, plus `@min(n, preserve_len)` of the newly
+/// "pumped" bytes.
+///
+/// Asserts `Writer.buffer` capacity is at least `preserve_len`.
+/// `n` can be greater than the `Writer.buffer` capacity.
 pub fn streamExactPreserve(r: *Reader, w: *Writer, preserve_len: usize, n: usize) StreamError!void {
     if (w.end + n <= w.buffer.len) {
         @branchHint(.likely);

lib/std/Io/Writer.zig+23-3

...	@@ -417,7 +417,8 @@ pub fn writableSliceGreedyPreserve(w: *Writer, preserve: usize, minimum_len: usi	...	@@ -417,7 +417,8 @@ pub fn writableSliceGreedyPreserve(w: *Writer, preserve: usize, minimum_len: usi
417	return w.buffer[w.end..];	417	return w.buffer[w.end..];
418	}	418	}
419		419
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.
421	///	422	///
422	/// Advances the buffer end position by `len`.	423	/// Advances the buffer end position by `len`.
423	///	424	///
...	@@ -755,8 +756,14 @@ pub fn writeByte(w: *Writer, byte: u8) Error!void {	...	@@ -755,8 +756,14 @@ pub fn writeByte(w: *Writer, byte: u8) Error!void {
755	}	756	}
756	}	757	}
757		758
758	/// When draining the buffer, ensures that at least `preserve` bytes	759	/// On success, at least `preserve` bytes will remain buffered if there are
759	/// remain buffered.	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`.
760	pub fn writeBytePreserve(w: *Writer, preserve: usize, byte: u8) Error!void {	767	pub fn writeBytePreserve(w: *Writer, preserve: usize, byte: u8) Error!void {
761	if (w.buffer.len - w.end != 0) {	768	if (w.buffer.len - w.end != 0) {
762	@branchHint(.likely);	769	@branchHint(.likely);
...	@@ -784,6 +791,19 @@ test splatByteAll {	...	@@ -784,6 +791,19 @@ test splatByteAll {
784	try testing.expectEqualStrings(&@as([45]u8, @splat('7')), aw.writer.buffered());	791	try testing.expectEqualStrings(&@as([45]u8, @splat('7')), aw.writer.buffered());
785	}	792	}
786		793
		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.
787	pub fn splatBytePreserve(w: *Writer, preserve: usize, byte: u8, n: usize) Error!void {	807	pub fn splatBytePreserve(w: *Writer, preserve: usize, byte: u8, n: usize) Error!void {
788	const new_end = w.end + n;	808	const new_end = w.end + n;
789	if (new_end <= w.buffer.len) {	809	if (new_end <= w.buffer.len) {