| ... | @@ -551,64 +551,64 @@ pub fn writeAll(w: *Writer, bytes: []const u8) Error!void { | ... | @@ -551,64 +551,64 @@ pub fn writeAll(w: *Writer, bytes: []const u8) Error!void { |
| 551 | while (index < bytes.len) index += try w.write(bytes[index..]); | 551 | while (index < bytes.len) index += try w.write(bytes[index..]); |
| 552 | } | 552 | } |
| 553 | | 553 | |
| 554 | /// Renders fmt string with args, calling `writer` with slices of bytes. | 554 | /// Renders `fmt` string with `args`, calling `w` with slices of bytes. |
| 555 | /// If `writer` returns an error, the error is returned from `format` and | | |
| 556 | /// `writer` is not called again. | | |
| 557 | /// | 555 | /// |
| 558 | /// The format string must be comptime-known and may contain placeholders following | 556 | /// The format string must be comptime-known and may contain placeholders |
| 559 | /// this format: | 557 | /// following this format: |
| 560 | /// `{[argument][specifier]:[fill][alignment][width].[precision]}` | 558 | /// ``` |
| | 559 | /// {[argument][specifier]:[fill][alignment][width].[precision]} |
| | 560 | /// ``` |
| 561 | /// | 561 | /// |
| 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: |
| 563 | /// | 563 | /// |
| 564 | /// - *argument* is either the numeric index or the field name of the argument that should be inserted | 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 | 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...} | 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) | 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. | 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 | 569 | /// - **alignment** is one of the three bytes '<', '^', or '>' to make numbers |
| 570 | /// left, center, or right-aligned, respectively. | 570 | /// left, center, or right-aligned, respectively. |
| 571 | /// - Not all specifiers support alignment. | 571 | /// - Not all specifiers support alignment. |
| 572 | /// - Alignment is not Unicode-aware; appropriate only when used with raw bytes or ASCII. | 572 | /// - Alignment is not Unicode-aware; appropriate only when used with raw |
| 573 | /// - *width* is the total width of the field in bytes. This only applies to number formatting. | 573 | /// bytes or ASCII. |
| 574 | /// - *precision* specifies how many decimals a formatted number should have. | 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. |
| 575 | /// | 577 | /// |
| 576 | /// Note that most of the parameters are optional and may be omitted. Also you | 578 | /// Most of the parameters are optional and may be omitted. The separators (':' |
| 577 | /// can leave out separators like `:` and `.` when all parameters after the | 579 | /// and '.') may be omitted when all parameters afterwards are omitted. |
| 578 | /// separator are omitted. | | |
| 579 | /// | 580 | /// |
| 580 | /// Only exception is the *fill* parameter. If a non-zero *fill* character is | 581 | /// The **fill** parameter is an exception. If a non-zero **fill** character is |
| 581 | /// required at the same time as *width* is specified, one has to specify | 582 | /// required at the same time as **width** is specified, **alignment** is |
| 582 | /// *alignment* as well, as otherwise the digit following `:` is interpreted as | 583 | /// required, otherwise the digit following ':' is interpreted as **width**. |
| 583 | /// *width*, not *fill*. | | |
| 584 | /// | 584 | /// |
| 585 | /// The *specifier* has several options for types: | 585 | /// **specifier** supports: |
| 586 | /// - `x` and `X`: output numeric value in hexadecimal notation, or string in hexadecimal bytes | 586 | /// - `x` and `X`: numeric value in hexadecimal notation, or string in hexadecimal bytes |
| 587 | /// - `s`: | 587 | /// - `s`: |
| 588 | /// - for pointer-to-many and C pointers of u8, print as a C-string using zero-termination | 588 | /// - for pointer-to-many and C pointers of u8, print as a C-string using zero-termination |
| 589 | /// - for slices of u8, print the entire slice as a string without zero-termination | 589 | /// - for slices of u8, print the entire slice as a string without zero-termination |
| 590 | /// - `t`: | 590 | /// - `t`: |
| 591 | /// - for enums and tagged unions: prints the tag name | 591 | /// - for enums and tagged unions: prints the tag name |
| 592 | /// - for error sets: prints the error name | 592 | /// - for error sets: prints the error name |
| 593 | /// - `b64`: output string as standard base64 | 593 | /// - `b64`: string as standard base64 |
| 594 | /// - `e`: output floating point value in scientific notation | 594 | /// - `e`: floating point value in scientific notation |
| 595 | /// - `d`: output numeric value in decimal notation | 595 | /// - `d`: numeric value in decimal notation |
| 596 | /// - `b`: output integer value in binary notation | 596 | /// - `b`: integer value in binary notation |
| 597 | /// - `o`: output integer value in octal notation | 597 | /// - `o`: integer value in octal notation |
| 598 | /// - `c`: output integer as an ASCII character. Integer type must have 8 bits at max. | 598 | /// - `c`: 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. | 599 | /// - `u`: integer as an UTF-8 sequence. Integer type must have 21 bits at max. |
| 600 | /// - `D`: output nanoseconds as duration | 600 | /// - `B`: bytes in SI units (decimal) |
| 601 | /// - `B`: output bytes in SI units (decimal) | 601 | /// - `Bi`: bytes in IEC units (binary) |
| 602 | /// - `Bi`: output 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 | /// - `?`: output 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 | /// - `!`: 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. | 604 | /// - `*`: the address of the value instead of the value itself. |
| 605 | /// - `*`: output the address of the value instead of the value itself. | 605 | /// - `any`: a value of any type using its default format. |
| 606 | /// - `any`: output a value of any type using its default format. | | |
| 607 | /// - `f`: delegates to a method on the type named "format" with the signature `fn (*Writer, args: anytype) Writer.Error!void`. | 606 | /// - `f`: delegates to a method on the type named "format" with the signature `fn (*Writer, args: anytype) Writer.Error!void`. |
| 608 | /// | 607 | /// |
| 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. |
| 610 | /// | 609 | /// |
| 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 `}}`. |
| 612 | pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void { | 612 | pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void { |
| 613 | const ArgsType = @TypeOf(args); | 613 | const ArgsType = @TypeOf(args); |
| 614 | const args_type_info = @typeInfo(ArgsType); | 614 | const args_type_info = @typeInfo(ArgsType); |
Andrew Kelley <andrew@ziglang.org> 2026-04-15 16:39:17-07:00
lib