Formats a string
Formats the supplied values (v1, v2 etc.) using format string 'fstr', similar to the C function printf.
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.
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)
%d and %i - output as an integer number
%o - convert to octal
%u - convert to an unsigned number
Negative numbers will be converted to 4294967296 (2^32) minus the number.
%x - hex (lower-case)
%X - hex (upper-case)
%e - scientific notation, "e" in lower case:
%E - scientific notation, "E" in upper case:
%f - floating point, default to 6 decimal places:
%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.
%G - Same as %g except that an upper-case E is used where appropriate.
%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.
%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.
See Also ...
string.byte - Converts a character into its ASCII (decimal) equivalent
Lua base functions
(Help topic: lua=string.format)
Enter a search string to find matching documentation.
Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.
Gammon Software support
Forum RSS feed ( https://gammon.com.au/rss/forum.xml )