| ... | @@ -49,6 +49,45 @@ fn peekIsAlign(comptime fmt: []const u8) bool { | ... | @@ -49,6 +49,45 @@ fn peekIsAlign(comptime fmt: []const u8) bool { |
| 49 | /// Renders fmt string with args, calling output with slices of bytes. | 49 | /// Renders fmt string with args, calling output with slices of bytes. |
| 50 | /// If `output` returns an error, the error is returned from `format` and | 50 | /// If `output` returns an error, the error is returned from `format` and |
| 51 | /// `output` is not called again. | 51 | /// `output` is not called again. |
| | 52 | /// |
| | 53 | /// The format string must be comptime known and may contain placeholders following |
| | 54 | /// this format: |
| | 55 | /// `{[position][specifier]:[fill][alignment][width].[precision]}` |
| | 56 | /// |
| | 57 | /// Each word between `[` and `]` is a parameter you have to replace with something: |
| | 58 | /// |
| | 59 | /// - *position* is the index of the argument that should be inserted |
| | 60 | /// - *specifier* is a type-dependent formatting option that determines how a type should formatted (see below) |
| | 61 | /// - *fill* is a single character which is used to pad the formatted text |
| | 62 | /// - *alignment* is one of the three characters `<`, `^` or `>`. they define if the text is *left*, *center*, or *right* aligned |
| | 63 | /// - *width* is the total width of the field in characters |
| | 64 | /// - *precision* specifies how many decimals a formatted number should have |
| | 65 | /// |
| | 66 | /// Note that most of the parameters are optional and may be omitted. Also you can leave out separators like `:` and `.` when |
| | 67 | /// all parameters after the separator are omitted. |
| | 68 | /// Only exception is the *fill* parameter. If *fill* is required, one has to specify *alignment* as well, as otherwise |
| | 69 | /// the digits after `:` is interpreted as *width*, not *fill*. |
| | 70 | /// |
| | 71 | /// The *specifier* has several options for types: |
| | 72 | /// - `x` and `X`: |
| | 73 | /// - format the non-numeric value as a string of bytes in hexadecimal notation ("binary dump") in either lower case or upper case |
| | 74 | /// - output numeric value in hexadecimal notation |
| | 75 | /// - `s`: print a pointer-to-many as a c-string, use zero-termination |
| | 76 | /// - `B` and `Bi`: output a memory size in either metric (1000) or power-of-two (1024) based notation. works for both float and integer values. |
| | 77 | /// - `e`: output floating point value in scientific notation |
| | 78 | /// - `d`: output numeric value in decimal notation |
| | 79 | /// - `b`: output integer value in binary notation |
| | 80 | /// - `c`: output integer as an ASCII character. Integer type must have 8 bits at max. |
| | 81 | /// - `*`: output the address of the value instead of the value itself. |
| | 82 | /// |
| | 83 | /// If a formatted user type contains a function of the type |
| | 84 | /// ``` |
| | 85 | /// fn format(value: ?, comptime fmt: []const u8, options: std.fmt.FormatOptions, context: var, comptime Errors: type, output: fn (@typeOf(context), []const u8) Errors!void) Errors!void |
| | 86 | /// ``` |
| | 87 | /// with `?` being the type formatted, this function will be called instead of the default implementation. |
| | 88 | /// This allows user types to be formatted in a logical manner instead of dumping all fields of the type. |
| | 89 | /// |
| | 90 | /// A user type may be a `struct`, `union` or `enum` type. |
| 52 | pub fn format( | 91 | pub fn format( |
| 53 | context: var, | 92 | context: var, |
| 54 | comptime Errors: type, | 93 | comptime Errors: type, |
Felix "xq" Queißner <xq@random-projects.net> 2019-10-22 20:58:27+02:00
Andrew Kelley <andrew@ziglang.org> 2019-10-22 14:58:27-04:00
lib