Wiki
Clone wikiCore / string.format
Back to Beyond the Codea in-app reference
string.format (formatstring, ...) function
Introduction
The Lua version 5.1 reference documents most of the string.format(formatstring, ...)
function. The function returns a formatted version of its variable arguments following the description given in its first argument, which must be a string following the rules below.
Rules for formatstring
The format string can contain format specifiers that are replaced by the values specified in the other arguments, formatted as specified. The format specifiers have the form, where []
indicates an optional part:
%[flags][width][.precision]type
The type
part of the specifier is required:
type | Output | Examples |
---|---|---|
d or i | Signed decimal integer | 1234 |
u | Unsigned decimal integer | 1234 |
o | Unsigned octal | 2322 |
x | Unsigned hexadecimal integer (lowercase) | 4d2 |
X | Unsigned hexadecimal integer (uppercase) | 4D2 |
f | Decimal floating point | 1234.567749 |
e | Scientific notation (lowercase) | 1.234568e+03 |
E | Scientific notation (uppercase) | 1.234568E+03 |
g | Use the shortest representation: %e or %f | 1234.57 |
G | Use the shortest representation: %E or %f | 1234.57 |
c | Character | a |
s | String of characters | 1234.57, hello |
q | Formats a string in a form suitable to be safely read back by Lua: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. | |
% | %% will print a single % | % |
The optional flags
part of the format specifier:
flags | Explanation |
---|---|
- | Left-justify within the given width (see below). Right justification is the default. |
+ | Prefix positive numbers with a plus sign. |
(space) | Prefix positive numbers with a space. |
# | For o , x or X types, non-zero values are prefixed with 0 , 0x or 0X . For e , E , f , g or G types, it forces the output to contain a decimal point even if no more digits follow. By default, if no digits follow, no decimal point is written. |
0 | Left-pads the number with zeroes (0 ) instead of spaces when padding is specified (see width). |
The optional width
part of the format specifier is the minimum number of characters to be printed. If necessary, the result is padded with blank spaces but the result is not truncated if the result is larger.
The optional .precision
part of the format specifier is a number. .
is equivalent to .0
.
Type | Explanation of precision |
---|---|
d, i, o, u, x, X | The minimum number of digits to be written. If necessary, the result is padded with leading zeros. The value is not truncated even if the result is longer. A precision of 0 means that no character is written for the value 0. |
e, E, and f | The number of digits to be printed after the decimal point (6 by default). |
g and G | The maximum number of significant digits to be printed. |
s | The maximum number of characters to be printed. All are printed by default. |
Updated