1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 |
x1 x1 x1 x1 x1 x1 x1 x1 x1 x1 x1 x1 |
/**
* {@linkcode sprintf} and {@linkcode printf} for printing formatted strings to
* stdout.
*
* ```ts
* import { sprintf } from "@std/fmt/printf";
* import { assertEquals } from "@std/assert";
*
* assertEquals(sprintf("%d", 9), "9");
* assertEquals(sprintf("%o", 9), "11");
* assertEquals(sprintf("%f", 4), "4.000000");
* assertEquals(sprintf("%.3f", 0.9999), "1.000");
* ```
*
* This implementation is inspired by POSIX and Golang but does not port
* implementation code.
*
* sprintf converts and formats a variable number of arguments as is specified
* by a `format string`. In it's basic form, a format string may just be a
* literal. In case arguments are meant to be formatted, a `directive` is
* contained in the format string, preceded by a '%' character:
*
* %<verb>
*
* E.g. the verb `s` indicates the directive should be replaced by the string
* representation of the argument in the corresponding position of the argument
* list. E.g.:
*
* Hello %s!
*
* applied to the arguments "World" yields "Hello World!".
*
* The meaning of the format string is modelled after [POSIX][1] format strings
* as well as well as [Golang format strings][2]. Both contain elements specific
* to the respective programming language that don't apply to JavaScript, so
* they can not be fully supported. Furthermore we implement some functionality
* that is specific to JS.
*
* ## Verbs
*
* The following verbs are supported:
*
* | Verb | Meaning |
* | ----- | -------------------------------------------------------------- |
* | `%` | print a literal percent |
* | `t` | evaluate arg as boolean, print `true` or `false` |
* | `b` | eval as number, print binary |
* | `c` | eval as number, print character corresponding to the codePoint |
* | `o` | eval as number, print octal |
* | `x X` | print as hex (ff FF), treat string as list of bytes |
* | `e E` | print number in scientific/exponent format 1.123123e+01 |
* | `f F` | print number as float with decimal point and no exponent |
* | `g G` | use %e %E or %f %F depending on size of argument |
* | `s` | interpolate string |
* | `T` | type of arg, as returned by `typeof` |
* | `v` | value of argument in 'default' format (see below) |
* | `j` | argument as formatted by `JSON.stringify` |
* | `i` | argument as formatted by `Deno.inspect` |
* | `I` | argument as formatted by `Deno.inspect` in compact format |
*
* ## Width and Precision
*
* Verbs may be modified by providing them with width and precision, either or
* both may be omitted:
*
* %9f width 9, default precision
* %.9f default width, precision 9
* %8.9f width 8, precision 9
* %8.f width 9, precision 0
*
* In general, 'width' describes the minimum length of the output, while
* 'precision' limits the output.
*
* | verb | precision |
* | --------- | --------------------------------------------------------------- |
* | `t` | n/a |
* | `b c o` | n/a |
* | `x X` | n/a for number, strings are truncated to p bytes(!) |
* | `e E f F` | number of places after decimal, default 6 |
* | `g G` | set maximum number of digits |
* | `s` | truncate input |
* | `T` | truncate |
* | `v` | truncate, or depth if used with # see "'default' format", below |
* | `j` | n/a |
*
* Numerical values for width and precision can be substituted for the `*` char,
* in which case the values are obtained from the next args, e.g.:
*
* sprintf("%*.*f", 9, 8, 456.0)
*
* is equivalent to:
*
* sprintf("%9.8f", 456.0)
*
* ## Flags
*
* The effects of the verb may be further influenced by using flags to modify
* the directive:
*
* | Flag | Verb | Meaning |
* | ----- | --------- | -------------------------------------------------------------------------- |
* | `+` | numeric | always print sign |
* | `-` | all | pad to the right (left justify) |
* | `#` | | alternate format |
* | `#` | `b o x X` | prefix with `0b 0 0x` |
* | `#` | `g G` | don't remove trailing zeros |
* | `#` | `v` | use output of `inspect` instead of `toString` |
* | `' '` | | space character |
* | `' '` | `x X` | leave spaces between bytes when printing string |
* | `' '` | `d` | insert space for missing `+` sign character |
* | `0` | all | pad with zero, `-` takes precedence, sign is appended in front of padding |
* | `<` | all | format elements of the passed array according to the directive (extension) |
*
* ## 'default' format
*
* The default format used by `%v` is the result of calling `toString()` on the
* relevant argument. If the `#` flags is used, the result of calling `inspect()`
* is interpolated. In this case, the precision, if set is passed to `inspect()`
* as the 'depth' config parameter.
*
* ## Positional arguments
*
* Arguments do not need to be consumed in the order they are provided and may
* be consumed more than once. E.g.:
*
* sprintf("%[2]s %[1]s", "World", "Hello")
*
* returns "Hello World". The presence of a positional indicator resets the arg
* counter allowing args to be reused:
*
* sprintf("dec[%d]=%d hex[%[1]d]=%x oct[%[1]d]=%#o %s", 1, 255, "Third")
*
* returns `dec[1]=255 hex[1]=0xff oct[1]=0377 Third`
*
* Width and precision my also use positionals:
*
* "%[2]*.[1]*d", 1, 2
*
* This follows the golang conventions and not POSIX.
*
* ## Errors
*
* The following errors are handled:
*
* Incorrect verb:
*
* S("%h", "") %!(BAD VERB 'h')
*
* Too few arguments:
*
* S("%d") %!(MISSING 'd')"
*
* [1]: https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html
* [2]: https://golang.org/pkg/fmt/
*
* @module
*/
import { sprintf as _function_sprintf } from "jsr:@std/[email protected]/printf"
/**
* Converts and formats a variable number of `args` as is specified by `format`.
* `sprintf` returns the formatted string.
*
* See the module documentation for the available format strings.
*
* @example Usage
* ```ts
* import { sprintf } from "@std/fmt/printf";
* import { assertEquals } from "@std/assert";
*
* assertEquals(sprintf("%d", 9), "9");
*
* assertEquals(sprintf("%o", 9), "11");
*
* assertEquals(sprintf("%f", 4), "4.000000");
*
* assertEquals(sprintf("%.3f", 0.9999), "1.000");
* ```
*
* @param format The format string to use
* @param args The arguments to format
* @return The formatted string
*/
const sprintf = _function_sprintf as typeof _function_sprintf
export { sprintf }
import { printf as _function_printf } from "jsr:@std/[email protected]/printf"
/**
* Converts and format a variable number of `args` as is specified by `format`.
* `printf` writes the formatted string to standard output.
*
* See the module documentation for the available format strings.
*
* @example Usage
* ```ts no-assert
* import { printf } from "@std/fmt/printf";
*
* printf("%d", 9); // Prints "9"
*
* printf("%o", 9); // Prints "11"
*
* printf("%f", 4); // Prints "4.000000"
*
* printf("%.3f", 0.9999); // Prints "1.000"
* ```
*
* @param format The format string to use
* @param args The arguments to format
*/
const printf = _function_printf as typeof _function_printf
export { printf }
|