authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-03-09 21:24:59-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-03-09 21:24:59-07:00
log5318045b88f05c8c3505287114e1caec562de763
tree95226476c5f4110f4005f96314584d8a055eed47
parent3b515fbede945a2927d5aba59212553a8b26b944

std.Io.Writer: document write and writeAll

closes #31435

1 files changed, 18 insertions(+), 2 deletions(-)

lib/std/Io/Writer.zig+18-2
...@@ -518,6 +518,17 @@ test "writeSplatAll works with a single buffer" {...@@ -518,6 +518,17 @@ test "writeSplatAll works with a single buffer" {
518 try testing.expectEqualStrings("hellohellohello", aw.writer.buffered());518 try testing.expectEqualStrings("hellohellohello", aw.writer.buffered());
519}519}
520520
521/// Transfers `bytes` to the stream, calling `drain` at most once.
522///
523/// Returns the number of bytes transferred, which may be less than
524/// `bytes.len`, including zero.
525///
526/// A return value less than `bytes.len` does not indicate failure; a
527/// subsequent call may return nonzero, or fail with `error.WriteFailed`.
528///
529/// See also:
530/// * `writeAll`
531/// * `writeVec`
521pub fn write(w: *Writer, bytes: []const u8) Error!usize {532pub fn write(w: *Writer, bytes: []const u8) Error!usize {
522 if (w.end + bytes.len <= w.buffer.len) {533 if (w.end + bytes.len <= w.buffer.len) {
523 @branchHint(.likely);534 @branchHint(.likely);
...@@ -528,8 +539,13 @@ pub fn write(w: *Writer, bytes: []const u8) Error!usize {...@@ -528,8 +539,13 @@ pub fn write(w: *Writer, bytes: []const u8) Error!usize {
528 return w.vtable.drain(w, &.{bytes}, 1);539 return w.vtable.drain(w, &.{bytes}, 1);
529}540}
530541
531/// Calls `drain` as many times as necessary such that all of `bytes` are542/// Transfers `bytes` to the stream, calling `drain` as many times as necessary
532/// transferred.543/// such that all `bytes` are transferred.
544///
545/// See also:
546/// * `print`
547/// * `writeVecAll`
548/// * `write`
533pub fn writeAll(w: *Writer, bytes: []const u8) Error!void {549pub fn writeAll(w: *Writer, bytes: []const u8) Error!void {
534 var index: usize = 0;550 var index: usize = 0;
535 while (index < bytes.len) index += try w.write(bytes[index..]);551 while (index < bytes.len) index += try w.write(bytes[index..]);