lib/string-format.x

Checked formatting of Var values into a String.

Primary API

String

String.format

String String.format(String fmt, List values)

Formats values through a checked, C-style subset of fmt. The receiver is decoded runtime text, so this fixed-signature operation is safe to call through the interpreter as fmt.format(values). It supports %%, flags -+ #0, numeric or * width and precision, integer conversions d i o u x X with hh h l ll, floating conversions f F e E g G a A with default, l, or L, and %c and %s. Numeric values are converted with Var.convert; %s uses Var.str.

Pointer and write-count conversions, wide strings and characters, positional arguments, j z t lengths, malformed formats, and missing or excess values are rejected. %c also rejects NUL because canonical Strings cannot contain it. Output is staged privately and no result is published on failure. Formatting follows the process locale.

Raises: <format> with byte offset and reason; numeric and string conversion failures are nested as cause. Allocation failures may also transfer while staging or canonicalizing the result.

Source: lib/string-format.x:76

Design notes

String.format parses a checked subset of C’s format syntax itself, converts each Var value to the C type its conversion names, and prints it through Buffer.printf, so a format read at run time cannot pass C a mismatched argument. String.printf, which hands C arguments straight to vsnprintf, stays with the other constructors in string.x.

Tests and examples

make verify (unittest/test-string.x).