fmt +linux +x86_64

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:

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:

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

Index

Types

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

Functions

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

Types

type field[link]

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

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

type formattable[link]

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

Tagged union of all types which are formattable.

type modifiers[link]

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

Specifies how to format an argument.

type negation[link]

type negation = enum {
	NONE,
	SPACE,
	PLUS,

};

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

type padding[link]

type padding = enum {
	ALIGN_RIGHT,
	ALIGN_LEFT,
	ZEROES,

};

Specifies how to align and pad an argument within a given width.

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...) (io::error | size);

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...) (io::error | size);

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

fn errorfln[link]

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

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

fn errorln[link]

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

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]

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

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]

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

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...) (io::error | size);

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...) (io::error | size);

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

fn fprintfln[link]

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

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...) (io::error | size);

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...) (io::error | size);

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...) (io::error | size);

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

fn printfln[link]

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

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

fn println[link]

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

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