Table and Array Functions

Table Functions and Array Functions perform operations with data in a lua table or a CImage object. Several functions, including mean and sdev, also accept a variable length list of explicit numbers or string values that can be converted numbers. Also see the CStats class for class-based equivalents of several table functions All table and array functions are global (not class-based) and use lowercase names to distinguish them from class methods.

Lua tables are a collection of key-value pairs. The keys may be integral numeric indices ("subscripts"), like 15, or be explicitly named, like data. If the key is an integral numeric index, the table value can be specified explicitly using[], as in tbl[15] = 23, or implicitly as a member of a list, like tbl = { 15, 23, 75 }. Arrays using implicit indices begin with index 1. In the latter example, the value 23 would be accessed as tbl[2].

A table member with a named key, like data, may be specified explicitly using[], as in tbl["data"] = 23, or implicitly as a member of a list, as in tbl = { data=15, 23, 75 }. Notice that the named key must be quoted when enclosed in [], such as tbl["data"] but non-quoted when specified in a list, like { data=15 }. If a list does not contain a named key, then lua internally assigns it an integral key based on its sequential position in the table. If all table keys are integral indices, like 3 or10000, and purely numeric values, then this document often refers to that table as an "array." The older topic Tables and Arrays - Overview provides a similar discussion about the use of the term "array" in Mira as a special type of lua table.

The Mira script library contains groups of table functions that support data organized in various ways. The term "Table Type" used below is for explanatory purposes and is not part of the Lua language:

Types of Lua Tables used in the Mira Pro x64 Script Language

Table Type	Data in the Table	Associated Functions:
1	Arrays having explicit integral keys or hidden keys (integral indices) and values that are numbers. These must be a 1-dimensional table that does not contain a sub-table.	Array Functions. that support only indexed arrays.
2	Tables that are 1-dimensional but contain at least 1 non-integral key. These are by definition NOT arrays.	Generalized Table Functions that support all types of table content.
3	Multi-dimensional arrays, meaning that the table contains at least one sub-table.	Generalized Table Functions that support all types of table content.
4	General tables that may be multi-dimensional, with or without named keys, with or without sub-tables, and contain numbers or other value types. By definition, a table that contains a sub-table has a dimension greater than 1. The table functions also work with simple 1-dimensional arrays but are slightly slower than the array functions.	Generalized Table Functions that support all types of table content.

As an example, the mean function works only with a table of type 1, which is a simple 1-dimensional array, CImage object, or list of numbers. Conversely, its variant, the meann function, works with general tables that may include non-numeric values, named keys, and multiple dimensions. Table functions also work with 1-dimensional arrays.

Array Functions

These functions work with lua tables containing only values that are numbers, no keys, and no sub-tables. This special type of table is called an Array. Nearly all of these functions support only 1-dimensional arrays which, by definition, contain no sub-tables that add dimensions to the 1-dimensional array. However, the arraytoimage function supports 2-dimensional arrays. Most of these functions work with a CImage class object. Several also work with a CArray class object or a list of numbers.

Table Functions

These functions work with general multi-dimensional tables that contain sub-tables within the primary table. They also support tables with or without keys and with any type of values. Their names have an extra "n" appended to signify that they support table with higher dimensions. Most are generalizations of the Array Functions that support only 1-dimensional arrays. However, none of these functions support class objects or lists of numbers. Most functions perform some type of mathematical processing by selecting only the numeric values in the table.

Related Topics