Mirrors/zig
1
0
Fork 0
mirror of https://codeberg.org/ziglang/zig.git synced 2026-04-26 13:01:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

std.Io.Writer.print: update doc comments

Browse Source 
notably, removes incorrect mention of {D} format specifier
This commit is contained in:
Andrew Kelley
2026-04-15 16:39:17 -07:00
parent a05a25e2bb
commit 0dd99c37cc
1 changed files with 41 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/std/Io/Writer.zig
+41 -41
View File
@@ -551,64 +551,64 @@ pub fn writeAll(w: *Writer, bytes: []const u8) Error!void {
while (index < bytes.len) index += try w.write(bytes[index..]); while (index < bytes.len) index += try w.write(bytes[index..]);
} }
/// Renders fmt string with args, calling `writer` with slices of bytes. /// Renders `fmt` string with `args`, calling `w` with slices of bytes.
/// If `writer` returns an error, the error is returned from `format` and
/// `writer` is not called again.
/// ///
/// The format string must be comptime-known and may contain placeholders following /// The format string must be comptime-known and may contain placeholders
/// this format: /// following this format:
/// `{[argument][specifier]:[fill][alignment][width].[precision]}` /// ```
/// {[argument][specifier]:[fill][alignment][width].[precision]}
/// ```
/// ///
/// Above, each word including its surrounding [ and ] is a parameter which you have to replace with something: /// Above, each word including its surrounding [ and ] is a parameter to be replaced with:
/// ///
/// - *argument* is either the numeric index or the field name of the argument that should be inserted /// - **argument** is either the numeric index or the field name of the argument that should be inserted.
/// - when using a field name, you are required to enclose the field name (an identifier) in square /// - When using a field name, the field name (an identifier) must be enclosed in square
/// brackets, e.g. {[score]...} as opposed to the numeric index form which can be written e.g. {2...} /// brackets, e.g. `{[score]...}` as opposed to the numeric index form which can be written e.g. `{2...}`.
/// - *specifier* is a type-dependent formatting option that determines how a type should formatted (see below) /// - **specifier** is a type-dependent formatting option that determines how a type should formatted (see below).
/// - *fill* is a single byte which is used to pad formatted numbers. /// - **fill** is a single byte which is used to pad formatted numbers.
/// - *alignment* is one of the three bytes '<', '^', or '>' to make numbers /// - **alignment** is one of the three bytes '<', '^', or '>' to make numbers
/// left, center, or right-aligned, respectively. /// left, center, or right-aligned, respectively.
/// - Not all specifiers support alignment. /// - Not all specifiers support alignment.
/// - Alignment is not Unicode-aware; appropriate only when used with raw bytes or ASCII. /// - Alignment is not Unicode-aware; appropriate only when used with raw
/// - *width* is the total width of the field in bytes. This only applies to number formatting. /// bytes or ASCII.
/// - *precision* specifies how many decimals a formatted number should have. /// - **width** is the total size of the field in bytes, only applicable to
/// number formatting.
/// - **precision** specifies how many decimals a formatted number should have.
/// ///
/// Note that most of the parameters are optional and may be omitted. Also you /// Most of the parameters are optional and may be omitted. The separators (':'
/// can leave out separators like `:` and `.` when all parameters after the /// and '.') may be omitted when all parameters afterwards are omitted.
/// separator are omitted.
/// ///
/// Only exception is the *fill* parameter. If a non-zero *fill* character is /// The **fill** parameter is an exception. If a non-zero **fill** character is
/// required at the same time as *width* is specified, one has to specify /// required at the same time as **width** is specified, **alignment** is
/// *alignment* as well, as otherwise the digit following `:` is interpreted as /// required, otherwise the digit following ':' is interpreted as **width**.
/// *width*, not *fill*.
/// ///
/// The *specifier* has several options for types: /// **specifier** supports:
/// - `x` and `X`: output numeric value in hexadecimal notation, or string in hexadecimal bytes /// - `x` and `X`: numeric value in hexadecimal notation, or string in hexadecimal bytes
/// - `s`: /// - `s`:
/// - for pointer-to-many and C pointers of u8, print as a C-string using zero-termination /// - for pointer-to-many and C pointers of u8, print as a C-string using zero-termination
/// - for slices of u8, print the entire slice as a string without zero-termination /// - for slices of u8, print the entire slice as a string without zero-termination
/// - `t`: /// - `t`:
/// - for enums and tagged unions: prints the tag name /// - for enums and tagged unions: prints the tag name
/// - for error sets: prints the error name /// - for error sets: prints the error name
/// - `b64`: output string as standard base64 /// - `b64`: string as standard base64
/// - `e`: output floating point value in scientific notation /// - `e`: floating point value in scientific notation
/// - `d`: output numeric value in decimal notation /// - `d`: numeric value in decimal notation
/// - `b`: output integer value in binary notation /// - `b`: integer value in binary notation
/// - `o`: output integer value in octal notation /// - `o`: integer value in octal notation
/// - `c`: output integer as an ASCII character. Integer type must have 8 bits at max. /// - `c`: integer as an ASCII character. Integer type must have 8 bits at max.
/// - `u`: output integer as an UTF-8 sequence. Integer type must have 21 bits at max. /// - `u`: integer as an UTF-8 sequence. Integer type must have 21 bits at max.
/// - `D`: output nanoseconds as duration /// - `B`: bytes in SI units (decimal)
/// - `B`: output bytes in SI units (decimal) /// - `Bi`: bytes in IEC units (binary)
/// - `Bi`: output bytes in IEC units (binary) /// - `?`: optional value as either the unwrapped value, or `null`; may be followed by a format specifier for the underlying value.
/// - `?`: output optional value as either the unwrapped value, or `null`; may be followed by a format specifier for the underlying value. /// - `!`: error union value as either the unwrapped value, or the formatted error value; may be followed by a format specifier for the underlying value.
/// - `!`: output error union value as either the unwrapped value, or the formatted error value; may be followed by a format specifier for the underlying value. /// - `*`: the address of the value instead of the value itself.
/// - `*`: output the address of the value instead of the value itself. /// - `any`: a value of any type using its default format.
/// - `any`: output a value of any type using its default format.
/// - `f`: delegates to a method on the type named "format" with the signature `fn (*Writer, args: anytype) Writer.Error!void`. /// - `f`: delegates to a method on the type named "format" with the signature `fn (*Writer, args: anytype) Writer.Error!void`.
/// ///
/// A user type may be a `struct`, `vector`, `union` or `enum` type. /// 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 `}}`. /// Literal curly braces can be escaped in the format string via doubling, e.g.
/// `{{` or `}}`.
pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void { pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void {
const ArgsType = @TypeOf(args); const ArgsType = @TypeOf(args);
const args_type_info = @typeInfo(ArgsType); const args_type_info = @typeInfo(ArgsType);