@fmt
Import this module with import @fmt.
Formatted output and string formatting functions.
Formatted Output
Section titled “Formatted Output”| Function | Signature | Description |
|---|---|---|
printf |
(format string, args [T]) |
Print formatted string to stdout |
printfln |
(format string, args [T]) |
Print formatted string to stdout with trailing newline |
eprintf |
(format string, args [T]) |
Print formatted string to stderr |
eprintfln |
(format string, args [T]) |
Print formatted string to stderr with trailing newline |
sprintf |
(format string, args [T]) -> string |
Return formatted string |
One array element per format directive; each is independently i64, u64, f64, string, bool, char, or a bigint (i128/u128/i256/u256, integer directives only). Composite types are rejected.
When args is an array literal, each element is checked against its own directive, so the elements may differ in type ({name, 30}); this is the only place a mixed-type array literal is allowed, and its elements are never unified to a common type. The literal must have exactly as many elements as the format string has directives. When args is an array variable of type [T], every directive must accept T; one element is read per directive, and the program panics if the array has fewer elements than directives. args is required even when the format string has no directives; plain text goes through print or println.
eprintln and eprint are builtins, not fmt module functions; use them without an import.
Format Specifiers
Section titled “Format Specifiers”Format strings use C-style % specifiers:
| Specifier | Type | Description |
|---|---|---|
%d, %i |
signed integer or char |
Signed decimal integer |
%u |
unsigned integer | Unsigned decimal integer |
%f |
f32 / f64 |
Decimal floating-point |
%e, %E |
f32 / f64 |
Scientific notation (lowercase / uppercase) |
%g, %G |
f32 / f64 |
Shorter of %f or %e (lowercase / uppercase) |
%s |
string |
String |
%c |
char or signed integer up to i64 |
Single character, printed as its UTF-8 encoding |
%b |
bool |
true / false |
%x, %X |
any integer | Hexadecimal (lowercase / uppercase) |
%o |
any integer | Octal |
%% |
— | Literal % |
Width, precision, and flags (-, +, space, 0, #) follow C printf conventions, except that %s width and precision count codepoints (see below), limited to the ones each conversion gives a meaning to:
| Conversion | Flags | Precision |
|---|---|---|
%d, %i |
- + space 0 |
yes |
%u |
- 0 |
yes |
%x, %X, %o |
- 0 # |
yes |
%f, %e, %E, %g, %G |
- + space 0 # |
yes |
%s |
- |
yes (maximum codepoints) |
%c, %b |
- |
no |
Any other flag or a precision where the table has none is a compile error. C length modifiers (h, hh, l, ll, L) are not accepted: each value is formatted at the width of its type, so %d, %i, %u, %x, %X, and %o are automatically widened to their 64-bit form for Grayscale’s i64/u64 types. A width or precision above 2147483647 is a compile error; C’s printf cannot represent it. Escapes in the format string are decoded before directives are read, so "\x25d" is a %d directive, and a \0 writes a NUL byte rather than ending the format string. %s of a string writes all of its bytes, including any after an embedded NUL. A %s width pads to that many codepoints and a precision keeps at most that many codepoints, never splitting a character: fmt("%.2s", "日本語") is "日本". fmt never uses display columns; a wide character counts as one. %c prints a char (or an integer codepoint) as UTF-8, so 'é' prints as é, and its width counts characters (%3c pads 'é' to three characters, like 'a'); an integer that is not a Unicode scalar value (negative, a surrogate U+D800–U+DFFF, or above U+10FFFF) prints U+FFFD. The same directives also accept i128, u128, i256, and u256, which are rendered from their raw bit pattern (like C printf: %x/%o on a negative value show its two’s-complement form); for a bigint element only width and - apply — the 0, #, +, and space flags and precision are ignored. %f, %c, and %b reject bigints. Composite types (structs, arrays, maps) are not supported — use println for those.
import @fmt
do main() {
mut score i64 = 42mut x i64 = 7fmt.printf("%-10s %5d\n", {"score", score}) // "score 42"fmt.printf("%08.2f\n", {3.14159}) // "00003.14"mut s string = fmt.sprintf("x = %d", {x}) // "x = 7"mut parts [i64] = {2026, 9, 28}fmt.printfln("%d-%02d-%02d", parts) // "2026-09-28" println(s)}Padding
Section titled “Padding”| Function | Signature | Description |
|---|---|---|
pad_left |
(s string, width i64, ch char) -> string |
Pad string on the left to width codepoints with ch |
pad_right |
(s string, width i64, ch char) -> string |
Pad string on the right to width codepoints with ch |
center |
(s string, width i64, ch char) -> string |
Center string within width codepoints, padding both sides with ch |
Number Formatting
Section titled “Number Formatting”| Function | Signature | Description |
|---|---|---|
i64_to_binary |
(n i64) -> string |
Format integer as binary; a negative n is formatted as its 64-bit two’s-complement bits |
f64_to_fixed |
(f f64, decimals i64) -> string |
Format f64 with fixed decimal places |
format_number |
(n i64) -> string |
Decimal string with ASCII comma thousands separators (1234567 → "1,234,567", -1000 → "-1,000") |
format_bytes |
(n i64) -> string |
Human-readable byte count in binary units B/KiB/MiB/GiB/TiB/PiB; whole bytes below 1024 ("1023 B"), one decimal above ("1.5 KiB") |
Formatted output functions take one array element per format directive; each is independently i64, u64, f64, string, bool, char, or a bigint (i128/u128/i256/u256, integer directives only). Composite types (structs, arrays, maps) are not supported. Use println for printing composite types.