authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2026-04-15 16:39:17-07:00
committergravatar for alex@alexrp.comAlex Rønne Petersen <alex@alexrp.com> 2026-04-16 12:34:15+02:00
log2633fe27f2066b4410e0fb40f62408804b28d3aa
tree34b0df1e8fbaedac6a1f26f3b25b347ef4875091
parent73fcba1ef448f369cc4d8f6824f224414cb850ba
signaturebadge-check Signed by SSH key SHA256:7B/LJ7bpR1eX8aCXSr4mtd5M45VMPKcx9zY8e95b5QM

std.Io.Writer.print: update doc comments

notably, removes incorrect mention of {D} format specifier

1 files changed, 41 insertions(+), 41 deletions(-)

lib/std/Io/Writer.zig+41-41
......@@ -551,64 +551,64 @@ pub fn writeAll(w: *Writer, bytes: []const u8) Error!void {
551551 while (index < bytes.len) index += try w.write(bytes[index..]);
552552}
553553
554/// Renders fmt string with args, calling `writer` with slices of bytes.
555/// If `writer` returns an error, the error is returned from `format` and
556/// `writer` is not called again.
554/// Renders `fmt` string with `args`, calling `w` with slices of bytes.
557555///
558/// The format string must be comptime-known and may contain placeholders following
559/// this format:
560/// `{[argument][specifier]:[fill][alignment][width].[precision]}`
556/// The format string must be comptime-known and may contain placeholders
557/// following this format:
558/// ```
559/// {[argument][specifier]:[fill][alignment][width].[precision]}
560/// ```
561561///
562/// Above, each word including its surrounding [ and ] is a parameter which you have to replace with something:
562/// Above, each word including its surrounding [ and ] is a parameter to be replaced with:
563563///
564/// - *argument* is either the numeric index or the field name of the argument that should be inserted
565/// - when using a field name, you are required to enclose the field name (an identifier) in square
566/// brackets, e.g. {[score]...} as opposed to the numeric index form which can be written e.g. {2...}
567/// - *specifier* is a type-dependent formatting option that determines how a type should formatted (see below)
568/// - *fill* is a single byte which is used to pad formatted numbers.
569/// - *alignment* is one of the three bytes '<', '^', or '>' to make numbers
564/// - **argument** is either the numeric index or the field name of the argument that should be inserted.
565/// - When using a field name, the field name (an identifier) must be enclosed in square
566/// brackets, e.g. `{[score]...}` as opposed to the numeric index form which can be written e.g. `{2...}`.
567/// - **specifier** is a type-dependent formatting option that determines how a type should formatted (see below).
568/// - **fill** is a single byte which is used to pad formatted numbers.
569/// - **alignment** is one of the three bytes '<', '^', or '>' to make numbers
570570/// left, center, or right-aligned, respectively.
571571/// - Not all specifiers support alignment.
572/// - Alignment is not Unicode-aware; appropriate only when used with raw bytes or ASCII.
573/// - *width* is the total width of the field in bytes. This only applies to number formatting.
574/// - *precision* specifies how many decimals a formatted number should have.
572/// - Alignment is not Unicode-aware; appropriate only when used with raw
573/// bytes or ASCII.
574/// - **width** is the total size of the field in bytes, only applicable to
575/// number formatting.
576/// - **precision** specifies how many decimals a formatted number should have.
575577///
576/// Note that most of the parameters are optional and may be omitted. Also you
577/// can leave out separators like `:` and `.` when all parameters after the
578/// separator are omitted.
578/// Most of the parameters are optional and may be omitted. The separators (':'
579/// and '.') may be omitted when all parameters afterwards are omitted.
579580///
580/// Only exception is the *fill* parameter. If a non-zero *fill* character is
581/// required at the same time as *width* is specified, one has to specify
582/// *alignment* as well, as otherwise the digit following `:` is interpreted as
583/// *width*, not *fill*.
581/// The **fill** parameter is an exception. If a non-zero **fill** character is
582/// required at the same time as **width** is specified, **alignment** is
583/// required, otherwise the digit following ':' is interpreted as **width**.
584584///
585/// The *specifier* has several options for types:
586/// - `x` and `X`: output numeric value in hexadecimal notation, or string in hexadecimal bytes
585/// **specifier** supports:
586/// - `x` and `X`: numeric value in hexadecimal notation, or string in hexadecimal bytes
587587/// - `s`:
588588/// - for pointer-to-many and C pointers of u8, print as a C-string using zero-termination
589589/// - for slices of u8, print the entire slice as a string without zero-termination
590590/// - `t`:
591591/// - for enums and tagged unions: prints the tag name
592592/// - for error sets: prints the error name
593/// - `b64`: output string as standard base64
594/// - `e`: output floating point value in scientific notation
595/// - `d`: output numeric value in decimal notation
596/// - `b`: output integer value in binary notation
597/// - `o`: output integer value in octal notation
598/// - `c`: output integer as an ASCII character. Integer type must have 8 bits at max.
599/// - `u`: output integer as an UTF-8 sequence. Integer type must have 21 bits at max.
600/// - `D`: output nanoseconds as duration
601/// - `B`: output bytes in SI units (decimal)
602/// - `Bi`: output bytes in IEC units (binary)
603/// - `?`: output optional value as either the unwrapped value, or `null`; may be followed by a format specifier for the underlying value.
604/// - `!`: 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.
605/// - `*`: output the address of the value instead of the value itself.
606/// - `any`: output a value of any type using its default format.
593/// - `b64`: string as standard base64
594/// - `e`: floating point value in scientific notation
595/// - `d`: numeric value in decimal notation
596/// - `b`: integer value in binary notation
597/// - `o`: integer value in octal notation
598/// - `c`: integer as an ASCII character. Integer type must have 8 bits at max.
599/// - `u`: integer as an UTF-8 sequence. Integer type must have 21 bits at max.
600/// - `B`: bytes in SI units (decimal)
601/// - `Bi`: bytes in IEC units (binary)
602/// - `?`: optional value as either the unwrapped value, or `null`; may be followed by a format specifier for the underlying value.
603/// - `!`: error union value as either the unwrapped value, or the formatted error value; may be followed by a format specifier for the underlying value.
604/// - `*`: the address of the value instead of the value itself.
605/// - `any`: a value of any type using its default format.
607606/// - `f`: delegates to a method on the type named "format" with the signature `fn (*Writer, args: anytype) Writer.Error!void`.
608607///
609/// A user type may be a `struct`, `vector`, `union` or `enum` type.
608/// A user type may be a struct, vector, union or enum type.
610609///
611/// To print literal curly braces, escape them by writing them twice, e.g. `{{` or `}}`.
610/// Literal curly braces can be escaped in the format string via doubling, e.g.
611/// `{{` or `}}`.
612612pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void {
613613 const ArgsType = @TypeOf(args);
614614 const args_type_info = @typeInfo(ArgsType);