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.

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. 

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


  • %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. Basically this means it puts a backslash in front of the quote character, backslash itself, newline, and the nul character. The string itself is surrounded by quotes.

  • %s - output a string

  • %% - 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
  • # : For octal conversion (o), prefixes the number with 0
    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


Width is the width of the returned field. If the converted number/string is wider than the width it is not truncated.

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.


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 ("%5-s", "hi")         --> 'hi   '


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_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