WoW:API format: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
m (Added note on outputting a % character within the format string)
m (Move page script moved page API format to API format without leaving a redirect)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{:Lua/Libshortcut|format|string.format}}
{{wowlua}}
string.format(formatstring, e1, e2, ...)
Creates a formatted string from format and substitution parameters, similar to sprintf in C.


Create a formatted string from the format and arguments provided. This is similar to the printf("format",...) function in C. An additional option %q returns string in a format that can safely be read back by Lua interpreter (puts quotes around a string and escapes special characters), it has little or no use in addon programming, but used by World of Warcraft to preparse all strings before saving them between sessions.
local s = string.format(formatstring, e1, e2, ...)
local s = format(formatstring, e1, e2, ...)


* c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument.
== Parameters ==
* q and s expect a string.  
* formatstring - the format string
* ... - list of substitutions of any relevant type


  > = string.format("%s %q", "Hello", "Lua user!")   -- string and quoted string
=== Returns ===
* formatted string
 
== Details ==
Create a formatted string from the format and arguments provided. This is similar to the printf("format",...) function in C. An additional option %q returns string in a format that can safely be read back by Lua interpreter (puts quotes around a string and escapes special characters), but used by World of Warcraft to preparse all strings before saving them between sessions. Lua supports the following subset of the C format specifiers, plus Lua specific 'q'
 
=== Substitution escapes ===
* c, d, E, e, f, g, G, i, o, u, X, x (expect a number as argument)
* q, s (expect a string as argument)
* % (escape char, to produce % use %%)
 
=== Examples ===
String and quoted string
  string.format("%s %q", "Hello", "Lua user!")
  Hello "Lua user!"
  Hello "Lua user!"
  > = string.format("%c%c%c", 76,117,97)             -- char
Char
  string.format("%c%c%c", 76,117,97)
  Lua
  Lua
  > = string.format("%e, %E", math.pi,math.pi)       -- exponent
Exponent
  string.format("%e, %E", math.pi, math.pi)  
  3.141593e+000, 3.141593E+000
  3.141593e+000, 3.141593E+000
  > = string.format("%f, %g, %.2f", math.pi, math.pi, math.pi)       -- float and compact float
Float and compact float
  string.format("%f, %g, %.2f", math.pi, math.pi, math.pi)  
  3.141593, 3.14159, 3.14
  3.141593, 3.14159, 3.14
  > = string.format("%d, %i, %u", -100,-100,-100)   -- signed, signed, unsigned integer
Signed, signed, unsigned integer
  string.format("%d, %i, %u", -100,-100,-100)  
  -100, -100, 4294967196
  -100, -100, 4294967196
  > = string.format("%o, %x, %X", -100,-100,-100)   -- octal, hex, hex
Octal, hex, hex
  string.format("%o, %x, %X", -100,-100,-100)
  37777777634, ffffff9c, FFFFFF9C
  37777777634, ffffff9c, FFFFFF9C
<br>


Note: if you want a % character to be output as part of your format string, you need to enter %%. ie.
Note: if you want a % character to be output as part of your format string, you need to enter %%
  > = string.format("Ratio is %u %%",12)
  string.format("Ratio is %u %%",12)
  Ratio is 12 %
  Ratio is 12 %


<br>
==== Macro Example ====
==== Macro Example ====
This macro prints out the time remaining on the Polymorph debuff in seconds, rounded to the nearest whole number:
This macro prints out the time remaining on the Polymorph debuff in seconds, rounded to the nearest whole number:
<pre>
/run for i=1,40 do local n,_,_,_,_,_,x,_,_=UnitDebuff("focus",i);if (n=="Polymorph")or (n=="Polymorph(Pig)")or (n=="Polymorph(Turtle)")then SendChatMessage('''format("%.0f"''',-1*(GetTime()-x)).." secs left on "..UnitName("focus").."'s CC!","EMOTE");end end
/run for i=1,40 do local n,_,_,_,_,_,x,_,_=UnitDebuff("focus",i);if (n=="Polymorph")or (n=="Polymorph(Pig)")or (n=="Polymorph(Turtle)")then SendChatMessage('''format("%.0f"''',-1*(GetTime()-x)).." secs left on "..UnitName("focus").."'s CC!","EMOTE");end end  
</pre>


== External links ==
== External links ==
* http://www.gnu.org/software/libc/manual/html_node/Formatted-Output.html#Formatted-Output
* Lua string reference - https://www.lua.org/pil/20.html
 
* GCC printf format - http://www.gnu.org/software/libc/manual/html_node/Formatted-Output.html#Formatted-Output
{{LUA}}

Latest revision as of 04:45, 15 August 2023

WoW Lua

Creates a formatted string from format and substitution parameters, similar to sprintf in C.

local s = string.format(formatstring, e1, e2, ...)
local s = format(formatstring, e1, e2, ...)

Parameters[edit]

  • formatstring - the format string
  • ... - list of substitutions of any relevant type

Returns[edit]

  • formatted string

Details[edit]

Create a formatted string from the format and arguments provided. This is similar to the printf("format",...) function in C. An additional option %q returns string in a format that can safely be read back by Lua interpreter (puts quotes around a string and escapes special characters), but used by World of Warcraft to preparse all strings before saving them between sessions. Lua supports the following subset of the C format specifiers, plus Lua specific 'q'

Substitution escapes[edit]

  • c, d, E, e, f, g, G, i, o, u, X, x (expect a number as argument)
  • q, s (expect a string as argument)
  • % (escape char, to produce % use %%)

Examples[edit]

String and quoted string

string.format("%s %q", "Hello", "Lua user!")
Hello "Lua user!"

Char

string.format("%c%c%c", 76,117,97)
Lua

Exponent

string.format("%e, %E", math.pi, math.pi) 
3.141593e+000, 3.141593E+000

Float and compact float

string.format("%f, %g, %.2f", math.pi, math.pi, math.pi) 
3.141593, 3.14159, 3.14

Signed, signed, unsigned integer

string.format("%d, %i, %u", -100,-100,-100) 
-100, -100, 4294967196

Octal, hex, hex

string.format("%o, %x, %X", -100,-100,-100)
37777777634, ffffff9c, FFFFFF9C

Note: if you want a % character to be output as part of your format string, you need to enter %%

string.format("Ratio is %u %%",12)
Ratio is 12 %

Macro Example[edit]

This macro prints out the time remaining on the Polymorph debuff in seconds, rounded to the nearest whole number:

/run for i=1,40 do local n,_,_,_,_,_,x,_,_=UnitDebuff("focus",i);if (n=="Polymorph")or (n=="Polymorph(Pig)")or (n=="Polymorph(Turtle)")then SendChatMessage(format("%.0f",-1*(GetTime()-x)).." secs left on "..UnitName("focus").."'s CC!","EMOTE");end end

External links[edit]