Standard library · Text

text/fmt

Imported as import "text/fmt" as fmt, its names are then fmt.…. Every signature below is the one the checker infers.

Text laid out and numbers spelled: a template with slots, padding by width, a float to so many places, thousands separated, a size in bytes, an ordinal, a table with its columns lined up.

A template's slots take their values from a list of strings, in order — {} the next one, {2} the third — and a slot may say how wide and which way: {:>8} right in eight, {:<8} left, {:^8} centred, {:0>8} padded with zeros, {1:*^10} the second value centred among stars. Anything that is not a string is made one first — show(x), fixed(x, 2), thousands(n) — so the template only ever places text, and the number is spelled by the function that knows how. {{ and }} are a brace. Widths count characters, not bytes, so héllo is five.

fmt.text("{} has {:>6} items", Cons("cart", Cons(show(12), Nil)))   # => cart has     12 items
fmt.fixed(3.14159, 2)              # => 3.14
fmt.thousands(1234567)             # => 1,234,567
fmt.bytes(1536)                    # => 1.5 KB
fmt.ordinal(22)                    # => 22nd
fmt.table(Cons(Cons("a", Cons("bb", Nil)), Cons(Cons("ccc", Cons("d", Nil)), Nil)))   # => a    bb\nccc  d

Functions

fn text(template: Str, args: List(Str)) -> Str

fmt.text("{} and {}", Cons("a", Cons("b", Nil)))       # => a and b
fmt.text("{1} before {0}", Cons("a", Cons("b", Nil)))  # => b before a
fmt.text("[{:^7}]", Cons("mid", Nil))                  # => [  mid  ]
fmt.text("{:0>5}", Cons("42", Nil))                    # => 00042
fmt.text("{{literal}}", Nil)                          # => {literal}

fn pad_left(s: Str, width: Int) -> Str

fmt.pad_left("héllo", 7)   # =>   héllo

fn pad_right(s: Str, width: Int) -> Str

fmt.pad_right("ab", 4) + "|"   # => ab  |

fn center(s: Str, width: Int) -> Str

fmt.center("ab", 5) + "|"   # =>  ab  |

fn pad_left_with(s: Str, width: Int, fill: Str) -> Str

fmt.pad_left_with("7", 3, "0")   # => 007

fn pad_right_with(s: Str, width: Int, fill: Str) -> Str

fmt.pad_right_with("ab", 5, ".")   # => ab...

fn center_with(s: Str, width: Int, fill: Str) -> Str

The extra space goes to the right when it does not split evenly.

fmt.center_with("ab", 7, "*")   # => **ab***

fn truncate(s: Str, width: Int) -> Str

The first width characters, and an ellipsis in place of the rest.

fmt.truncate("a long sentence", 6)   # => a lon…
fmt.truncate("short", 10)           # => short

fn fixed(x: Float, places: Int) -> Str

x to places decimal places, rounded half away from zero. Past what an integer can count — around 9e15 — the float's own spelling is used.

fmt.fixed(2.5, 0)       # => 3
fmt.fixed(-2.5, 0)       # => -3
fmt.fixed(3.0, 3)       # => 3.000

fn thousands(n: Int) -> Str

The number with a separator every three digits from the right.

fmt.thousands(-1234567)   # => -1,234,567
fmt.thousands(999)        # => 999

fn thousands_with(n: Int, sep: Str) -> Str

fmt.thousands_with(1234567, ".")   # => 1.234.567

fn zero_pad(n: Int, width: Int) -> Str

The number in width digits, zeros in front.

fmt.zero_pad(42, 5)   # => 00042

fn signed(n: Int) -> Str

+3, -3, 0.

fmt.signed(3)    # => +3
fmt.signed(0)    # => 0
fmt.signed(-3)   # => -3

fn percent(x: Float, places: Int) -> Str

x as a percentage: percent(0.125, 1) is 12.5%.

fmt.percent(0.125, 1)   # => 12.5%

fn radix(n: Int, base: Int) -> Str

In base 2 to 36, lowercase.

fmt.radix(255, 2)    # => 11111111
fmt.radix(255, 36)   # => 73

fn hex(n: Int) -> Str

fmt.hex(255)   # => ff

fn binary(n: Int) -> Str

fmt.binary(5)   # => 101

fn sci(x: Float, places: Int) -> Str

1.23e+05: a mantissa to places places and an exponent of at least two digits, as C prints one.

fmt.sci(123456.0, 2)   # => 1.23e+05
fmt.sci(0.00042, 1)    # => 4.2e-04

fn bytes(n: Int) -> Str

A count of bytes in the unit that fits, to one place: 1.5 KB, 3.0 MB.

fmt.bytes(512)        # => 512 B
fmt.bytes(1536)       # => 1.5 KB
fmt.bytes(3145728)    # => 3.0 MB

fn ordinal(n: Int) -> Str

1st, 2nd, 3rd, 4th, and 11th to 13th as English has them.

fmt.ordinal(1)    # => 1st
fmt.ordinal(12)   # => 12th
fmt.ordinal(23)   # => 23rd

fn plural(n: Int, word: Str) -> Str

1 file, 2 files; plural_with for a word that does not just take an s.

fmt.plural(1, "file")   # => 1 file
fmt.plural(2, "file")   # => 2 files

fn plural_with(n: Int, one: Str, many: Str) -> Str

fmt.plural_with(3, "child", "children")   # => 3 children

fn table(rows: List(List(Str))) -> Str

Rows of cells, each column padded to its widest cell and two spaces between columns; the last cell of a row is not padded.

fmt.table(Cons(Cons("name", Cons("size", Nil)), Cons(Cons("a.rill", Cons("12", Nil)), Nil)))   # => name    size\na.rill  12

fn table_with(rows: List(List(Str)), sep: Str) -> Str

fmt.table_with(Cons(Cons("a", Cons("b", Nil)), Nil), " | ")   # => a | b

Tests

• test_template_slots
• test_padding_counts_characters
• test_fixed_and_friends
• test_integers_spelled
• test_words
• test_table_lines_up