ParallelArray

Description

The ParallelArray is the central data structure around which River Trail programs are built. A ParallelArray can be created either from an existing array-like object (such as a JavaScript Array or another ParallelArray), or by using a comprehension, as shown in the examples below.

ParallelArrays are immutable: once created, they cannot be changed. Instead, operations such as map return a new ParallelArray.

Synopsis

ParallelArray();
ParallelArray(array);
ParallelArray(size, elementalFunction, arg1, arg2, ...); 
ParallelArray(constructor, array);
ParallelArray(element0, element1, ...); 
ParallelArray(canvas);

Arguments

ParallelArray objects can be created in a variety of ways, depending on the arguments passed to the ParallelArray constructor.

No arguments: When called with no arguments, the constructor returns a ParallelArray with no elements.
array: When called with an array argument, which can be any array-like object, and no other arguments, the constructor returns a new ParallelArray populated with the values in array.
size, elementalFunction, arg1, arg2, ...: When called with a size and an elementalFunction, and optional arguments arg1, arg2, etc., the constructor returns a ParallelArray of size size where each value is the result of calling elementalFunction with the index where its result goes and any remaining arg1, arg2, ... arguments. elementalFunction must be of Function type. If size is a number, then the index passed to the elemental function will be a number, as well. To support the creating of multi-dimensional arrays, size can be a vector. In that case, the index passed to the elemental function will be a vector, too.
constructor, array: When called with an argument constructor of type Function and an array-like object array, construct a new ParallelArray populated with the values in array, but using constructor as the constructor for the ParallelArray's internal data container. This form can be used to force a ParallelArray to internally represent its data as a typed array.
element0, element1, ...: When called with multiple array elements as arguments, the constructor returns a new ParallelArray populated with those elements.
canvas: When called with an HTML <canvas> object as argument, the constructor returns a new ParallelArray with shape [height, width, 4] where height and width are the height and width of the canvas in pixels, and the third dimension represents the 4-byte RGBA value for each pixel.

Discussion

To create a ParallelArray whose first element is a function, one must use the elemental function form and have the elemental function return the function.

To create a ParallelArray with a single element that is an Array, one must use the elemental function form with a size of 1 and return the array from the elemental function.

Returns

A freshly minted ParallelArray.

Examples

// create an empty ParallelArray with shape 0
var pa0 = new ParallelArray();

// create a ParallelArray out of a nested JS array, with shape [3, 2]
var pa1 = new ParallelArray([ [0,1], [2,3], [4,5] ]);

// create a ParallelArray from another ParallelArray
var pa2 = new ParallelArray(pa1);

// create a nested ParallelArray with shape [2, 2] from two arrays
var pa3 = new ParallelArray([0,1], [2,3]);

// create a ParallelArray using the comprehension constructor with
// shape [3, 2]
var pa4 = new ParallelArray(3, function (i) { return [i, i+1]; });

// create a ParallelArray with a shape vector with shape [3, 2]
var pa5 = new ParallelArray([3,2], function (iv) { return iv[0] * iv[1]; });

// create a ParallelArray from a canvas element
var pa6 = new ParallelArray(document.createElement("canvas"));

Methods

The following prototype methods on the Array object are also implemented for ParallelArray:

IntelLabs/RiverTrail