array package

License

The array package is marked as Compatible, which means any game can use it.

This package contains 30 classes, all of them variations on a theme. You can create a densely packed fixed-size array of either 1, 2, or 3 dimensions, containing Lua numbers, booleans, signed/unsigned 8-, 16-, or 32-bit integers, or 32- or 64-bit floating point values.

Each variant takes up the minimum necessary memory to store its contents, and accesses are performed in O(1) time.

All of the above classes implement the following:

array1d = SubCritical.Construct("PackedArray1D", size) array2d = SubCritical.Construct("PackedArray2D", width, height) array3d = SubCritical.Construct("PackedArray3D", width, height, depth)

Create an array of the given type and dimensions.

value = array1d:Get(x) value = array2d:Get(x, y) value = array3d:Get(x, y, z)

Get the value currently stored at the given location. Unset values default to false or 0, depending on the array's type.

Coordinates start from 0, not 1.

If the given coordinates are outside the array's bounds, returns the border value (see below).

width = array1d:GetSize() width,height = array2d:GetSize() width,height,depth = array3d:GetSize()

Returns the dimensions of the array.

array1d:Set(value, x) array2d:Set(value, x, y) array3d:Set(value, x, y, z)

Change the value currently stored at the given location.

Coordinates start from 0, not 1.

border = array:GetBorder()

Return the value that will currently be returned if an access outside the bounds of the array is attempted.

array:SetBorder(border)

Change the value that will be returned if an access outside the bounds of the array is attempted. Valid values are nil or any number. The default is nil, and the number will not be clamped to the range of the array. (Boolean arrays still have number/nil border values.)

dumped = array:Dump()

Get the array's contents, in big-endian form and packed as tightly as possible, suitable for serialization.

array:Undump(dumped)

Fill the array with a string we got from a previous call to Dump. The string must be exactly the right length, or an error will be thrown.

Here are some examples:

-- Create a PackedArray containing a 32x32 quarter-circle.
array = SubCritical.Construct("PackedArray2D_B", 32, 32)
for x=0,31 do
  for y=0,31 do
    array:Set(math.sqrt(x*x+y*y) <= 31, x, y)
  end
end

-- Create a PackedArray containing a multiplication table.
-- array[x][y] contains (x+1)*(y+1).
-- 12 * 12 = 144, which is less than 256, so our numbers will fit in a U8.
array = SubCritical.Construct("PackedArray2D_U8", 12, 12)
for x=1,12 do
  for y=1,12 do
    array:Set(x*y, x-1, y-1)
  end
end

Back to index