string.format
Lua function

string.format

Summary

Formats a string

Prototype

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


Description

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.



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)


See Also ...

Topics

DOC_lua_base Lua base functions
DOC_lua_bc Lua bc (big number) functions
DOC_lua_bit Lua bit manipulation functions
DOC_lua_coroutines Lua coroutine functions
DOC_lua_debug Lua debug functions
DOC_lua_io Lua io functions
DOC_lua_lpeg Lua LPEG library
DOC_lua_math Lua math functions
DOC_lua_os Lua os functions
DOC_lua_package Lua package functions
DOC_lua_rex Lua PCRE regular expression functions
DOC_lua Lua script extensions
DOC_lua_string Lua string functions
DOC_lua_tables Lua table functions
DOC_lua_utils Lua utilities
DOC_regexp Regular Expressions
DOC_scripting Scripting

Lua functions

LUA_string.byte string.byte (Converts a character into its ASCII (decimal) equivalent)
LUA_string.char string.char (Converts ASCII codes into their equivalent characters)
LUA_string.dump string.dump (Converts a function into binary)
LUA_string.find string.find (Searches a string for a pattern)
LUA_string.gfind string.gfind (Iterate over a string (obsolete in Lua 5.1))
LUA_string.gmatch string.gmatch (Iterate over a string)
LUA_string.gsub string.gsub (Substitute strings inside another string)
LUA_string.len string.len (Return the length of a string)
LUA_string.lower string.lower (Converts a string to lower-case)
LUA_string.match string.match (Searches a string for a pattern)
LUA_string.rep string.rep (Returns repeated copies of a string)
LUA_string.reverse string.reverse (Reverses the order of characters in a string)
LUA_string.sub string.sub (Returns a substring of a string)
LUA_string.upper string.upper (Converts a string to upper-case)

(Help topic: lua=string.format)

DOC_contents Documentation contents page