• fmt vs.&
• Formatting strings
• Formatting floats
• Expressions
• Debugging strings
• Implementation details
• Standard format specifiers for strings, integers and floats
• Limitations
• Future directions
• Imports
• Types

  • StandardFormatSpecifier
• Procs

  alignString
  • alignString(s: string; minimumWidth: int; align = '\x00'; fill = ' '): string
  formatValue
  • formatValue(result: var string; value: SomeFloat; specifier: static string)
  • formatValue(result: var string; value: SomeFloat; specifier: string)
  • formatValue(result: var string; value: string; specifier: static string)
  • formatValue(result: var string; value: string; specifier: string)
  • formatValue[T: SomeInteger](result: var string; value: T; specifier: static string)
  • formatValue[T: SomeInteger](result: var string; value: T; specifier: string)
  parseStandardFormatSpecifier
  • parseStandardFormatSpecifier(s: string; start = 0; ignoreUnknownSuffix = false): StandardFormatSpecifier
• Templates

  &
  • `&`(pattern: string{lit}): string
  fmt
  • fmt(pattern: static string): untyped
  • fmt(pattern: static string; openChar: static char; closeChar: static char): string

Stringinterpolation /format inspired by Python's f-strings.

fmt vs.&

You can use eitherfmt or the unary& operator for formatting. The difference between them is subtle but important.

Thefmt"{expr}" syntax is more aesthetically pleasing, but it hides a small gotcha. The string is ageneralized raw string literal. This has some surprising effects:

Example:

importstd/strformatletmsg="hello"assertfmt"{msg}\n"=="hello\\n"

Because the literal is a raw string literal, the\n is not interpreted as an escape sequence.

There are multiple ways to get around this, including the use of the& operator:

Example:

importstd/strformatletmsg="hello"assert&"{msg}\n"=="hello\n"assertfmt"{msg}{'\n'}"=="hello\n"assertfmt("{msg}\n")=="hello\n"assert"{msg}\n".fmt=="hello\n"

Formatting strings

Example:

importstd/strformatassert&"""{"abc":>4}"""==" abc"assert&"""{"abc":<4}"""=="abc "

Formatting floats

Example:

importstd/strformatassertfmt"{-12345:08}"=="-0012345"assertfmt"{-1:3}"==" -1"assertfmt"{-1:03}"=="-01"assertfmt"{16:#X}"=="0x10"assertfmt"{123.456}"=="123.456"assertfmt"{123.456:>9.3f}"=="  123.456"assertfmt"{123.456:9.3f}"=="  123.456"assertfmt"{123.456:9.4f}"==" 123.4560"assertfmt"{123.456:>9.0f}"=="     123."assertfmt"{123.456:<9.4f}"=="123.4560 "assertfmt"{123.456:e}"=="1.234560e+02"assertfmt"{123.456:>13e}"==" 1.234560e+02"assertfmt"{123.456:13e}"==" 1.234560e+02"

Expressions

Example:

importstd/strformatletx=3.14assertfmt"{(if x!=0: 1.0/x else: 0):.5}"=="0.31847"assertfmt"""{(block:    var res: string    for i in 1..15:      res.add (if i mod 15 == 0: "FizzBuzz"        elif i mod 5 == 0: "Buzz"        elif i mod 3 == 0: "Fizz"        else: $i) & " "    res)}"""=="1 2 Fizz 4 Buzz Fizz 7 8 Fizz Buzz 11 Fizz 13 14 FizzBuzz "

Debugging strings

fmt"{expr=}" expands tofmt"expr={expr}" namely the text of the expression, an equal sign and the results of evaluated expression.

Example:

importstd/strformatassertfmt"{123.456=}"=="123.456=123.456"assertfmt"{123.456=:>9.3f}"=="123.456=  123.456"letx="hello"assertfmt"{x=}"=="x=hello"assertfmt"{x =}"=="x =hello"lety=3.1415926assertfmt"{y=:.2f}"==fmt"y={y:.2f}"assertfmt"{y=}"==fmt"y={y}"assertfmt"{y = : <8}"==fmt"y = 3.14159 "prochello(a:string,b:float):int=12assertfmt"{hello(x, y) = }"=="hello(x, y) = 12"assertfmt"{x.hello(y) = }"=="x.hello(y) = 12"assertfmt"{hello x, y = }"=="hello x, y = 12"

Example:

importstd/strformatletx="12"assertfmt"{x=}"=="x=12"assertfmt"{x =:}"=="x =12"assertfmt"{x =}"=="x =12"assertfmt"{x= :}"=="x= 12"assertfmt"{x= }"=="x= 12"assertfmt"{x = :}"=="x = 12"assertfmt"{x = }"=="x = 12"assertfmt"{x   =  :}"=="x   =  12"assertfmt"{x   =  }"=="x   =  12"

Implementation details

An expression like&"{key} is {value:arg} {{z}}" is transformed into:

vartemp=newStringOfCap(educatedCapGuess)temp.formatValue(key,"")temp.add(" is ")temp.formatValue(value,arg)temp.add(" {z}")temp

Parts of the string that are enclosed in the curly braces are interpreted as Nim code. To escape a{ or}, double it.

Within a curly expression, however,{,}, must be escaped with a backslash.

To enable evaluating Nim expressions within curlies, colons inside parentheses do not need to be escaped.

Example:

importstd/strformatletx="hello"assertfmt"""{ "\{(" & x & ")\}" }"""=="{(hello)}"assertfmt"""{{({ x })}}"""=="{(hello)}"assertfmt"""{ $(\{x:1,"world":2\}) }"""=="""[("hello", 1), ("world", 2)]"""

& delegates most of the work to an open overloaded set offormatValue procs. The required signature for a typeT that supports formatting is usuallyprocformatValue(result:varstring;x:T;specifier:string).

The subexpression after the colon (arg in&"{key} is {value:arg} {{z}}") is optional. It will be passed as the last argument toformatValue. When the colon with the subexpression it is left out, an empty string will be taken instead.

For strings and numeric types the optional argument is a so-called "standard format specifier".

Standard format specifiers for strings, integers and floats

The general form of a standard format specifier is:

[[fill]align][sign][#][0][minimumwidth][.precision][type]

The square brackets[] indicate an optional element.

The optionalalign flag can be one of the following:

<

Forces the field to be left-aligned within the available space. (This is the default for strings.)

>

Forces the field to be right-aligned within the available space. (This is the default for numbers.)

^

Forces the field to be centered within the available space.

Note that unless a minimum field width is defined, the field width will always be the same size as the data to fill it, so that the alignment option has no meaning in this case.

The optionalfill character defines the character to be used to pad the field to the minimum width. The fill character, if present, must be followed by an alignment flag.

Thesign option is only valid for numeric types, and can be one of the following:

If the# character is present, integers use the 'alternate form' for formatting. This means that binary, octal and hexadecimal output will be prefixed with0b,0o and0x, respectively.

width is a decimal integer defining the minimum field width. If not specified, then the field width will be determined by the content.

If the width field is preceded by a zero (0) character, this enables zero-padding.

Theprecision is a decimal number indicating how many digits should be displayed after the decimal point in a floating point conversion. For non-numeric types the field indicates the maximum field size - in other words, how many characters will be used from the field content. The precision is ignored for integer conversions.

Finally, thetype determines how the data should be presented.

The available integer presentation types are:

The available floating point presentation types are:

Limitations

Because of the well defined order how templates and macros are expanded, strformat cannot expand template arguments:

templatemyTemplate(arg:untyped):untyped=echo"arg is: ",argecho&"--- {arg} ---"letx="abc"myTemplate(x)

First the templatemyTemplate is expanded, where every identifierarg is substituted with its argument. Thearg inside the format string is not seen by this process, because it is part of a quoted string literal. It is not an identifier yet. Then the strformat macro creates thearg identifier from the string literal, an identifier that cannot be resolved anymore.

The workaround for this is to bind the template argument to a new local variable.

templatemyTemplate(arg:untyped):untyped=block:letarg1{.inject.}=argecho"arg is: ",arg1echo&"--- {arg1} ---"

The use of{.inject.} here is necessary again because of template expansion order and hygienic templates. But since we generally want to keep the hygiene ofmyTemplate, and we do not wantarg1 to be injected into the context wheremyTemplate is expanded, everything is wrapped in ablock.

Future directions

A curly expression with commas in it like{x,argA,argB} could be transformed toformatValue(result,x,argA,argB) in order to support formatters that do not need to parse a custom language within a custom language but instead prefer to use Nim's existing syntax. This would also help with readability, since there is only so much you can cram into single letter DSLs.