Plan: 0.5.0 Array Access Functions

This is a planning document for the 0.5.0 Array Access Functions feature. The described feature is in flux and probably will be different from the final implementation, but any feedback is welcome and will be used to further evolve the feature.

High-Level Description

In order to support extracted controls, Maxim has an array variable type that contains multiple values of a specific type. However, currently these values are entirely opaque to Maxim code itself, as values can only be taken out/put in by extractor controls. This feature proposes a set of functions to allow creating/modifying array values.

First, a quick explanation of how arrays are structured: arrays contain 32 values and a 32-bit bitmap. Each bit in the bitmap specifies if the array contains a value at that index (i.e if the value at the index is 'active').

New Globals

The following globals are proposed:

MAX_ARRAY_SIZE: num = 32

New Functions

The following functions are proposed:

numArray() -> num[]                          Creates a number array with no active values
midiArray() -> midi[]                        Creates a MIDI array with no active values
has<T>(arr: T[], index: num) -> num          Returns 1 if the value at the index was active, else 0. The index is wrapped around.
get<T>(arr: T[], index: num) -> T            Returns the value at the index if it was active, else the type's identity value. The index is wrapped around.
countActive<T>(arr: T[]) -> num              Returns the number of active values in the array.
countFree<T>(arr: T[]) -> num                Returns the number of free (not active) values in the array.
set<T>(arr: T[], index: num, val: T) -> T[]  Returns a new array with the value placed at the index. The index is wrapped around.
delete<T>(arr: T[], index: num) -> T[]       Returns a new array with the value at the index no longer active. The index is wrapped around.
push<T>(arr: T[], val: T) -> T[]             Places the value at the first free position, if there is one.

Note that some of these are generic functions. This feature depends on the Generics feature.