fmt
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, ... });
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
type field = (...formattable | *modifiers);
Tagged union of the formattable types and modifiers. Used for
functions which accept format strings.
type formattable = (...types::numeric | uintptr | str |
rune | bool |
nullable *void |
void);
Tagged union of all types which are formattable.
type modifiers
type modifiers = struct {
padding: padding,
negation: negation,
width: uint,
precision: uint,
base: strconv::base,
};
Specifies how to format an argument.
type negation
type negation = enum {
NONE,
SPACE,
PLUS,
};
Specifies for numerical arguments when to prepend a plus or minus sign or a
blank space.
type padding
type padding = enum {
ALIGN_RIGHT,
ALIGN_LEFT,
ZEROES,
};
Specifies how to align and pad an argument within a given width.
Functions
fn asprint
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
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
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
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
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
fn errorf(fmt: str, args: field...) (io::error | size);
Formats text for printing and writes it to os::stderr.
fn errorfln
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
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
@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
@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
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
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
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
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
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
fn printf(fmt: str, args: field...) (io::error | size);
Formats text for printing and writes it to os::stdout.
fn printfln
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
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.