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 may 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 shall be formatted: inline format modifiers, and parametric format modifiers.

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

The format modifiers take the form of optional flag characters:

• "0": Numeric values are zero-padded up to the required width.
• "-": The value shall be left-aligned, and spaces inserted on the right to meet the required width. "-" takes precedence over "0" if both are used.
• " ": (a space) insert a space before positive numbers, where "-" would be if it were negative.
• "+": insert a "+" before positive numbers, where "-" would be if it were negative. "+" takes precedence over " " if both are used.

Following the flags, an optional decimal number shall specify the minimum width of this field. If "0" or "-" were not given, the default behavior shall be to pad with spaces to achieve the necessary width.

Following the width, an optional precision may be given as a decimal number following a "." character. For integer types, this gives the minimum number of digits to include. For floating types, this gives the number of digits following the radix to include.

Following the precision, an optional character controls the output format:

• x, X: print in lowercase or uppercase hexadecimal
• o, b: print in octal or binary

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("{:05}", 42);			// "00042"

A parametric format modifier is a secondary argument from the parameter list, which is a pointer to an instance of modifiers. This modifier parameter shall describe 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 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::modifiers { ... },
	"world", &fmt::modifiers { ... });

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

type field;
type formattable;
type modifiers;
type negation;
type padding;

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

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

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

type modifiers = struct {
	padding: padding,
	negation: negation,
	width: uint,
	precision: uint,
	base: strconv::base,
};

type negation = enum {
	NONE,
	SPACE,
	PLUS,

};

type padding = enum {
	ALIGN_RIGHT,
	ALIGN_LEFT,
	ZEROES,

};

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

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

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

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

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

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

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

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

@noreturn fn fatal(args: formattable...) void;

@noreturn fn fatalf(fmt: str, args: field...) void;

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

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

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

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

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

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

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

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