1 The `printf()` function formats given input value according to a format 2 string specified as first argument. The format string mimicks the syntax 3 and directives used by C printf(). 4 5 Each directive (with the exception of %%) in the format string expects 6 a corresponding argument. If fewer arguments are passed to printf() than 7 required by the format string, missing values will be assumed to be `null` 8 and be interpreted accordingly. Excess arguments are ignored. 9 10 Writes the output string formatted according to the format string with all 11 format directives interpolated by their respective values to the standard 12 output stream of the VM. 13 14 Returns the number of bytes written to the output stream. 15 16 Writes an empty string in case the format string argument is not a valid 17 string value. 18 19 -- Testcase -- 20 {% 21 // String interpolation, corresponding value will be converted 22 // into string if needed. 23 printf("Hello %s!\n", "World"); 24 printf("Hello %s!\n", false); 25 printf("Hello %s!\n", 123); 26 printf("Hello %s!\n", null); 27 printf("Hello %s!\n"); 28 29 // Signed integer interpolation, corresponding value will be 30 // converted into integer if needed. Also `d` and `i` are aliases. 31 printf("%d\n", 123); 32 printf("%i\n", 456.789); 33 printf("%d\n", true); 34 printf("%d\n", "0x42"); 35 printf("%d\n", "invalid"); 36 printf("%d\n", null); 37 printf("%d\n", 0xffffffffffffffff); 38 printf("%d\n"); 39 40 // Unsigned integer interpolation in decimal notation, corresponding 41 // value will be converted into unsigned integer if needed. 42 printf("%u\n", 123); 43 printf("%u\n", -123); 44 printf("%u\n", 0xffffffffffffffff); 45 printf("%u\n", 456.789); 46 printf("%u\n", "invalid"); 47 printf("%u\n", null); 48 printf("%u\n"); 49 50 // Unsigned integer interpolation in octal notation, corresponding 51 // value will be converted into unsigned integer if needed. 52 printf("%o\n", 123); 53 printf("%o\n", -123); 54 printf("%o\n", 0xffffffffffffffff); 55 printf("%o\n", 456.789); 56 printf("%o\n", "invalid"); 57 printf("%o\n", null); 58 printf("%o\n"); 59 60 // Unsigned integer interpolation in lower case hexadecimal notation, 61 // corresponding value will be converted into unsigned integer if 62 // needed. 63 printf("%x\n", 123); 64 printf("%x\n", -123); 65 printf("%x\n", 0xffffffffffffffff); 66 printf("%x\n", 456.789); 67 printf("%x\n", "invalid"); 68 printf("%x\n", null); 69 printf("%x\n"); 70 71 // Unsigned integer interpolation in upper case hexadecimal notation, 72 // corresponding value will be converted into unsigned integer if 73 // needed. 74 printf("%X\n", 123); 75 printf("%X\n", -123); 76 printf("%X\n", 0xffffffffffffffff); 77 printf("%X\n", 456.789); 78 printf("%X\n", "invalid"); 79 printf("%X\n", null); 80 printf("%X\n"); 81 82 // Floating point value interpolation in exponential notation, 83 // corresponding value will be converted to double if needed. 84 printf("%e\n", 123); 85 printf("%e\n", -123); 86 printf("%e\n", 456.789); 87 printf("%e\n", -456.789); 88 printf("%e\n", "invalid"); 89 printf("%e\n", null); 90 printf("%e\n"); 91 92 // Floating point value interpolation in exponential notation, 93 // using uppercase characters. Corresponding value will be converted 94 // to double if needed. 95 printf("%E\n", 123); 96 printf("%E\n", -123); 97 printf("%E\n", 456.789); 98 printf("%E\n", -456.789); 99 printf("%E\n", "invalid"); 100 printf("%E\n", null); 101 printf("%E\n"); 102 103 // Floating point value interpolation in decimal point notation, 104 // corresponding value will be converted to double if needed. 105 printf("%f\n", 123); 106 printf("%f\n", -123); 107 printf("%f\n", 456.789); 108 printf("%f\n", -456.789); 109 printf("%f\n", "invalid"); 110 printf("%f\n", null); 111 printf("%f\n"); 112 113 // Floating point value interpolation in decimal point notation, 114 // using uppercase characters. Corresponding value will be converted 115 // to double if needed. 116 printf("%F\n", 123); 117 printf("%F\n", -123); 118 printf("%F\n", 456.789); 119 printf("%F\n", -456.789); 120 printf("%F\n", "invalid"); 121 printf("%F\n", null); 122 printf("%F\n"); 123 124 // Floating point value interpolation in either decimal point or 125 // exponential notation, depending on size of exponent. Corresponding 126 // value will be converted to double if needed. 127 printf("%g\n", 123.456); 128 printf("%g\n", 0.0000001); 129 printf("%g\n", "invalid"); 130 131 // Floating point value interpolation in either decimal point or 132 // exponential notation, depending on size of exponent and using 133 // uppercase characters. Corresponding value will be converted to 134 // double if needed. 135 printf("%G\n", 123.456); 136 printf("%G\n", 0.0000001); 137 printf("%G\n", "invalid"); 138 139 // Character interpolation. The corresponding value is casted as `char` 140 // and the resulting character is interpolated. 141 printf("%c\n", 65); 142 //printf("%c\n", -1); 143 //printf("%c\n", 456.789); 144 //printf("%c\n", "invalid"); 145 146 // JSON interpolation. The corresponding value is JSON encoded and 147 // interpolated as string. 148 printf("%J\n", "Hello\n"); 149 printf("%J\n", 123); 150 printf("%J\n", [ 1, 2, 3 ]); 151 printf("%J\n", { some: "dictionary", an: [ "array", true, false ] }); 152 printf("%J\n", null); 153 printf("%J\n"); 154 155 // Escaping `%`. The `%%` format string will produce a literal `%`. 156 // No corresponding argument is expected. 157 printf("%%\n"); 158 %} 159 -- End -- 160 161 -- Expect stdout -- 162 Hello World! 163 Hello false! 164 Hello 123! 165 Hello (null)! 166 Hello (null)! 167 123 168 456 169 1 170 66 171 0 172 0 173 -1 174 0 175 123 176 18446744073709551493 177 18446744073709551615 178 456 179 0 180 0 181 0 182 173 183 1777777777777777777605 184 1777777777777777777777 185 710 186 0 187 0 188 0 189 7b 190 ffffffffffffff85 191 ffffffffffffffff 192 1c8 193 0 194 0 195 0 196 7B 197 FFFFFFFFFFFFFF85 198 FFFFFFFFFFFFFFFF 199 1C8 200 0 201 0 202 0 203 1.230000e+02 204 -1.230000e+02 205 4.567890e+02 206 -4.567890e+02 207 nan 208 0.000000e+00 209 0.000000e+00 210 1.230000E+02 211 -1.230000E+02 212 4.567890E+02 213 -4.567890E+02 214 NAN 215 0.000000E+00 216 0.000000E+00 217 123.000000 218 -123.000000 219 456.789000 220 -456.789000 221 nan 222 0.000000 223 0.000000 224 123.000000 225 -123.000000 226 456.789000 227 -456.789000 228 NAN 229 0.000000 230 0.000000 231 123.456 232 1e-07 233 nan 234 123.456 235 1E-07 236 NAN 237 A 238 "Hello\n" 239 123 240 [ 1, 2, 3 ] 241 { "some": "dictionary", "an": [ "array", true, false ] } 242 null 243 null 244 % 245 -- End -- 246 247 248 Field widths may be specified for format directives. 249 250 -- Testcase -- 251 {% 252 // by default the output of a format directive is as long as the 253 // string representation of the corresponding value 254 printf("[%s]\n", "test"); 255 256 // by specifying a field width, the output will be padded to the 257 // given length 258 printf("[%10s]\n", "test"); 259 260 // the same applies to numbers 261 printf("[%10d]\n", 123); 262 printf("[%10f]\n", 1.0); 263 264 // and to char formats 265 printf("[%10c]\n", 65); 266 267 // field width is not applicable to `%` formats 268 printf("[%10%]\n"); 269 %} 270 -- End -- 271 272 -- Expect stdout -- 273 [test] 274 [ test] 275 [ 123] 276 [ 1.000000] 277 [ A] 278 [%] 279 -- End -- 280 281 282 Precisions may be specified for format directives. 283 284 -- Testcase -- 285 {% 286 // For `f`, `F`, `e` and `E`, the precision specifies the amount of 287 // digits after the comma 288 printf("[%.3f]\n", 1/3); 289 printf("[%.3F]\n", 1/3); 290 printf("[%.3e]\n", 1/3); 291 printf("[%.3E]\n", 1/3); 292 293 // For `g` and `G` the precision specifies the number of significant 294 // digits to print before switching to exponential notation 295 printf("[%.3g]\n", 1000.1); 296 printf("[%.3G]\n", 1000.1); 297 298 // For strings, the precision specifies the amount of characters to 299 // print at most 300 printf("[%.5s]\n", "test"); 301 printf("[%.3s]\n", "test"); 302 303 // For JSON format, the precision specifies the amount of indentation 304 // to use. Omitting precision will not indent, specifying a precision 305 // of `0` uses tabs for indentation, any other precision uses this 306 // many spaces 307 printf("<%J>\n", [ 1, 2, 3, { true: false } ]), // no indent 308 printf("<%.J>\n", [ 1, 2, 3, { true: false } ]), // tab indent 309 printf("<%.0J>\n", [ 1, 2, 3, { true: false } ]), // tab indent 310 printf("<%.1J>\n", [ 1, 2, 3, { true: false } ]), // indent using one space 311 printf("<%.4J>\n", [ 1, 2, 3, { true: false } ]), // indent using four spaces 312 313 // precision does not apply to char, integer or `%` formats 314 printf("[%.3d]\n", 1000); 315 printf("[%.3c]\n", 65); 316 printf("[%.3%]\n"); 317 %} 318 -- End -- 319 320 -- Expect stdout -- 321 [0.000] 322 [0.000] 323 [0.000e+00] 324 [0.000E+00] 325 [1e+03] 326 [1E+03] 327 [test] 328 [tes] 329 <[ 1, 2, 3, { "true": false } ]> 330 <[ 331 1, 332 2, 333 3, 334 { 335 "true": false 336 } 337 ]> 338 <[ 339 1, 340 2, 341 3, 342 { 343 "true": false 344 } 345 ]> 346 <[ 347 1, 348 2, 349 3, 350 { 351 "true": false 352 } 353 ]> 354 <[ 355 1, 356 2, 357 3, 358 { 359 "true": false 360 } 361 ]> 362 [1000] 363 [A] 364 [%] 365 -- End -- 366 367 368 A number of flag characters are supported for format directives. 369 370 -- Testcase -- 371 {% 372 // The recognized flag characters are `#`, `0`, `-`, `+` and ` ` (space) 373 printf("%#0+- s\n", "test"); 374 375 // Repetitions of flag characters are accepted 376 printf("%###s\n", "test"); 377 printf("%000s\n", "test"); 378 printf("%++-s\n", "test"); 379 printf("%-- s\n", "test"); 380 printf("% s\n", "test"); 381 382 // The `#` flag produces alternative forms of various conversions 383 printf("%o / %#o\n", 15, 15); 384 printf("%x / %#x\n", 16, 16); 385 printf("%X / %#X\n", 17, 17); 386 printf("%g / %#g\n", 1.0, 1.0); 387 388 // The `0` flag indicates zero- instead of space-padding for various 389 // numeric conversions. 390 printf("[%5d / %05d]\n", -10, -10); 391 printf("[%5d / %05d]\n", 11, 11); 392 printf("[%5g / %05g]\n", -12.0, -12.0); 393 printf("[%5g / %05g]\n", 13.0, 13.0); 394 printf("[%5s / %05s]\n", "a", "a"); 395 396 // The `-` flag indicates left, instead of right padding. It will 397 // override `0` and always pad with spaces 398 printf("[%-5d / %-05d]\n", -10, -10); 399 printf("[%-5d / %-05d]\n", 11, 11); 400 printf("[%-5g / %-05g]\n", -12.0, -12.0); 401 printf("[%-5g / %-05g]\n", 13.0, 13.0); 402 printf("[%-5s / %-05s]\n", "a", "a"); 403 404 // The `+` flag indicates that a sign (`+` or `-`) should be placed 405 // before signed numeric values. It overrides ` ` (space). 406 printf("[%+5d / %+05d]\n", -10, -10); 407 printf("[%+5d / %+05d]\n", 11, 11); 408 printf("[%+5g / %+05g]\n", -12.0, -12.0); 409 printf("[%+5g / %+05g]\n", 13.0, 13.0); 410 printf("[%+5s / %+05s]\n", "a", "a"); 411 412 // The ` ` (space) flag indicates that a blank should be placed 413 // before positive numbers (useful to ensure that negative and 414 // positive values in output are aligned) 415 printf("[%-5d / %- 5d]\n", -10, -10); 416 printf("[%-5d / %- 5d]\n", 11, 11); 417 printf("[%-5g / %- 5g]\n", -12.0, -12.0); 418 printf("[%-5g / %- 5g]\n", 13.0, 13.0); 419 printf("[%-5s / %- 5s]\n", "a", "a"); 420 %} 421 -- End -- 422 423 -- Expect stdout -- 424 test 425 test 426 test 427 test 428 test 429 test 430 17 / 017 431 10 / 0x10 432 11 / 0X11 433 1 / 1.00000 434 [ -10 / -0010] 435 [ 11 / 00011] 436 [ -12 / -0012] 437 [ 13 / 00013] 438 [ a / a] 439 [-10 / -10 ] 440 [11 / 11 ] 441 [-12 / -12 ] 442 [13 / 13 ] 443 [a / a ] 444 [ -10 / -0010] 445 [ +11 / +0011] 446 [ -12 / -0012] 447 [ +13 / +0013] 448 [ a / a] 449 [-10 / -10 ] 450 [11 / 11 ] 451 [-12 / -12 ] 452 [13 / 13 ] 453 [a / a ] 454 -- End -- 455 456 457 Unrecognized format directives are copied to the output string as-is. 458 459 -- Testcase -- 460 {% 461 // A truncated format directive is preserved 462 printf("test %\n", "test"); 463 printf("test %-010.3\n", "test"); 464 465 // An unrecognized format directive is preserved 466 printf("test %y test\n", 123); 467 printf("test %~123s test\n", 123); 468 %} 469 -- End -- 470 471 -- Expect stdout -- 472 test % 473 test %-010.3 474 test %y test 475 test %~123s test 476 -- End -- 477 478 479 Missing values for format directives are treated as `null`. 480 481 -- Testcase -- 482 {% 483 printf("%s\n"); 484 printf("%d\n"); 485 printf("%u\n"); 486 printf("%o\n"); 487 printf("%x\n"); 488 printf("%X\n"); 489 printf("%f\n"); 490 printf("%F\n"); 491 printf("%e\n"); 492 printf("%E\n"); 493 printf("%g\n"); 494 printf("%G\n"); 495 //printf("%c\n"); 496 printf("%J\n"); 497 %} 498 -- End -- 499 500 -- Expect stdout -- 501 (null) 502 0 503 0 504 0 505 0 506 0 507 0.000000 508 0.000000 509 0.000000e+00 510 0.000000E+00 511 0 512 0 513 null 514 -- End -- 515 516 517 Supplying a non-string format value will yield an empty string result. 518 519 -- Testcase -- 520 {% 521 printf(true, 1, 2, 3); 522 %} 523 -- End -- 524 525 -- Expect stdout -- 526 -- End -- 527 528 529 Prefixing a format directive with `n$` will select the corresponding argument 530 with 1 referring to the first argument. Missing or out-of range arguments will 531 be treated as `null`. 532 533 -- Testcase -- 534 {% 535 printf("%2$s\n", "foo", "bar", "baz"); 536 printf("%10$s\n", "foo", "bar", "baz"); 537 %} 538 -- End -- 539 540 -- Expect stdout -- 541 bar 542 (null) 543 -- End --
This page was automatically generated by LXR 0.3.1. • OpenWrt