fmt+x86_64 +linux

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 a modifier is repeated (or two 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:

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, ... });

Index

Types

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,
};

Functions

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...) (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);

Types

type alignment[link]

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

Alignment modifier. Specifies how to align an argument within a given width.

type field[link]

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

Tagged union of the formattable types and mods. Used for functions which accept format strings.

type formattable[link]

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

Tagged union of all types which are formattable.

type mods[link]

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

Specifies how to format an argument.

type neg[link]

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

Negative modifier. Specifies for numerical arguments when to prepend a plus or minus sign or a blank space.

Functions

fn asprint[link]

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

Formats values for printing using the default format modifiers and writes them into a heap-allocated string separated by spaces. The caller must free the return value.

fn asprintf[link]

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

Formats text for printing and writes it into a heap-allocated string. The caller must free the return value.

fn bsprint[link]

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

Formats values for printing using the default format modifiers and writes them into a caller supplied buffer separated by spaces. The returned string is borrowed from this buffer. Aborts if the buffer isn't large enough to hold the formatted text.

fn bsprintf[link]

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

Formats text for printing and writes it into a caller supplied buffer. The returned string is borrowed from this buffer. Aborts if the buffer isn't large enough to hold the formatted text.

fn error[link]

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

Formats values for printing using the default format modifiers and writes them to os::stderr separated by spaces.

fn errorf[link]

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

Formats text for printing and writes it to os::stderr.

fn errorfln[link]

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

Formats text for printing and writes it to os::stderr, followed by a line feed.

fn errorln[link]

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

Formats values for printing using the default format modifiers and writes them to os::stderr separated by spaces and followed by a line feed.

fn fatal[link]

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

Formats values for printing using the default format modifiers and writes them to os::stderr separated by spaces and followed by a line feed, then exits the program with an error status.

fn fatalf[link]

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

Formats text for printing and writes it to os::stderr, followed by a line feed, then exits the program with an error status.

fn fprint[link]

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

Formats values for printing using the default format modifiers and writes them to an io::handle separated by spaces.

fn fprintf[link]

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

Formats text for printing and writes it to an io::handle.

fn fprintfln[link]

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

Formats text for printing and writes it to an io::handle, followed by a line feed.

fn fprintln[link]

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

Formats values for printing using the default format modifiers and writes them to an io::handle separated by spaces and followed by a line feed.

fn print[link]

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

Formats values for printing using the default format modifiers and writes them to os::stdout separated by spaces.

fn printf[link]

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

Formats text for printing and writes it to os::stdout.

fn printfln[link]

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

Formats text for printing and writes it to os::stdout, followed by a line feed.

fn println[link]

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

Formats values for printing using the default format modifiers and writes them to os::stdout separated by spaces and followed by a line feed.