fmt: formatted string I/O

A format string consists of a string of literal characters, to be printed verbatim, and format sequences, which describe how to format arguments from a set of variadic parameters for printing.

A format sequence is enclosed in curly braces "{}". An empty sequence takes the next argument from the parameter list, in order. A specific parameter can be selected by indexing it from zero: "{0}", "{1}", and so on. To print "{", use "{{", and for "}", use "}}".

There are two ways to specify how an argument will be formatted: inline format modifiers, and parametric format modifiers.

Inline format modifiers are a series of characters within a format sequence. You can use a colon to add format modifiers; for example, "{:x}" will format an argument in hexadecimal, and "{3:-10}" will left-align the 4th argument (zero indexed) to at least 10 characters.

Format modifiers can be written in any order, and can also be repeated. If multiple conflicting modifiers are given (such as both "x" and "X"), the one furthest to the right will be used.

A format modifier can be any of the following:

• a number N: Sets the width to N. If the value would otherwise be shorter than N runes, insert padding characters in order to make it N runes long. By default, the value is right-aligned, with padding inserted on the left side, and the padding character is " " (a space).
• "-": Left-align the value, inserting padding characters on the right side of the value in order to meet the width requirement.
• "=": Center-align the value, inserting the same amount of padding on the left as on the right. If an odd number of padding characters need to be placed, the extra one will be on the left of the value.
• "_" followed by a rune: Use the given rune as the padding character rather than the default of " " (a space).
• " " (a space): Insert a space before positive integers, where "-" would be if it were negative.
• "+": Insert a "+" before positive integers.
• "x": Format numbers in lowercase hexadecimal.
• "X": Format numbers in uppercase hexadecimal.
• "o": Format numbers in octal.
• "b": Format numbers in binary.
• "e": Format floats in scientific notation.
• "f": Format floats in fixed-point notation.
• "g": Format floats in whichever of scientific and fixed-point notation is shortest. This is the default.
• "F" followed by "s": Use a sign for both positive and negative numbers.
• "F" followed by ".": Always include at least one digit after the decimal point.
• "F" followed by "U": Uppercase INFINITY and NAN.
• "F" followed by "E": Uppercase exponent symbols (E and P rather than e and p).
• "F" followed by "S": Use a sign for both positive and negative exponents.
• "F" followed by "2": Show at least two digits of the exponent.
• "." followed by a number N: Sets the precision to N. Integers will be left-padded with "0"s between the sign and the number itself. Strings will be truncated to N runes. Floats will include up to N digits, counted as per strconv::ftosf, including those before the decimal point in the default case ("g"), excluding them when "f" or "e" are set.

Some inline modifier examples:

fmt::printf("hello {}", "world");		// "hello world"
fmt::printf("{1} {0}", "hello", "world");	// "world hello"
fmt::printf("{:x} {:X}", 51966, 61453);		// "cafe F00D"
fmt::printf("{:-5}", 42);			// "42   "
fmt::printf("{:5}", 42);			// "   42"
fmt::printf("{:.5}", 42);			// "00042"
fmt::printf("{:.2f}", 42.87934);		// "42.88"

A parametric format modifier is a secondary argument from the parameter list, which is a pointer to an instance of mods. This modifier parameter describes how the primary formattable argument is formatted.

A parametric format sequence of this sort takes the form of "{i%j}", where i is the formattable parameter index, j is the modifiers parameter index, and i & j are optional. If either i or j aren't explicitly provided by the user, they will evaluate to the index of the next unused argument.

Some parametric modifier examples:

// "hello world hello"
fmt::printf("{%} {%} {0%1}", // evaluates to "{0%1} {2%3} {0%1}"
	"hello", &fmt::mods { ... },
	"world", &fmt::mods { ... });

// "|hello|     world|0000000123|BEEF|"
fmt::printf("|{%}|{%}|{%}|{%}|",
	"hello", &fmt::mods { ... },
	"world", &fmt::mods { pad = ' ', width = 10, ... },
	123,     &fmt::mods { prec = 10, ... },
	0xBEEF,  &fmt::mods { base = strconv::base::HEX, ... });

type alignment = enum {
	RIGHT,
	CENTER,
	LEFT,
};
type field = (...formattable | *mods);
type formattable = (...types::numeric | uintptr | str | rune | bool | nullable *opaque | void);
type mods = struct {
	alignment: alignment,
	pad: rune,
	neg: neg,
	width: size,
	prec: size,
	base: strconv::base,
	ffmt: strconv::ffmt,
	fflags: strconv::fflags,
};
type neg = enum {
	NONE,
	SPACE,
	PLUS,
};

fn asprint(args: formattable...) (str | nomem);
fn asprintf(fmt: str, args: field...) (str | nomem);
fn bsprint(buf: []u8, args: formattable...) (str | nomem);
fn bsprintf(buf: []u8, fmt: str, args: field...) (str | nomem);
fn error(args: formattable...) (size | io::error);
fn errorf(fmt: str, args: field...) (size | io::error);
fn errorfln(fmt: str, args: field...) (size | io::error);
fn errorln(args: formattable...) (size | io::error);
fn fatal(args: formattable...) never;
fn fatalf(fmt: str, args: field...) never;
fn fprint(h: io::handle, args: formattable...) (size | io::error);
fn fprintf(h: io::handle, fmt: str, args: field...) (size | io::error);
fn fprintfln(h: io::handle, fmt: str, args: field...) (size | io::error);
fn fprintln(h: io::handle, args: formattable...) (size | io::error);
fn print(args: formattable...) (size | io::error);
fn printf(fmt: str, args: field...) (size | io::error);
fn printfln(fmt: str, args: field...) (size | io::error);
fn println(args: formattable...) (size | io::error);

type alignment = enum {
	RIGHT,
	CENTER,
	LEFT,
};

type field = (...formattable | *mods);

type formattable = (...types::numeric | uintptr | str | rune | bool | nullable *opaque | void);

type mods = struct {
	alignment: alignment,
	pad: rune,
	neg: neg,
	width: size,
	prec: size,
	base: strconv::base,
	ffmt: strconv::ffmt,
	fflags: strconv::fflags,
};

type neg = enum {
	NONE,
	SPACE,
	PLUS,
};

fn asprint(args: formattable...) (str | nomem);

fn asprintf(fmt: str, args: field...) (str | nomem);

fn bsprint(buf: []u8, args: formattable...) (str | nomem);

fn bsprintf(buf: []u8, fmt: str, args: field...) (str | nomem);

fn error(args: formattable...) (size | io::error);

fn errorf(fmt: str, args: field...) (size | io::error);

fn errorfln(fmt: str, args: field...) (size | io::error);

fn errorln(args: formattable...) (size | io::error);

fn fatal(args: formattable...) never;

fn fatalf(fmt: str, args: field...) never;

fn fprint(h: io::handle, args: formattable...) (size | io::error);

fn fprintf(h: io::handle, fmt: str, args: field...) (size | io::error);

fn fprintfln(h: io::handle, fmt: str, args: field...) (size | io::error);

fn fprintln(h: io::handle, args: formattable...) (size | io::error);

fn print(args: formattable...) (size | io::error);

fn printf(fmt: str, args: field...) (size | io::error);

fn printfln(fmt: str, args: field...) (size | io::error);

fn println(args: formattable...) (size | io::error);