Changes: Lua functions

Revision as of 11:07, 20 January 2012

== Ny'alotha: The dreaming city - General Val'jex < Commander of the Old > == Tactics - Boss information

This article or section includes speculation, observations or opinions possibly supported by lore or by Blizzard officials. It should not be taken as representing official lore.

This article is fan fiction.
The contents herein are entirely player made and in no way represent official Warcraft lore or history. The characters and events listed are of an independent nature and are applied for roleplaying purposes only.

@@ Line 1: / Line 1: @@
+== Ny'alotha: The dreaming city - General Val'jex < Commander of the Old > == Tactics - Boss information
-{{wowapi}}
-These are standard '''Lua functions''' available in most Lua parsers. Arguably, we could just refer to the [http://www.lua.org Lua web site], but a few functions differ slightly in Blizzard's implementation. They are all documented here for consistency.
+{{Speculation}}
-== Lua in the World of Warcraft API ==
+{{fanfic}}
-Note that the [[World of Warcraft API]] does ''not'' provide all standard Lua functions. Notably, operating system and file I/O libraries are not present.
-=== Lua Functions ===
-These functions are part of the Lua programming language (v5.1), described in the [http://www.lua.org/manual/5.1/manual.html Lua 5.1 Reference Manual].
-In addition to this list, see also [[World of Warcraft API#Debugging Functions|Debugging Functions]].
-: [[API assert|assert]](value[, errormsg]) - asserts a value evaluates to true. If it is, returns value, otherwise causes a Lua error to be thrown.
-: [[API collectgarbage|collectgarbage]]() - Forces garbage collection. (Added in 1.10.1)
-: [[API date|date]](format, time) - Returns the current date according to the user's machine.
-: [[API error|error]]("error message",level) - Throws an error with the given error message. Use pcall() (see below) to catch errors.
-: [[API gcinfo|gcinfo]]() - Returns the number of kB of add-on memory in use and the current garbage collection threshold (in kB). (Function gcinfo is deprecated; use collectgarbage("count") instead.<ref>http://www.lua.org/manual/5.1/manual.html</ref>)
-: [[API getfenv|getfenv]](function or integer) - Returns the table representing the stack frame of the given function or stack level.
-: [[API getmetatable|getmetatable]](obj, mtable) - Returns the metatable of the given table or userdata object.
-: [[API loadstring|loadstring]]("Lua code") - Parse the string as Lua code and return it as a function reference.
-: [[API next|next]](table, index) - Returns the next key, value pair of the table, allowing you to walk over the table.
-: [[API newproxy|newproxy]](boolean or proxy) - Creates a userdata with a sharable metatable.
-: [[API pcall|pcall]](func, arg1, arg2, ...) - Returns a boolean value indicating successful execution of func and the error message or func's results as additional values.
-: [[API select|select]](index, list) - Returns the number of items in '''list''' or the value of the item in '''list''' at '''index'''.
-: [[API setfenv|setfenv]](function or integer, table) - Sets the table representing the stack frame of the given function or stack level.
-: [[API setmetatable|setmetatable]](obj, mtable) - Sets the metatable of the given table or userdata object.
-: [[API time|time]](table) - Returns time in seconds since epoch (00:00:00 Jan 1 1970)
-: [[API type|type]](var) - Returns the type of variable as a string, "number", "string", "table", "function" or "userdata".
-: [[API unpack|unpack]](table[, start][, end]) - Returns the contents of its argument as separate values.
-: [[API xpcall|xpcall]](func, err) - Returns a boolean indicating successful execution of func and calls err on failure, additionally returning func's or err's results.
-=== Math Functions ===
-Most of these functions are shorthand references to the Lua math library (which is available via "math.", see [http://lua-users.org/wiki/MathLibraryTutorial MathLibraryTutorial] for more info).
-The trigonometry functions are not just references; they have degree&rarr;radian conversion wrappers. Blizzard's versions work with degrees. Lua's standard math library works with radians.
-: [[API abs|abs]](value) - Returns the absolute value of the number.
-: [[API acos|acos]](value) - Returns the arc cosine of the value in degrees.
-: [[API asin|asin]](value) - Returns the arc sine of the value in degrees.
-: [[API atan|atan]](value) - Returns the arc tangent of the value in degrees.
-: [[API atan2|atan2]](y, x) - Returns the arc tangent of Y/X in degrees.
-: [[API ceil|ceil]](value) - Returns the ceiling of value.
-: [[API cos|cos]](degrees) - Returns the cosine of the degree value.
-: [[API deg|deg]](radians) - Returns the degree equivalent of the radian value.
-: [[API exp|exp]](value) - Returns the exponent of value.
-: [[API floor|floor]](value) - Returns the floor of value.
-: [[API fmod|fmod]](value,modulus) - Returns the remainder of the division of value by modulus that rounds the quotient towards zero.
-: [[API frexp|frexp]](num) - Extract mantissa and exponent from a floating point number.
-: [[API ldexp|ldexp]](value, exponent) - Load exponent of a floating point number.
-: [[API log|log]](value) - Returns the natural logarithm (log base e) of value.
-: [[API log10|log10]](value) - Returns the base-10 logarithm of value.
-: [[API max|max]](value[, values...]) - Returns the numeric maximum of the input values.
-: [[API min|min]](value[,values...]) - Returns the numeric minimum of the input values.
-: [[API mod|mod]](value,modulus) - Returns floating point modulus of value. (Function math.mod was renamed math.fmod)
-: [[API rad|rad]](degrees) - Returns the radian equivalent of the degree value.
-: [[API random|random]]([ [lower,] upper]) - Returns a random number (optionally bounded integer value)
-: [[API sin|sin]](degrees) - Returns the sine of the degree value.
-: [[API sqrt|sqrt]](value) - Return the square root of value.
-: [[API tan|tan]](degrees) - Returns the tangent of the degree value.
-=== String Functions ===
-These string functions are shorthand references to the Lua string library (which is available via "string.", see [http://lua-users.org/wiki/StringLibraryTutorial StringLibraryTutorial] for more info),
-: [[API format|format]](formatstring[, value[, ...]]) - Return a formatted string using values passed in.
-: [[API gsub|gsub]](string,pattern,replacement[, limitCount]) - Globally substitute pattern for replacement in string.
-: [[API strbyte|strbyte]](string[, index]) - Returns the internal numeric code of the i-th character of string
-: [[API strchar|strchar]](asciiCode[, ...]) - Returns a string with length equal to number of arguments, with each character assigned the internal code for that argument.
-: [[API strfind|strfind]](string, pattern[, initpos[, plain]]) - Look for match of pattern in string, optionally from specific location or using plain substring.
-: [[API strlen|strlen]](string) - Return length of the string.
-: [[API strlower|strlower]](string) - Return string with all upper case changed to lower case.
-: [[API strmatch|strmatch]](string, pattern[, initpos]) - Similar to strfind but only returns the matches, not the string positions.
-: [[API strrep|strrep]](seed,count) - Return a string which is count copies of seed.
-: [[API strrev|strrev]](string) - Reverses a string; alias of string.reverse.
-: [[API strsub|strsub]](string, index[, endIndex]) - Return a substring of string starting at index
-: [[API strupper|strupper]](string) - Return string with all lower case changed to upper case.
-: [[API tonumber|tonumber]](arg[, base]) - Return a number if arg can be converted to number. Optional argument specifies the base to interpret the numeral. Bases other than 10 accept only unsigned integers.
-: [[API tostring|tostring]](arg) - Convert arg to a string.
-These are custom string functions available in WoW but not normal Lua.
-: [[API strlenutf8|strlenutf8]](string) - Returns the number of characters in a UTF8-encoded string.
-: [[API strtrim|strtrim]](string[, chars]) - Trim leading and trailing spaces or the characters passed to chars from string.
-: [[API strsplit|strsplit]](delimiter, string) - Return a list of substrings separated by occurrences of the delimiter.
-: [[API strjoin|strjoin]](delimiter, string, string[, ...]) - Join string arguments into a single string, separated by delimiter.
-: [[API strconcat|strconcat]](...) - Returns a concatenation of all number/string arguments passed.
-: [[API tostringall|tostringall]](...) - Converts all arguments to strings and returns them in the same order that they were passed.
-=== Table Functions ===
-These table functions are shorthand references to the Lua table library (which is available via "table.", see [http://lua-users.org/wiki/TableLibraryTutorial TableLibraryTutorial] for more info).
-Be also aware that many table functions are designed to work with tables indexed only with numerical indexes, starting with 1 and without holes (like {[1] = "foo", [3] = "bar"} --- recognize that [2] will be nil in this table). When working with any other tables behavior is not defined and might lead to unexpected results. Not being aware of this fact is one major causes for bugs in code written in Lua.
-: [[API foreach|foreach]](table,function) - Execute function for each element in table. (deprecated, used pairs instead)
-: [[API foreachi|foreachi]](table,function) - Execute function for each element in table, indices are visited in sequential order. (deprecated, used ipairs instead)
-: [[API getn|getn]](table) - Return the size of the table when seen as a list. This is deprecated, it is replaced by the # operator. Instead of table.getn(table), use #(table).
-: [[API ipairs|ipairs]](table) - Returns an iterator of type integer to traverse a table.
-: [[API pairs|pairs]](table) - Returns an iterator to traverse a table.
-: [[API sort|sort]](table[, comp]) - Sort the elements in the table in-place, optionally using a custom comparator.
-: {{api|tContains}}(table, value) - returns true if value is contained within table. This is not standard Lua, but added by Blizzard.
-: [[API tinsert|tinsert]](table[, pos], value) - Insert value into the table at position pos (defaults to end of table)
-: [[API tremove|tremove]](table[, pos]) - Remove and return the table element at position pos (defaults to last entry in table)
-: [[API wipe|wipe]](table) - Restore the table to its initial value (like tab = {} without the garbage).  This is not standard Lua, but added by Blizzard.
-=== Bit Functions ===
-World of Warcraft includes the Lua bitlib library (available via the "bit" table) which provides access to bit manipulation operators. It has been available since [[Patch 1.9]]. This library seems to work internally with standard 32-bit 'int' values, since bit.lshift(0x80000000, 1) == 0
-: [[API bit.bnot|bit.bnot]](a) - binary 'not' - the one's complement of a
-: [[API bit.band|bit.band]](a1, ...) - binary 'and' - the bitwise and of the values
-: [[API bit.bor|bit.bor]](a1, ...) - binary 'or' - the bitwise or of the values
-: [[API bit.bxor|bit.bxor]](a1, ...) - bitwise 'xor' - the bitwise exclusive or of the values
-: [[API bit.lshift|bit.lshift]](a, n) - 'left shift' - a shifted left by n bits
-: [[API bit.rshift|bit.rshift]](a, n) - 'right shift' - a shifted right by n bits
-: [[API bit.arshift|bit.arshift]](a, n) - 'arithmetic right shift' - a shifted right arithmetically by n bits
-: [[API bit.mod|bit.mod]](a, n) - signed 'modulus' - the signed value of a modulo n (result is the same sign as a)
-Using these functions to pack data structures is fairly slow work. Unless you have a very large database and ''need'' to conserve memory, save your information in several, individual variables or table fields.
-=== Coroutine Functions ===
-Coroutine functions should be used sparingly because of the amount of memory they use.
-: [[API coroutine.create|coroutine.create]](f)
-: [[API coroutine.resume|coroutine.resume]](co [, val1, ...])
-: [[API coroutine.running|coroutine.running]]()
-: [[API coroutine.status|coroutine.status]](co)
-: [[API coroutine.wrap|coroutine.wrap]](f)
-: [[API coroutine.yield|coroutine.yield]](...)
-== Notes ==
-=== String Functions ===
-* All strings have their metatable set to index the global string table, so any string function may be called through it with the colon syntax:
- -- This...
- local s = string.format(input, arg1, arg2, ...)
- -- ...can be written as this
- local s = input:format(arg1, arg2, ...)  -- input gets passed as the first argument, replicating the above code, as per the colon syntax
-To make this work for string constants, you have to use parentheses. "%d":format(arg1) is not valid Lua code, you have to do
- ("%d"):format(arg1)
-Since this uses the string table, any function placed inside the string table works the same. The following is valid:
- function string.print(a)
-  return print(a)
- end
- ("test"):print()
-Though you should try to avoid populating the string table with your own functions.
-=== Table Functions ===
-* Any function that takes a table as its first argument can be assigned to a method in said table and used thusly.
-** There's no practical reason for doing this, but it's kinda fun to know these useless things.
-** '''Notice''' that [[API wipe|table.wipe]] (and [[API wipe|wipe]]) will remove itself and all other methods assigned in this manner.
- tab = {}
- -- this works, of course.
- tinsert(tab, 1, value) -- change the value at index 1 to value.
- -- as does this
- tab.insert = tinsert
- tab:insert(1, value) -- change the value at index 1 to value (note the ":").
-== See also ==
-* [[Lua]], which has plenty of links to other reference material.