From 5360968e03525be4d312ca61a7ba2dcb7890ec42 Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Thu, 10 Jul 2025 10:28:32 -0700 Subject: [PATCH 1/4] std: rename `io` to `Io` in preparation This commit is non-breaking. std.io is deprecated in favor of std.Io, in preparation for that namespace becoming an interface. --- CMakeLists.txt | 24 ++--- lib/std/{io.zig => Io.zig} | 90 +++++++++---------- lib/std/{io => Io}/DeprecatedReader.zig | 0 lib/std/{io => Io}/DeprecatedWriter.zig | 0 lib/std/{io => Io}/Reader.zig | 0 lib/std/{io => Io}/Reader/Limited.zig | 0 lib/std/{io => Io}/Reader/test.zig | 0 lib/std/{io => Io}/Writer.zig | 0 lib/std/{io => Io}/bit_reader.zig | 0 lib/std/{io => Io}/bit_writer.zig | 0 lib/std/{io => Io}/buffered_atomic_file.zig | 0 lib/std/{io => Io}/buffered_reader.zig | 0 lib/std/{io => Io}/buffered_writer.zig | 0 lib/std/{io => Io}/c_writer.zig | 0 .../{io => Io}/change_detection_stream.zig | 0 lib/std/{io => Io}/counting_reader.zig | 0 lib/std/{io => Io}/counting_writer.zig | 0 lib/std/{io => Io}/find_byte_writer.zig | 0 lib/std/{io => Io}/fixed_buffer_stream.zig | 0 lib/std/{io => Io}/limited_reader.zig | 0 lib/std/{io => Io}/multi_writer.zig | 0 lib/std/{io => Io}/seekable_stream.zig | 0 lib/std/{io => Io}/stream_source.zig | 0 lib/std/{io => Io}/test.zig | 0 lib/std/{io => Io}/tty.zig | 0 lib/std/fs/path.zig | 8 +- lib/std/std.zig | 4 +- 27 files changed, 64 insertions(+), 62 deletions(-) rename lib/std/{io.zig => Io.zig} (92%) rename lib/std/{io => Io}/DeprecatedReader.zig (100%) rename lib/std/{io => Io}/DeprecatedWriter.zig (100%) rename lib/std/{io => Io}/Reader.zig (100%) rename lib/std/{io => Io}/Reader/Limited.zig (100%) rename lib/std/{io => Io}/Reader/test.zig (100%) rename lib/std/{io => Io}/Writer.zig (100%) rename lib/std/{io => Io}/bit_reader.zig (100%) rename lib/std/{io => Io}/bit_writer.zig (100%) rename lib/std/{io => Io}/buffered_atomic_file.zig (100%) rename lib/std/{io => Io}/buffered_reader.zig (100%) rename lib/std/{io => Io}/buffered_writer.zig (100%) rename lib/std/{io => Io}/c_writer.zig (100%) rename lib/std/{io => Io}/change_detection_stream.zig (100%) rename lib/std/{io => Io}/counting_reader.zig (100%) rename lib/std/{io => Io}/counting_writer.zig (100%) rename lib/std/{io => Io}/find_byte_writer.zig (100%) rename lib/std/{io => Io}/fixed_buffer_stream.zig (100%) rename lib/std/{io => Io}/limited_reader.zig (100%) rename lib/std/{io => Io}/multi_writer.zig (100%) rename lib/std/{io => Io}/seekable_stream.zig (100%) rename lib/std/{io => Io}/stream_source.zig (100%) rename lib/std/{io => Io}/test.zig (100%) rename lib/std/{io => Io}/tty.zig (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 57e7cba085..db580b05fa 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -387,6 +387,18 @@ set(ZIG_STAGE2_SOURCES lib/std/Build.zig lib/std/Build/Cache.zig lib/std/Build/Cache/DepTokenizer.zig + lib/std/Io.zig + lib/std/Io/Reader.zig + lib/std/Io/Writer.zig + lib/std/Io/buffered_atomic_file.zig + lib/std/Io/buffered_writer.zig + lib/std/Io/change_detection_stream.zig + lib/std/Io/counting_reader.zig + lib/std/Io/counting_writer.zig + lib/std/Io/find_byte_writer.zig + lib/std/Io/fixed_buffer_stream.zig + lib/std/Io/limited_reader.zig + lib/std/Io/seekable_stream.zig lib/std/Progress.zig lib/std/Random.zig lib/std/Target.zig @@ -449,18 +461,6 @@ set(ZIG_STAGE2_SOURCES lib/std/hash_map.zig lib/std/heap.zig lib/std/heap/arena_allocator.zig - lib/std/io.zig - lib/std/io/Reader.zig - lib/std/io/Writer.zig - lib/std/io/buffered_atomic_file.zig - lib/std/io/buffered_writer.zig - lib/std/io/change_detection_stream.zig - lib/std/io/counting_reader.zig - lib/std/io/counting_writer.zig - lib/std/io/find_byte_writer.zig - lib/std/io/fixed_buffer_stream.zig - lib/std/io/limited_reader.zig - lib/std/io/seekable_stream.zig lib/std/json.zig lib/std/json/stringify.zig lib/std/leb128.zig diff --git a/lib/std/io.zig b/lib/std/Io.zig similarity index 92% rename from lib/std/io.zig rename to lib/std/Io.zig index 5339318cd1..00ff0cea98 100644 --- a/lib/std/io.zig +++ b/lib/std/Io.zig @@ -84,8 +84,8 @@ pub const Limit = enum(usize) { } }; -pub const Reader = @import("io/Reader.zig"); -pub const Writer = @import("io/Writer.zig"); +pub const Reader = @import("Io/Reader.zig"); +pub const Writer = @import("Io/Writer.zig"); /// Deprecated in favor of `Reader`. pub fn GenericReader( @@ -404,53 +404,53 @@ pub fn GenericWriter( } /// Deprecated in favor of `Reader`. -pub const AnyReader = @import("io/DeprecatedReader.zig"); +pub const AnyReader = @import("Io/DeprecatedReader.zig"); /// Deprecated in favor of `Writer`. -pub const AnyWriter = @import("io/DeprecatedWriter.zig"); +pub const AnyWriter = @import("Io/DeprecatedWriter.zig"); -pub const SeekableStream = @import("io/seekable_stream.zig").SeekableStream; +pub const SeekableStream = @import("Io/seekable_stream.zig").SeekableStream; -pub const BufferedWriter = @import("io/buffered_writer.zig").BufferedWriter; -pub const bufferedWriter = @import("io/buffered_writer.zig").bufferedWriter; +pub const BufferedWriter = @import("Io/buffered_writer.zig").BufferedWriter; +pub const bufferedWriter = @import("Io/buffered_writer.zig").bufferedWriter; -pub const BufferedReader = @import("io/buffered_reader.zig").BufferedReader; -pub const bufferedReader = @import("io/buffered_reader.zig").bufferedReader; -pub const bufferedReaderSize = @import("io/buffered_reader.zig").bufferedReaderSize; +pub const BufferedReader = @import("Io/buffered_reader.zig").BufferedReader; +pub const bufferedReader = @import("Io/buffered_reader.zig").bufferedReader; +pub const bufferedReaderSize = @import("Io/buffered_reader.zig").bufferedReaderSize; -pub const FixedBufferStream = @import("io/fixed_buffer_stream.zig").FixedBufferStream; -pub const fixedBufferStream = @import("io/fixed_buffer_stream.zig").fixedBufferStream; +pub const FixedBufferStream = @import("Io/fixed_buffer_stream.zig").FixedBufferStream; +pub const fixedBufferStream = @import("Io/fixed_buffer_stream.zig").fixedBufferStream; -pub const CWriter = @import("io/c_writer.zig").CWriter; -pub const cWriter = @import("io/c_writer.zig").cWriter; +pub const CWriter = @import("Io/c_writer.zig").CWriter; +pub const cWriter = @import("Io/c_writer.zig").cWriter; -pub const LimitedReader = @import("io/limited_reader.zig").LimitedReader; -pub const limitedReader = @import("io/limited_reader.zig").limitedReader; +pub const LimitedReader = @import("Io/limited_reader.zig").LimitedReader; +pub const limitedReader = @import("Io/limited_reader.zig").limitedReader; -pub const CountingWriter = @import("io/counting_writer.zig").CountingWriter; -pub const countingWriter = @import("io/counting_writer.zig").countingWriter; -pub const CountingReader = @import("io/counting_reader.zig").CountingReader; -pub const countingReader = @import("io/counting_reader.zig").countingReader; +pub const CountingWriter = @import("Io/counting_writer.zig").CountingWriter; +pub const countingWriter = @import("Io/counting_writer.zig").countingWriter; +pub const CountingReader = @import("Io/counting_reader.zig").CountingReader; +pub const countingReader = @import("Io/counting_reader.zig").countingReader; -pub const MultiWriter = @import("io/multi_writer.zig").MultiWriter; -pub const multiWriter = @import("io/multi_writer.zig").multiWriter; +pub const MultiWriter = @import("Io/multi_writer.zig").MultiWriter; +pub const multiWriter = @import("Io/multi_writer.zig").multiWriter; -pub const BitReader = @import("io/bit_reader.zig").BitReader; -pub const bitReader = @import("io/bit_reader.zig").bitReader; +pub const BitReader = @import("Io/bit_reader.zig").BitReader; +pub const bitReader = @import("Io/bit_reader.zig").bitReader; -pub const BitWriter = @import("io/bit_writer.zig").BitWriter; -pub const bitWriter = @import("io/bit_writer.zig").bitWriter; +pub const BitWriter = @import("Io/bit_writer.zig").BitWriter; +pub const bitWriter = @import("Io/bit_writer.zig").bitWriter; -pub const ChangeDetectionStream = @import("io/change_detection_stream.zig").ChangeDetectionStream; -pub const changeDetectionStream = @import("io/change_detection_stream.zig").changeDetectionStream; +pub const ChangeDetectionStream = @import("Io/change_detection_stream.zig").ChangeDetectionStream; +pub const changeDetectionStream = @import("Io/change_detection_stream.zig").changeDetectionStream; -pub const FindByteWriter = @import("io/find_byte_writer.zig").FindByteWriter; -pub const findByteWriter = @import("io/find_byte_writer.zig").findByteWriter; +pub const FindByteWriter = @import("Io/find_byte_writer.zig").FindByteWriter; +pub const findByteWriter = @import("Io/find_byte_writer.zig").findByteWriter; -pub const BufferedAtomicFile = @import("io/buffered_atomic_file.zig").BufferedAtomicFile; +pub const BufferedAtomicFile = @import("Io/buffered_atomic_file.zig").BufferedAtomicFile; -pub const StreamSource = @import("io/stream_source.zig").StreamSource; +pub const StreamSource = @import("Io/stream_source.zig").StreamSource; -pub const tty = @import("io/tty.zig"); +pub const tty = @import("Io/tty.zig"); /// A Writer that doesn't write to anything. pub const null_writer: NullWriter = .{ .context = {} }; @@ -869,16 +869,16 @@ pub fn PollFiles(comptime StreamEnum: type) type { test { _ = Reader; _ = Writer; - _ = @import("io/bit_reader.zig"); - _ = @import("io/bit_writer.zig"); - _ = @import("io/buffered_atomic_file.zig"); - _ = @import("io/buffered_reader.zig"); - _ = @import("io/buffered_writer.zig"); - _ = @import("io/c_writer.zig"); - _ = @import("io/counting_writer.zig"); - _ = @import("io/counting_reader.zig"); - _ = @import("io/fixed_buffer_stream.zig"); - _ = @import("io/seekable_stream.zig"); - _ = @import("io/stream_source.zig"); - _ = @import("io/test.zig"); + _ = @import("Io/bit_reader.zig"); + _ = @import("Io/bit_writer.zig"); + _ = @import("Io/buffered_atomic_file.zig"); + _ = @import("Io/buffered_reader.zig"); + _ = @import("Io/buffered_writer.zig"); + _ = @import("Io/c_writer.zig"); + _ = @import("Io/counting_writer.zig"); + _ = @import("Io/counting_reader.zig"); + _ = @import("Io/fixed_buffer_stream.zig"); + _ = @import("Io/seekable_stream.zig"); + _ = @import("Io/stream_source.zig"); + _ = @import("Io/test.zig"); } diff --git a/lib/std/io/DeprecatedReader.zig b/lib/std/Io/DeprecatedReader.zig similarity index 100% rename from lib/std/io/DeprecatedReader.zig rename to lib/std/Io/DeprecatedReader.zig diff --git a/lib/std/io/DeprecatedWriter.zig b/lib/std/Io/DeprecatedWriter.zig similarity index 100% rename from lib/std/io/DeprecatedWriter.zig rename to lib/std/Io/DeprecatedWriter.zig diff --git a/lib/std/io/Reader.zig b/lib/std/Io/Reader.zig similarity index 100% rename from lib/std/io/Reader.zig rename to lib/std/Io/Reader.zig diff --git a/lib/std/io/Reader/Limited.zig b/lib/std/Io/Reader/Limited.zig similarity index 100% rename from lib/std/io/Reader/Limited.zig rename to lib/std/Io/Reader/Limited.zig diff --git a/lib/std/io/Reader/test.zig b/lib/std/Io/Reader/test.zig similarity index 100% rename from lib/std/io/Reader/test.zig rename to lib/std/Io/Reader/test.zig diff --git a/lib/std/io/Writer.zig b/lib/std/Io/Writer.zig similarity index 100% rename from lib/std/io/Writer.zig rename to lib/std/Io/Writer.zig diff --git a/lib/std/io/bit_reader.zig b/lib/std/Io/bit_reader.zig similarity index 100% rename from lib/std/io/bit_reader.zig rename to lib/std/Io/bit_reader.zig diff --git a/lib/std/io/bit_writer.zig b/lib/std/Io/bit_writer.zig similarity index 100% rename from lib/std/io/bit_writer.zig rename to lib/std/Io/bit_writer.zig diff --git a/lib/std/io/buffered_atomic_file.zig b/lib/std/Io/buffered_atomic_file.zig similarity index 100% rename from lib/std/io/buffered_atomic_file.zig rename to lib/std/Io/buffered_atomic_file.zig diff --git a/lib/std/io/buffered_reader.zig b/lib/std/Io/buffered_reader.zig similarity index 100% rename from lib/std/io/buffered_reader.zig rename to lib/std/Io/buffered_reader.zig diff --git a/lib/std/io/buffered_writer.zig b/lib/std/Io/buffered_writer.zig similarity index 100% rename from lib/std/io/buffered_writer.zig rename to lib/std/Io/buffered_writer.zig diff --git a/lib/std/io/c_writer.zig b/lib/std/Io/c_writer.zig similarity index 100% rename from lib/std/io/c_writer.zig rename to lib/std/Io/c_writer.zig diff --git a/lib/std/io/change_detection_stream.zig b/lib/std/Io/change_detection_stream.zig similarity index 100% rename from lib/std/io/change_detection_stream.zig rename to lib/std/Io/change_detection_stream.zig diff --git a/lib/std/io/counting_reader.zig b/lib/std/Io/counting_reader.zig similarity index 100% rename from lib/std/io/counting_reader.zig rename to lib/std/Io/counting_reader.zig diff --git a/lib/std/io/counting_writer.zig b/lib/std/Io/counting_writer.zig similarity index 100% rename from lib/std/io/counting_writer.zig rename to lib/std/Io/counting_writer.zig diff --git a/lib/std/io/find_byte_writer.zig b/lib/std/Io/find_byte_writer.zig similarity index 100% rename from lib/std/io/find_byte_writer.zig rename to lib/std/Io/find_byte_writer.zig diff --git a/lib/std/io/fixed_buffer_stream.zig b/lib/std/Io/fixed_buffer_stream.zig similarity index 100% rename from lib/std/io/fixed_buffer_stream.zig rename to lib/std/Io/fixed_buffer_stream.zig diff --git a/lib/std/io/limited_reader.zig b/lib/std/Io/limited_reader.zig similarity index 100% rename from lib/std/io/limited_reader.zig rename to lib/std/Io/limited_reader.zig diff --git a/lib/std/io/multi_writer.zig b/lib/std/Io/multi_writer.zig similarity index 100% rename from lib/std/io/multi_writer.zig rename to lib/std/Io/multi_writer.zig diff --git a/lib/std/io/seekable_stream.zig b/lib/std/Io/seekable_stream.zig similarity index 100% rename from lib/std/io/seekable_stream.zig rename to lib/std/Io/seekable_stream.zig diff --git a/lib/std/io/stream_source.zig b/lib/std/Io/stream_source.zig similarity index 100% rename from lib/std/io/stream_source.zig rename to lib/std/Io/stream_source.zig diff --git a/lib/std/io/test.zig b/lib/std/Io/test.zig similarity index 100% rename from lib/std/io/test.zig rename to lib/std/Io/test.zig diff --git a/lib/std/io/tty.zig b/lib/std/Io/tty.zig similarity index 100% rename from lib/std/io/tty.zig rename to lib/std/Io/tty.zig diff --git a/lib/std/fs/path.zig b/lib/std/fs/path.zig index 1cf4dc3c64..542166b78e 100644 --- a/lib/std/fs/path.zig +++ b/lib/std/fs/path.zig @@ -227,8 +227,8 @@ test join { try testJoinMaybeZWindows(&[_][]const u8{ "c:\\a\\", "b\\", "c" }, "c:\\a\\b\\c", zero); try testJoinMaybeZWindows( - &[_][]const u8{ "c:\\home\\andy\\dev\\zig\\build\\lib\\zig\\std", "io.zig" }, - "c:\\home\\andy\\dev\\zig\\build\\lib\\zig\\std\\io.zig", + &[_][]const u8{ "c:\\home\\andy\\dev\\zig\\build\\lib\\zig\\std", "ab.zig" }, + "c:\\home\\andy\\dev\\zig\\build\\lib\\zig\\std\\ab.zig", zero, ); @@ -252,8 +252,8 @@ test join { try testJoinMaybeZPosix(&[_][]const u8{ "/a/", "b/", "c" }, "/a/b/c", zero); try testJoinMaybeZPosix( - &[_][]const u8{ "/home/andy/dev/zig/build/lib/zig/std", "io.zig" }, - "/home/andy/dev/zig/build/lib/zig/std/io.zig", + &[_][]const u8{ "/home/andy/dev/zig/build/lib/zig/std", "ab.zig" }, + "/home/andy/dev/zig/build/lib/zig/std/ab.zig", zero, ); diff --git a/lib/std/std.zig b/lib/std/std.zig index 5f13b931d1..564b04c609 100644 --- a/lib/std/std.zig +++ b/lib/std/std.zig @@ -25,6 +25,7 @@ pub const EnumMap = enums.EnumMap; pub const EnumSet = enums.EnumSet; pub const HashMap = hash_map.HashMap; pub const HashMapUnmanaged = hash_map.HashMapUnmanaged; +pub const Io = @import("Io.zig"); pub const MultiArrayList = @import("multi_array_list.zig").MultiArrayList; pub const PriorityQueue = @import("priority_queue.zig").PriorityQueue; pub const PriorityDequeue = @import("priority_dequeue.zig").PriorityDequeue; @@ -67,7 +68,8 @@ pub const hash = @import("hash.zig"); pub const hash_map = @import("hash_map.zig"); pub const heap = @import("heap.zig"); pub const http = @import("http.zig"); -pub const io = @import("io.zig"); +/// Deprecated +pub const io = Io; pub const json = @import("json.zig"); pub const leb = @import("leb128.zig"); pub const log = @import("log.zig"); From bd5745ddf2f5a5d42553b30241f0a44550f1672e Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Thu, 10 Jul 2025 12:41:26 -0700 Subject: [PATCH 2/4] std.log.defaultLog: provide a small buffer --- lib/std/log.zig | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/lib/std/log.zig b/lib/std/log.zig index 20792dcb8f..ca3896e2da 100644 --- a/lib/std/log.zig +++ b/lib/std/log.zig @@ -137,8 +137,11 @@ pub fn defaultLogEnabled(comptime message_level: Level) bool { return comptime logEnabled(message_level, default_log_scope); } -/// The default implementation for the log function, custom log functions may +/// The default implementation for the log function. Custom log functions may /// forward log messages to this function. +/// +/// Uses a 64-byte buffer for formatted printing which is flushed before this +/// function returns. pub fn defaultLog( comptime message_level: Level, comptime scope: @Type(.enum_literal), @@ -147,16 +150,10 @@ pub fn defaultLog( ) void { const level_txt = comptime message_level.asText(); const prefix2 = if (scope == .default) ": " else "(" ++ @tagName(scope) ++ "): "; - const stderr = std.fs.File.stderr().deprecatedWriter(); - var bw = std.io.bufferedWriter(stderr); - const writer = bw.writer(); - - std.debug.lockStdErr(); - defer std.debug.unlockStdErr(); - nosuspend { - writer.print(level_txt ++ prefix2 ++ format ++ "\n", args) catch return; - bw.flush() catch return; - } + var buffer: [64]u8 = undefined; + const stderr = std.debug.lockStderrWriter(&buffer); + defer std.debug.unlockStderrWriter(); + nosuspend stderr.print(level_txt ++ prefix2 ++ format ++ "\n", args) catch return; } /// Returns a scoped logging namespace that logs all messages using the scope From 88e50b30c3c929761f2ae1a924b96f8bc7548b84 Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Thu, 10 Jul 2025 12:58:47 -0700 Subject: [PATCH 3/4] std.debug.print: provide a small buffer --- lib/std/debug.zig | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/lib/std/debug.zig b/lib/std/debug.zig index 5da650266e..0f64b7f951 100644 --- a/lib/std/debug.zig +++ b/lib/std/debug.zig @@ -219,10 +219,14 @@ pub fn unlockStderrWriter() void { std.Progress.unlockStderrWriter(); } -/// Print to stderr, unbuffered, and silently returning on failure. Intended -/// for use in "printf debugging". Use `std.log` functions for proper logging. +/// Print to stderr, silently returning on failure. Intended for use in "printf +/// debugging". Use `std.log` functions for proper logging. +/// +/// Uses a 64-byte buffer for formatted printing which is flushed before this +/// function returns. pub fn print(comptime fmt: []const u8, args: anytype) void { - const bw = lockStderrWriter(&.{}); + var buffer: [64]u8 = undefined; + const bw = lockStderrWriter(&buffer); defer unlockStderrWriter(); nosuspend bw.print(fmt, args) catch return; } From e25541549852c8dcf4acbcc1a3f3d7ef4bcef9d7 Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Thu, 10 Jul 2025 13:14:55 -0700 Subject: [PATCH 4/4] std: add some missing doc comments --- lib/std/Io/Reader.zig | 9 +++++++++ lib/std/Io/Writer.zig | 5 +++++ 2 files changed, 14 insertions(+) diff --git a/lib/std/Io/Reader.zig b/lib/std/Io/Reader.zig index c2f0b25017..518fdf2568 100644 --- a/lib/std/Io/Reader.zig +++ b/lib/std/Io/Reader.zig @@ -840,6 +840,9 @@ pub fn peekDelimiterExclusive(r: *Reader, delimiter: u8) DelimiterError![]u8 { /// Returns number of bytes streamed, which may be zero, or error.EndOfStream /// if the delimiter was not found. /// +/// Asserts buffer capacity of at least one. This function performs better with +/// larger buffers. +/// /// See also: /// * `streamDelimiterEnding` /// * `streamDelimiterLimit` @@ -858,6 +861,9 @@ pub fn streamDelimiter(r: *Reader, w: *Writer, delimiter: u8) StreamError!usize /// Returns number of bytes streamed, which may be zero. End of stream can be /// detected by checking if the next byte in the stream is the delimiter. /// +/// Asserts buffer capacity of at least one. This function performs better with +/// larger buffers. +/// /// See also: /// * `streamDelimiter` /// * `streamDelimiterLimit` @@ -884,6 +890,9 @@ pub const StreamDelimiterLimitError = error{ /// /// Returns number of bytes streamed, which may be zero. End of stream can be /// detected by checking if the next byte in the stream is the delimiter. +/// +/// Asserts buffer capacity of at least one. This function performs better with +/// larger buffers. pub fn streamDelimiterLimit( r: *Reader, w: *Writer, diff --git a/lib/std/Io/Writer.zig b/lib/std/Io/Writer.zig index d79959dcb1..73d504c437 100644 --- a/lib/std/Io/Writer.zig +++ b/lib/std/Io/Writer.zig @@ -560,6 +560,10 @@ pub fn writeAllPreserve(w: *Writer, preserve_length: usize, bytes: []const u8) E /// A user type may be a `struct`, `vector`, `union` or `enum` type. /// /// To print literal curly braces, escape them by writing them twice, e.g. `{{` or `}}`. +/// +/// Asserts `buffer` capacity of at least 2 if a union is printed. This +/// requirement could be lifted by adjusting the code, but if you trigger that +/// assertion it is a clue that you should probably be using a buffer. pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void { const ArgsType = @TypeOf(args); const args_type_info = @typeInfo(ArgsType); @@ -930,6 +934,7 @@ pub fn printAddress(w: *Writer, value: anytype) Error!void { @compileError("cannot format non-pointer type " ++ @typeName(T) ++ " with * specifier"); } +/// Asserts `buffer` capacity of at least 2 if `value` is a union. pub fn printValue( w: *Writer, comptime fmt: []const u8,