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, as intbl = { 15, 23, 75 }. Similarly, 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 astbl["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, like3 or 10000, and purely numeric values, then this document often refers to that table as an "array." The older topic Tables and Arrays in Mira Pro Script provides a similar discussion about the use of the term "array" as a special type of table in Mira.

The Mira script library contains groups of table functions that support tables of the following types:

Arrays containing only explicit or implicit integral keys (indices) and values that are numbers;
Arrays that are 1-dimensional;
Arrays that are multi-dimensional, defined as having dimension > 1 (the table contains at least one table);
General tables that may be multi-dimensional, with or without keys, with or without sub-tables, and contain numbers or other value types.

Table type 1 supported by a collection of Array Functions. Table types 2, 3, and 4 are supported by a collection of general Table Functions that support all types of table content. A table of greater than one dimension is defined as a table that contains one or more sub-tables. For example, the mean function works with a 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