string.format

s = string.format (fstr, v1, v2, v3, ...)

Formats the supplied values (v1, v2 etc.) using format string 'fstr', similar to the C function printf.

It is an error to supply too few variables for the format string.

The format string comprises literal text, and directives starting with %. Each directive controls the format of the next argument. Directives can include flags, width and precision controls. To literally incorporate "%" in the output you need to put "%%" in the format string.

For example:

print (string.format ("To wield the %s you need to be level %i", "sword", 10))

Prints:

To wield the sword you need to be level 10

In this example the values "sword" and "10" are substituted where the %s and %i appear in the format string.

Important! If you are using string.format in MUSHclient, and inside "send to script" in a trigger or alias, then the % sign has special meaning there (it is used to identify wildcards, such as %1 is wildcard 1). Thus the % signs in string.format need to be doubled or they won't work properly.

For example:

print (string.format ("To wield the %%s you need to be level %%i", "sword", 10))

This does not apply if you are using a separate script file.

---

Directives can be:

• %c - convert a number to a single character (like string.char)

  
  string.format ("%c", 65) --> A
  

• %d and %i - output as an integer number

  
  string.format ("%i", 123.456) --> 123
  

• %o - convert to octal

  
  string.format ("%o", 16) --> 20
  

• %u - convert to an unsigned number
  
  Negative numbers will be converted to 4294967296 (2^32) minus the number.

  
  string.format ("%u", 1234.566) --> 1234
  string.format ("%u", -1234)    --> 4294966062
  

• %x - hex (lower-case)

  
  string.format ("%x", 86543) --> 1520f
  

• %X - hex (upper-case)

  
  string.format ("%X", 86543)--> 1520F
  

• %e - scientific notation, "e" in lower case:

  
  string.format ("%e", 15) --> 1.500000e+001
  

• %E - scientific notation, "E" in upper case:

  
  string.format ("%E", 15) --> 1.500000E+001
  

• %f - floating point, default to 6 decimal places:

  
  string.format ("%f", 15.656e4) --> 156560.000000
  

• %g - Signed value printed in %f or %e format, whichever is more compact for the given value. To make it compact, only the required number of decimal places (if any) are shown.

  
  string.format ("%g", 15.656) --> 15.656
  string.format ("%g", 1)      --> 1
  string.format ("%g", 1.2)    --> 1.2
  

• %G - Same as %g except that an upper-case E is used where appropriate.

  
  string.format ("%G", 15.656e42) --> 1.5656E+043
  

• %q - formats a string in such a way Lua can read it back in (eg. as Lua source).
  
  Basically this means:
  • It puts a backslash in front of the double quote character (hex 22), backslash itself (hex 5C), and newline (hex 0A).
  • The nul character (hex 00) becomes \000
  • Carriage return (hex 0D) becomes \r
  The string itself is surrounded by double quotes.
  
  For example:

  
  print (string.format ("%q", 'a cat called "Puss"')) --> "a cat called \"Puss\""
  

• %s - output a string (or something that can be converted to a string, such as a number).
• %% - output a single % character

You can optionally supply 'flags width.precision' arguments before the letter.

---

Flags can be:

• - : left align result inside field
• + : always prefix with a sign, using + if field positive
• 0 : left-fill with zeroes rather than spaces
• (space) : If positive, put a space where the + would have been
• # : Changes the behaviour of various formats, as follows:
  For octal conversion (o), prefixes the number with 0 - if necessary.
  For hex conversion (x), prefixes the number with 0x
  For hex conversion (X), prefixes the number with 0X
  For e, E and f formats, always show the decimal point.
  For g and G format, always show the decimal point, and do not truncate trailing zeroes.
  The option to 'always show the decimal point' would only apply if you had the precision set to 0.

---

Width is the width of the returned field. If the converted number/string is wider than the width it is not truncated. Thus, this is effectively the minimum width. The maximum width you can specify is 99.

Decimal places are counted in the width, so something like %10.4f will actually have 5 digits before the decimal place. (5 before, plus 1 for the decimal point, plus 4 after adds up to 10).

You cannot use "*" as the width (as you can for printf). If you want variable-size strings you can simulate that by modifying the format string on-the-fly.

eg. instead of %*g, use "%" .. width .. "g"

---

Precision is the number of decimal places to show for floating-point numbers. The maximum precision you can specify is 99.

For strings the length of the source string is truncated to the precision size.

If the precision is omitted it defaults to 6 decimal places for 'e', 'E' and 'f' format types. If decimal places are omitted by the specified precision, the result is rounded.

---

Examples:

string.format ("%15.1f", 15.656)   --> '           15.7'
string.format ("%15.8f", 15.656)   --> '    15.65600000'
string.format ("%-15.1f", 15.656)  --> '15.7           '
string.format ("%015.1f", 15.656)  --> '0000000000015.7'
string.format ("%+015.1f", 15.656) --> '+000000000015.7
string.format ("%5s", "hi")          --> '   hi'
string.format ("%-5s", "hi")         --> 'hi   '
string.format ("%.4s", "Nick Gammon")--> 'Nick'  (truncation)
string.format ("%9.4s", "John Smith")--> '     John'
string.format ("%.f", 4.4)           --> '4'  (precision of zero)
string.format ("%.f", 4.5)           --> '5'  (rounding)
string.format ("%#.f", 4.4)          --> '4.' (decimal place forced)