fmt+x86_64 +linux

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:

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

Types

type alignment[permalink] [source]

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

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

type field[permalink] [source]

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

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

type formattable[permalink] [source]

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

Tagged union of all types which are formattable.

type mods[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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

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[permalink] [source]

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

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

fn bsprint[permalink] [source]

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

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. Returns nomem, if the buffer isn't large enough to hold the formatted text.

fn bsprintf[permalink] [source]

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

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

fn error[permalink] [source]

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[permalink] [source]

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

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

fn errorfln[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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[permalink] [source]

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

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

fn printfln[permalink] [source]

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[permalink] [source]

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.