std.fmt — moon docs

Functions

fn pad_left(text: string, width: int, fill: string) -> string#

Pads the left side to the requested width.

text: Text to pad.
width: Target byte width; a shorter target returns the text unchanged.
fill: Padding value, repeated to close the gap; an empty fill pads nothing.

println(std.fmt.pad_left("42", 5, "0"))  // 00042
println(std.fmt.pad_right("ok", 5, ".")) // ok...

fn pad_right(text: string, width: int, fill: string) -> string#

Pads the right side to the requested width.

text: Text to pad.
width: Target byte width; a shorter target returns the text unchanged.
fill: Padding value, repeated to close the gap; an empty fill pads nothing.

fn center(text: string, width: int, fill: string) -> string#

Centers text within the requested width.

text: Text to centre.
width: Target byte width; a shorter target returns the text unchanged.
fill: Padding value; an odd remainder goes to the right side.

println(std.fmt.center("hi", 8, "-")) // ---hi---

fn repeat_str(text: string, count: int) -> string#

Repeats text the requested number of times.

text: Text to repeat.
count: How many copies to emit; zero or negative yields an empty string.

println(std.fmt.repeat_str("ab", 3)) // ababab

fn to_hex(value: int) -> string#

Formats an integer in hexadecimal.

value: Number to render in base 16.

println(std.fmt.to_hex(255)) // ff
println(std.fmt.to_oct(64))  // 100
println(std.fmt.to_bin(5))   // 101

fn to_bin(value: int) -> string#

Formats an integer in binary.

value: Number to render in base 2.

fn to_oct(value: int) -> string#

Formats an integer in octal.

value: Number to render in base 8.

fn join_with(items: [string], separator: string) -> string#

Joins strings with the supplied separator.

items: Pieces to concatenate, in order.
separator: Value placed between consecutive pieces.

println(std.fmt.join_with(["a", "b", "c"], ", ")) // a, b, c

fn surround(text: string, wrapper: string) -> string#

Wraps text with the supplied string.

text: Text to wrap.
wrapper: Value placed on both sides.

println(std.fmt.surround("title", "**")) // **title**

fn quote(text: string) -> string#

Wraps text in double quotes.

text: Text to wrap; embedded quotes are not escaped.

println(std.fmt.quote("moon"))     // "moon"
println(std.fmt.parenthesize("x")) // (x)
println(std.fmt.bracket("x"))      // [x]
println(std.fmt.brace("x"))        // {x}

fn parenthesize(text: string) -> string#

Wraps text in parentheses.

text: Text to wrap.

fn bracket(text: string) -> string#

Wraps text in square brackets.

text: Text to wrap.

fn brace(text: string) -> string#

Wraps text in braces.

text: Text to wrap.

fn indent(text: string, count: int) -> string#

Indents every line by the requested number of spaces.

text: Text whose every line is shifted.
count: How many spaces to prefix each line with.

println(std.fmt.indent("one\ntwo", 4))
//     one
//     two

extern fn format(spec: string, ...) -> string#

Formats heterogeneous arguments according to a format specification.

spec: Format string; the arguments after it fill its placeholders in order.

println(std.fmt.format("{} scored {}", "ada", 95)) // ada scored 95
println(std.fmt.format("{:08x}", 42))              // 0000002a
println(std.fmt.format("{:.2}", 3.14159))          // 3.14
println(std.fmt.format("{1} then {0}", "a", "b"))  // b then a

extern fn format_float(value: float, digits: int) -> string#

Formats a number with exactly digits decimal places, clamped to 0..64.

value: Number to render.
digits: Decimal places to emit, clamped to 0..64.

println(std.fmt.format_float(3.14159, 2)) // 3.14
println(std.fmt.format_float(2.0, 0))     // 2
println(std.fmt.float(1.0 / 3.0, 4))      // 0.3333 — same formatter, shorter name

extern fn float(value: float, digits: int) -> string#

The shorter spelling for format_float. float is a primitive-type keyword and is declarable as a function name; this is a second real declaration, not a dispatch alias.

value: Number to render.
digits: Decimal places to emit, clamped to 0..64.

fn int_base(value: int, base: int, width: int) -> string#

Integer formatting in base 2..36, zero-padding digits after the sign.

value: Number to render; a negative value keeps its - sign.
base: Radix from 2 to 36, using lowercase digits.
width: Minimum digit count, zero-padded after the sign.

println(std.fmt.int_base(255, 16, 4)) // 00ff
println(std.fmt.int_base(-5, 2, 8))   // -00000101

fn format_bytes(value: int) -> string#

A byte count for a person to read: 512B, 1.5KB, 2.3MB, 1TB.

Binary units (1024), because the thing being counted is nearly always memory or a file. Below 1 KB the exact count is printed with no scaling — rounding 900 bytes to 0.9KB loses the only precision that mattered — and the scale stops at TB rather than inventing units nobody reads.

value: Byte count to scale; below 1 KB it is printed exactly.

println(std.fmt.format_bytes(512))              // 512B
println(std.fmt.format_bytes(1536))             // 1.5KB
println(std.fmt.format_bytes(10 * 1024 * 1024)) // 10MB

fn format_ms(value: float) -> string#

A duration in milliseconds for a person to read: 7.5ms, 250ms, 1.2s.

One unit step only. A duration long enough to want minutes is one a caller should be formatting deliberately, not one a log line should be guessing at.

value: Duration in milliseconds.

println(std.fmt.format_ms(7.5))    // 7.5ms
println(std.fmt.format_ms(250.0))  // 250ms
println(std.fmt.format_ms(1234.0)) // 1.2s