12.1 String Formatting🔗ℹ

> @str{1 + 2 = @(1 + 2)}

"1 + 2 = 3"

In the {} argument for str, use @ escapes with functions like str.f or repr to format non-strings values in ways other than the to_string default.

• If the string must be padded to make it at least min_width characters, then copies of the pad character are added. Padding is added to the end if align is #'left, to the start if align is #'right, and to both ends if align is #'center.

• If the string must be truncated to reduce it to max_width characters, the initial characters are preserved if clip_align is #'left, trailing characters are preserved if clip_align is #'right, and central character are preserved if clip_align is #'center.

> str.s("hello", ~width: 10)

"hello     "

> str.s("hello", ~width: 10, ~pad: Char"_", ~align: #'center)

"__hello___"

> str.s("hello", ~max_width: 2)

"he"

> str.s("hello", ~max_width: 2, ~clip_align: #'right)

"lo"

The min_width, max_width, pad, align, and clip_align arguments are used the same as by str.s.

The minus_sign, plus_sign, and zero_sign arguments determines how a sign is shown. By default, a sign is shown only for negative n.

The sign_align argument determines where the sign string is positioned relative to digits. A #'left or #'center value places the sign on the left, and #'right on the right. A #'left or #'right value further moves the sign to before or after any padding that is added to the number to make the result min_width characters, and it preserves the sign and clips digits, instead, when clipping characters to fit into max_width.

> str.d(-10)

"-10"

> str.x(-10)

"-a"

> str.d(-10, ~width: 8)

"-10     "

> str.d(-10, ~width: 8, ~align: #'right)

"     -10"

> str.d(-10, ~width: 8, ~align: #'right, ~sign_align: #'left)

"-     10"

> str.d(-123456, ~width: 4, ~align: #'right, ~sign_align: #'left)

"-456"

> str.d(10, ~plus_sign: "+")

"+10"

The str.f (“f” for “floating point”) function produces a string that uses a decimal point and precision subsequent digits. If precision is 0, then the decimal point is dropped unless keep_decimal is true. The decimal string is used to represent a decimal point.

The str.e (“e” for “exponent”) function produces a string that uses exponential notation indicated with exponent. The coefficient is written with a single digit before a decimal point, and the digit is always between 1 and 9 unless n is zero; precision digits are shown after the decimal point. An exponent is shown after exponent, and a sign is included for the exponent only if it is negative.

The str.g (“g” for “general”) function produces a string like str.f or str.e, depending on a relationship between precision and the exponent expo that would be written with str.e: if the exponent is at least -4 and less than precision, then str.f is used, otherwise str.g is used. When str.g uses str.f, it adjusts precision to precision - 1 - expo. When str.g uses str.e, it adjusts precision to precision-1. Since these adjustments only work in general when precision is positive, a precision of 0 passed to str.g is treated as 1.

> str.f(123.45)

"123.450000"

> str.f(2/3, ~precision: 2)

"0.67"

> str.e(2/3, ~precision: 2)

"6.67e-1"

> str.e(123.45e10, ~precision: 2)

"1.23e12"

> str.g(2/3, ~precision: 2)

"0.67"

> str.g(123.45e10, ~precision: 2)

"1.2e12"

> str.g(123.45e10, ~decimal: ",", ~exponent: "E")

"1,2345E12"