Formatting and Converting Strings

Jun 17 2019, 4:50 PM PST

String formatting is used to convert variables into a user-friendly string of text. This is done through string.format(), a function which requires specific instructions in this pattern:

%[flags][width][.precision]specifier

Specifiers

The most important part of string formatting is the specifiers.

Specifier	Accepts	Outputs	Example Output
c	integer		3
d or i	integer	Decimal representation.	321
e or E	float	Scientific notation using e or E.	3.296e2 3.296E2
f	float		3231.1231
g or G	float	The shorter of e/E and f.	3E14 3e14
o	integer	Octal representation.	610
q	string	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, new lines, embedded zeros, and backslashes are correctly escaped.	"print(\"Hi\")"
s	string		Hello world!
u	integer	Decimal representation.	3131
x or X	integer	Hexadecimal representation.	7fa 7FA
%		% followed by another % will return the % sign itself.	%

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "The magic word is %s"
print(string.format(str, "Roblox"))
		
			The magic word is Roblox
		
			Copy Code
		
			Light Theme

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "The magic word is %q"
print(string.format(str, "Roblox"))
		
			The magic word is "Roblox"
		
			Copy Code
		
			Light Theme

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "Skip to \na new line and \nanother new line!"
print(string.format(str, "%q"))
		
			Skip to 
a new line and 
another new line!
		
			Copy Code
		
			Light Theme

Flags

Flag	Description
-	Left-justify the given field width (see Width below). Right justification is the default.
+	Forces a "+" sign to precede a number. Has no effect on negative numbers.
(space)	One blank space is inserted before a positive number, while negative numbers are unaffected. This is useful for making positive and negative numbers vertically align in a visual stacked list.
#	When used with o and x/X, writes a 0 (octal) or 0x/0X (hex) before values other than zero. When used with e/E and f, forces the output to contain a decimal point, even if no digits would follow (by default, no decimal point is written if no digits follow). When used with g or G, the result is the same as with e or E but trailing zeros are not removed.
0	Left-pads the number with zeros instead of empty spaces (see Width below).

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "%-10d"
print(string.format(str, 300) .. "]")
		
			300       ]  -- There are 7 spaces between '300' and ']'
		
			Copy Code
		
			Light Theme

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "%+i versus %+i"
print(string.format(str, 300, -300))
		
			+300 versus -300
		
			Copy Code
		
			Light Theme

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "There is a% i%% chance of rain in Seattle today."
print(string.format(str, 100))
		
			There is a 100% chance of rain in Seattle today.
		
			Copy Code
		
			Light Theme

Width

Width	Description
(number)	Minimum number of characters to return. If the number of characters to be formatted is less than this number, the result is padded with blank spaces.

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "%012i"
print("Score: " .. string.format(str, 15000))
		
			Score: 000000015000  -- 12 digits total, left-padded with zeros
		
			Copy Code
		
			Light Theme

Precision

Precision	Description
.(number)	For integer specifiers (d, i, o, u, x/X), precision specifies the minimum number of digits to be returned. If the value to be formatted is shorter than this number, the result is padded with leading zeros. A precision of 0 means that no character is written for the value 0. For e/E and f specifiers, this is the number of digits to be printed after the decimal point. For g/G specifiers, this is the maximum number of digits (before the e/E, if present). For s, this is the maximum number of characters to be returned. For c and q, this has no effect.

If no precision is specified, the default is 1. If the period is given without a value, 0 is assumed.

			
				Code Sample
			
				Expected Output
			
				Expand
				
			-- Add decimal with precision of 2 for a currency output
local str = "$%.2f"
print(string.format(str, 300))
		
			$300.00
		
			Copy Code
		
			Light Theme

			
				Code Sample
			
				Expected Output
			
				Expand
				
			-- Return first 6 letters of a string
local str = "%.6s"
print(string.format(str, "Robloxian"))
		
			Roblox
		
			Copy Code
		
			Light Theme

			
				Code Sample
			
				Expected Output
			
				Expand
				
			local str = "Once upon a time, there was a dragon named %s and it had %.8f horns."
print(string.format(str, "Pi", math.pi))
		
			Once upon a time, there was a dragon named Pi and it had 3.14159265 horns.
		
			Copy Code
		
			Light Theme

Tags:

strings
coding
reference
lua

Formatting and Converting Strings

Formatting and Converting Strings

Specifiers

Flags

Width

Precision

RELATED ARTICLES

Lua Style Guide

Using the Lua Debugger