| |
Tables and Arrays - Overview
The Mira Pro Script library provides a wealth of extensions to the lua language, many of which use lua tables. Since Mira is primarily designed for working with numeric data, class objects like CImage and non-class functions like mean work with lua tables that contain only values in the form of numbers. The Lua table construct is a general, versatile collection object that may contain values other than numbers, like strings, functions, key-named values, and even tables within the table. To distinguish between general lua tables that may contain nearly anything and tables that involve only numbers, this document often uses the term array to describe a lua table that contains only numbers. However, arrays may contain other arrays, making them a multi-dimensional array. Most class objects and non-class functions in the Mira script library use tables that are a 1-dimensional array with values that are numbers. However, there are also functions that work with generalized tables. These distinctions between table types are described below.
A lua table are explicitly declared in a script using the syntax tbl = {}, where the {} will contain a collection of key-value pairs. The keys may be string names or may be absent, in which case the array is accessed using integral indices beginning at 1. Numeric indices are integers, like 15, whereas named key are strings like "data" or data, depending on how it is used. Table values defined without a named key are explicitly accessed using [], as in tbl[15] = 23, or implicitly defined as a member of a list, as in tbl = { 15, 23, 75 }. Values using a named key, like "data" are explicitly defined like tbl["data"] = 15 or, in a list, like tbl = { data=15, 23, 75 }. Notice that the named key must be quoted when enclosed in [], such as tbl["data"] but not quoted when specified in a list, like { data=15 }. Numeric keys are not permitted, as in tbl = { 5=15, 23, 75 }, because this syntax conflicts with accessing table members using integral keys, as in tbl[5] = 15, which refers to the 5-th non-named element of table tbl. Note that some Mira functions and methods, like gaussdev and CImage:ColToTable create and return a table (actually, a 1-dimensional array), and the returned table should not be declared using {}.
Lua table members that include a value without a specified key are assigned an integral key based on their sequential position in the table. If all table keys are integral indices (except for sub-tables), like 3 or 10000, and all values in the table or sub-tables are numbers, then this table is called an array. Mira considers tables containing sub-tables to have a dimensionality greater than 1. A table containing no other tables is considered to have a dimension of 1. Most, though not all, Mira class methods and non-class functions use tables that are arrays with a dimension of 1. Exceptions are always noted.
The different types of tables supported by Mira Pro Script can be divided into the following groups:
So-called "arrays" that are tables containing only explicit or implicit integral keys (indices) and values that are numbers or can be converted to numbers;
Multi-dimensional tables or arrays that contain at least one sub-table;
General tables that may be multi-dimensional, with or without keys, with or without sub-tables, and contain numbers or other value types.
Most class objects, like CImage, CPlot, and non-class functions, like mean, pass or return a 1-dimensional array. However, some functions like arraytoimage() and CImage:RectToTable work with 2-dimensional arrays. Unless specified, you can normally assume a table is a 1-dimensional array of numbers.
Mira also provides numerous functions that work with general tables (type 3) and may parse the table to use only the numeric indices and values. These functions have a name ending with an extra "n", as in meann, which is the general table version of mean.
Mira Pro x64 Script User's Guide, v.8.73 Copyright Ⓒ 2024
Mirametrics, Inc. All Rights Reserved.