String.format

Available since: Gideros 2011.6
Class: string

Description

Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string).

The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported and that there is an extra option, q.

The q option formats a string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. For instance, the call

string.format('%q', 'a string with "quotes" and \n new line')

will produce the string:

"a string with \"quotes\" and \
new line"`

The options c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument, whereas q and s expect a string.

This function does not accept string values containing embedded zeros, except as arguments to the q option.

string.format(formatstring,e1,e2,...)

Parameters

formatstring: (string) the string defining the format of the output
e1: (string) first parameter for the format string optional
e2: (string) second parameter to format string optional
...: (multiple) more optional parameters for format string optional

Examples

Format an hexadecimal (0xRRGGBB) color to a string "0xRRGGBB"

local mycolor = 0x0000ff -- your color in hexadecimal format

-- prints "0x" as regular string, then add converted hex number with 6 leading zeros
local mycolorstring = string.format("0x%06x",mycolor) --> "0x0000ff"
-- or
local mycolorstring = ("0x%06x"):format(mycolor) --> "0x0000ff"

-- converts to hex number only
local mycolorstring2 = string.format("%x",mycolor) --> "ff"
-- or
local mycolorstring2 = ("%x"):format(mycolor) --> "ff"