#Format
#Format is the one attribute written before a parameter. It marks a char8[..] parameter as a format string, followed by a variadic parameter whose arguments fill its placeholders. When a call passes a string literal for it, the compiler counts the placeholders against the arguments and refuses a mismatch while compiling, rather than leaving it to fail at run time.
format-parameter = "#Format" identifier ":" "char8[..]"
The standard printing functions are declared this way:
pub func PrintLine(#Format format: char8[..], args: &Display...) -> IoError?
A function of your own takes it just as well; the compiler recognizes no package or function by name, only the attribute:
import Io::PrintLine;
import Format::Display;
func Log(level: int, #Format format: char8[..], args: &Display...) {
PrintLine(format, args...);
}
func Main() -> int {
Log(1, "{} of {}", 3, 4); // 3 of 4
Log(1, "{{}} {:x}", 255); // {} ff
return 0;
}
Placeholders
A placeholder is {} or {:spec}; {{ and }} are literal braces and count for nothing. A call whose literal has a different number of placeholders than arguments is an error:
error: format string has 2 placeholders, but 1 argument was provided
note: format parameter 'format' of 'Log' declared at 'Src/Main.rux':4:32
help: pass one argument for each '{}' placeholder
Only a literal can be counted. A format held in a variable, a spread argument such as args..., and a spec the formatter itself would reject are left to the formatter's check at run time.
Named placeholders
A placeholder may name the value it writes instead: {name} and {name:spec} name a binding in scope — a local, a parameter, a module constant or variable, or self — or a field path through one, and write it as {} and {:spec} would write the same value passed as an argument:
import Io::PrintLine;
struct Point {
x: int;
y: int;
}
func Main() -> int {
let key = "origin";
let point = Point { x: 3, y: 4 };
PrintLine("{key} = ({point.x}, {point.y:>4})"); // origin = (3, 4)
return 0;
}
The compiler rewrites such a literal into the positional literal and the values its names stand for, so the run-time formatter is unchanged. Only a literal passed for a #Format parameter is read this way; anywhere else "{key}" is plain text. One literal names every placeholder or none, and a literal with named placeholders takes no arguments after it. Only names are allowed in the braces — a call or an operator is passed as an argument to a {} placeholder instead:
error: format string mixes named and positional placeholders
help: name every placeholder or none
error: format placeholder '{Twice(count)}' must name a binding or a field path
A name that nothing declares is reported where the placeholder writes it.
Rules
| Mistake | Error |
|---|---|
| no variadic parameter after it | '#Format' parameter 'format' must be followed by a variadic parameter |
| on the variadic parameter itself | '#Format' cannot be applied to variadic parameter 'args' |
| on two parameters | '#Format' is already applied to parameter 'a' |
| on the receiver | '#Format' cannot be applied to the receiver 'self' |
| with an argument | '#Format' does not accept arguments |
| another name before a parameter | unknown parameter attribute '#Trim' |
A function has at most one format string, and the variadic parameter it counts against must be the last parameter.
See also
- Parameters — variadic parameters and spreads
- Attributes — the declaration attributes
- Learn: Format, Variadic