Register forum user name Search FAQ

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.

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)


See Also ...

Lua functions

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

Topics

Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua LPEG library
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Regular Expressions
Scripting
Scripting callbacks - plugins

(Help topic: lua=string.format)

Documentation contents page


Search ...

Enter a search string to find matching documentation.

Search for:   

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.