There may come a time when you need to output a number with specific formatting, such as displaying a value like 3.1415926 with only two decimal places. Or perhaps you need to lay out a table and produce column data, like a leaderboard. This is where string.format() comes into play. Using this, you can provide a format string plus a series of values to format and the API will return a single string formatted to your specifications.
The format string (the first parameter to string.format()) can contain text and format codes which produce the desired output string. Let's look at a simple example:
string.format( "Bill made $%6.2f dollars at the yard sale.", 11.25017 )
Within the format string, notice the format code of %6.2f. This directly coincides with the second parameter, 11.25017, and if we output this code to the console it will appear as this:
Bill made $ 11.25 dollars at the yard sale.
Let's inspect the format code of %6.2f in further detail.
In all places within the format string where you want to output a formatted value, begin with a percent sign (%).
Following this, the 6 parameter instructs the method to use 6 total characters to output the value.
Next, .2 indicates the number of decimal places to include after the decimal, in this case 2, commonly used to specify monetary values.
Finally, the f parameter indicates a Lua "conversion specifier," in this case a floating point number, most of which behave just like those in the family of C/C++ printf functions.
In the example above, the number only occupied 5 of the allotted 6 characters, so the string is padded with spaces. By default, spaces will be added to the left in order to simulate right justification, because numbers are often right justified. However, when outputting alphabetical values like names, you'll usually want them to be standard (left) justified. To accomplish this, simply use a minus sign (-) as part of the format code:
string.format( "%-20s %-10d.", "Albert Einstein", "29314" )
If we output this code, it will appear like this:
Albert Einstein 29314 .
In this output, carefully observe the "placeholder" spaces. Because we specified 20 total places for the string Albert Einstein- sign, 5 placeholder spaces will be output before the next part of the output string (29314). Similarly, since we specified 10 total places for the string 29314, 5 placeholder spaces will be output before the end of the .)
The string.format() API can also be used to format numbers such as high scores, in which you might want to include leading zeros:
string.format( "%07d", 1050 )
This will result in a value of 0001050 because we specified 0 (to pad the value with leading zeros) and we indicated 7 total spaces for the formatted output.
As noted above, you can use various "conversion specifiers" in the format string, including:
| Specifier | Output |
|---|---|
s |
|
d |
|
f |
Basically, aside from a few exceptions, Lua's string.format() API uses the same parameters as those in the family of C/C++ printf functions.
As you can see, the string.format() API is very powerful and it can be used to format strings for text display or UI needs, among other tasks. It may require some experimentation to accomplish the exact formatting that you desire, but with a little testing, you can format a string in virtually any manner necessary.