Extensions Static Array

Package: array

The Static Array extension is a C Module that provides a lower-level container for data similar to a C array, but still largely maintains the interface of standard Lua tables.  Static Arrays can be specified to contain different types of primitive data, such as bytes, shorts, integers, floats, or doubles.  Static Arrays pre-allocate space for a specific number of elements when they are created, and hold onto the same chunk of memory until they are either explicitly resized, or deleted.  Thus, data stored in a Static Array is not subject to the garbage collector, which is a major strength of Static Arrays in certain scenarios where large amounts of data in a fixed footprint are created and destroyed in a short time period.  Furthermore, because data types smaller than a double can be specified, and Static Arrays have no table entry overhead, Static Arrays can be much smaller than equivilent storage with tables for large data sets.

Static Arrays use 1-based indexes like Lua tables.  Indexes are bounds-checked.  All array elements are initialized to 0.

Member Functions

Any array objects created will contain the following member functions, which must be used with Lua's colon operator (:).

number at()
array clone()
void destroy()
number dimensions()
number dimSize()
void reset()
void resize()
void set()
number size()

Creating a Static Array

The static function array.new() will create a new static array object, given one or more dimension sizes, and optionally a type parameter.  Static Arrays created without a type parameter are automatically assigned the default Lua number type, "double".

Storage Types

The following table shows the storage types accepted as the type parameter in array.new().  Some of the names such as "long" and "int" are synonyms.

Type

Format

Size (bytes)

char signed integer 1
byte signed integer 1
short signed integer 2
int signed integer 4
long signed integer 4
float ieee single float 4
double ieee double float 8

Static Arrays as n-dimensional arrays

All Static Arrays can be manipulated as 1D arrays, but they do provide shortcuts to make manipulating multi-dimensional data easier.  The new and resize functions can take any number of size arguments, where each argument is the size of one of the dimensions.  The functions at and set are provided to access data using multi-dimensional indexes, whereas the square bracket array syntax still accesses the array as a single-dimensional structure, where the total size of the array is the size of all the dimension arguments multiplied together.  Data is stored in row-major order (that is, data elements are packed together starting with the right-most [or inner] dimension).

For example, if you execute the following code:

-- Create a 2x2x3 array (12 elements)
arr = array.new(2, 2, 3, "short")
 
-- Fill array with products of indexes
for i = 1, arr:dimSize(1) do
  for j = 1, arr:dimSize(2) do
    for k = 1, arr:dimSize(3) do
      arr:set(i, j, k, i * j * k)
    end
  end
end
 
-- Print out array linearly
for i = 1, #arr do
  print(arr[i])
end

Then the data will be printed in the following order:
1, 2, 3, 2, 4, 6, 2, 4, 6, 4, 8, 12

The grouping can be visualized below:
[ [ [1, 2, 3], [2, 4, 6] ],  [ [2, 4, 6], [4, 8, 12] ] ]

Unlike indexing with square brackets, multi-dimensional indexes are NOT bounds checked, and therefor overruning the bounds of one of the indexes may either fail, or return data from another part of the array.

Example

require "array"
 
-- Create an array of 1000 shorts (16-bit integers)
arr = array.new(1000, "short")
 
-- Fill array with sequential squares
for i = 1, arr:size() do
  arr[i] = i * i
end
 
-- Print values (note, we can also use Lua's # length
-- operator on these arrays too)
for i = 1, #arr do
  print(arr[i])
end
 
-- Reset array (reset all elements to 0)
arr:reset()
 
-- Resize array to half capacity
arr:resize(500)
 
-- When we're done, we can free memeory by destroying
-- the table.
arr:destroy()
 
-- Further attempts to use arr will have no effect

 

Copyright 2010 Justin Aquadro