ArrayND

Superclass: Array

ArrayND are N-dimensional Arrays whose slots may contain any Objects.
Their shape is fully described by the instance variable sizes [size1,size2,size3,...sizeN]. 
Each element can be adressed by N indices [index1,index2,index3,...indexN], 
where index ranges between 0 and size.
You have to supply sizes and indices as simple Arrays [a ,b ,c , ...] .
Remember that the first element is adressed per index 0!

Suggestions, bugs, improvements to sc.solar@studiobeige.de



Class Methods

*new(sizes)

Create a new ArrayND of shape (size1,size2,...sizeN)
Supply sizes as an Array like this [size1, size2, size3, . . .]

ArrayND.new([3,3,3]).postln;

*fill (sizes, function)

return an ArrayND of shape (size1,size2,...sizeN) by evaluating function.
function is passed one argument: indices 

*with (Array, sizes)

return an ArrayND of shape (size1,size2,...sizeN) by using the elements of array.


Instance Methods

indexAt (indices)

converts the multi-dimensional indices to simple one-dimensional index

indicesAt (index)

converts the simple one-dimensional index to multi-dimensional indices

isInRange (indices)

answers true if  the simple one-dimensional index or the multi-dimensional indices
are in range of the array

at (indices)

returns element at indices

wrapAt (indices)

returns element at indices wrapped to (0,sizeN-1)

getDiagonal ()

returns an ArrayND from the diagonal elements, 
the elements with all equal indices.

getSome ( dimensions, indices)

the mighty 'get everything you like' getSome.
In an Ndimensional Array you have to specify along which dimensions
you want to get something (e.g. a plane). Assuming a 3-dimensional
Array for now, there are 3 dimensions along which planes exist. The
[0,1], [1,2] and [0,2]-plane. With indices you supply the position of the plane.
The sizes of dimensions and indices added together has to equal the dimension of ArrayND.
In this example there is one index left to tell about the position.

(
var array;
array = ArrayND.new([3,3,3]);
array.size.do({arg i;array.put([i],i+1);});
array.postln;
array.getSome([0,1],[2]).postln;
)

You can get single lines up to hole ArrayNDs with getSome.
Getting single elements is done by setting dimensions to nil or [nil].
Although getting single elements is much faster using at(indices).

(
// getting an element, a line, a plane, a cube
var array;
array = ArrayND.new([3,3,3]);
array.size.do({arg i;array.put([i],i+1);});
//array.postln;
"getting one element".postln;
array.getSome(nil,[0,1,1]).postln;
"getting a line".postln;
array.getSome([0],[0,1]).postln;
"getting a plane".postln;
array.getSome([0,2],[0]).postln;
"getting a cube".postln;
array.getSome([0,1,2],nil).postln;
)

getLine ( dim, indices)

convenience wrapper using getSome

getRow ( indices )

convenience wrapper for Array2D support

getCol ( indices)

convenience wrapper for Array2D support

sizes
	or
shape

returns the shape of the ArrayND as [size1, size2, . . .]

postln

post the ArrayND as 2D representation.

ArrayND.new([3,3,3]).postln;

post

post the ArrayND as one row.

ArrayND.new([3,3,3]).post;

asArray

returns array as an Array(1D)

do (function)

evaluate function for each element.
function is passed two arguments: item, indices;
indices is an array containing the indices of item.

doSimple (function)

evaluate function for each element.
same as do, but function is passed two arguments: item,i
uses faster code.

doSome (dims, indices, function)

evaluate function for each element of the a subrange of array.
function is passed two arguments: item, indices;
See getSome for details.

doSomeSimple (dims, indices, function )

evaluate function for each element of a subrange of array.
function is passed two arguments: item, i;
See getSome and doSimple for details.

doLine ( dim, indices, function )

convenience wrapper using doSome

doRow ( indices, function )

convenience wrapper for Array2D support

doCol ( indices, function )

convenience wrapper for Array2D support

doLineSimple ( dim, indices, function )

convenience wrapper using doSome

doRowSimple ( indices, function )

convenience wrapper for Array2D support

doColSimple ( indices, function )

convenience wrapper for Array2D support



Shaping ArrayND:

flat

returns the ArrayND with all elements in one row

flatten (n)

returns the ArrayND with same number of elements but one dimension less.
The highest dimension sizeN is multiplied with next lower dimension

flattenTo (dim)

returns the ArrayND with same number of elements but one dimension less.
The highest dimension dimN is multiplied with dimension(dim)

reshape (shape)

returns ArrayND with same number of elements but with supplied shape.
size1*size2*size3... of  array must equal size1*size2*... of shape.
shape is an array of form [size1,size2,...]



Changing ArrayND:

put (indices, value)

put a single element at indices

wrapPut (indices, value)

put a single element at indices wrapped to (0,sizeN-1)

clipPut (indices, value)

put a single element at indices clipped to  (0,sizeN-1)

putSome ( dimensions, indices, some)

the mighty 'put everything you like' putSome.

(
// mighty putSome 
var array, some; 
some = ArrayND.fill([3,3],{0}).postln;
array = ArrayND.new([3,3,3]);
array.size.do({arg i;
array.put([i],i+1);
});
array.postln;
array.putSome([1,2],[2],some).postln;
)

(
// more mighty putSome
var array, some; 
some = ArrayND.fill([1,3],{0}).postln;
array = ArrayND.new([3,3]);
array.size.do({arg i;
array.put([i],i+1);
});
array.postln;
array.putSome([0],[0],some).postln;
)

See getSome for more details

putLine ( dim, indices, line)

convenience wrapper using putSome

putRow ( indices, row )

convenience wrapper for Array2D support

putCol ( indices, col)

convenience wrapper for Array2D support

fill (value)

fill the ArrayND with value.	


Return  new ArrayNDs:

flop (n)

flop results from array by  rotating the sizes.
[size1, size2, size3] --> [size2, size3, size1] --> [size3, size1, size2]--> [size1, size2, size3]
For N-dimensional ArrayND it takes n=N flops to get back to former array.
The diagonal elements stay the same .
Like transpose for Array2D.

collect (function)

returns a new ArrayND of same shape with function evaluated for each element.
function is passed two arguments: item, indices.

collectSimple (function)

returns a new ArrayND of same shape with function evaluated for each element.
function is passed two arguments: item, i.
See also doSimple.

collectSome (dims, indices, function)

returns a new ArrayND with function evaluated for each element of a subrange.
function is passed two arguments: item, indices.
See getSome  for details.

collectSomeSimple (dims, indices, function )

returns a new ArrayND with function evaluated for each element of a subrange.
function is passed two arguments: item, i.
See getSome and doSimple for details.

collectLine ( dim, indices, function )

convenience wrapper using collectSome

collectRow ( indices, function )

convenience wrapper for Array2D support

collectCol ( indices, function )

convenience wrapper for Array2D support

collectLineSimple ( dim, indices, function )

convenience wrapper using collectSome

collectRowSimple ( indices, function )

convenience wrapper for Array2D support

collectColSimple ( indices, function )

convenience wrapper for Array2D support

process (function)

returns the ArrayND  with function evaluated for each element.
changing the ArrayND itself rather than returning a new one (see collect for that)
function is passed two arguments: item, indices.

processSimple (function)

See process and collect above

processSome (dims, indices, function)

See process and collect above

processSomeSimple (dims, indices, function )

See process and collect above

processLine ( dim, indices, function )

convenience wrapper using collectSome

processRow ( indices, function )

convenience wrapper for Array2D support

processCol ( indices, function )

convenience wrapper for Array2D support

processLineSimple ( dim, indices, function )

convenience wrapper using collectSome

processRowSimple ( indices, function )

convenience wrapper for Array2D support

processColSimple ( indices, function )

convenience wrapper for Array2D support


sub (indices)

returns a new ArrayND of shape [size1-1,size2-1,...sizeN-1].
sub results from array by taking only those elements matching indices
in no item.

Operators:

== array2

returns true if array is identical to array2

==* array2

returns true if array has equal elements as array.
The shapes can be different.

+ array2

returns the sum for each element if array has same shape as array2

- array2

returns the subtraction for each element if array has same shape as array2

* number

returns the multiplication for each element with number.
number can be a scalar or a one-element array.
otherwise it returns the array back.

sumAll ()

returns the sum of all element 

mulElements ( array2 )

returns a new ArrayND where 
result.at(i) = array.at(i) * array2.at(i)
a multiplicaton for each element