A three-dimensional array based on a rectangular sequential array
Example:
var o = new polygonal.ds.Array3<String>(3, 3, 3);
o.forEach(function(_, x, y, z) return '$x,$y,$z');
trace(o); //outputs:
[ Array3 cols=3 rows=3 depth=3
layer=0
0 -> 0,0,0 | 1,0,0 | 2,0,0
1 -> 0,1,0 | 1,1,0 | 2,1,0
2 -> 0,2,0 | 1,2,0 | 2,2,0
layer=1
0 -> 0,0,1 | 1,0,1 | 2,0,1
1 -> 0,1,1 | 1,1,1 | 2,1,1
2 -> 0,2,1 | 1,2,1 | 2,2,1
layer=2
0 -> 0,0,2 | 1,0,2 | 2,0,2
1 -> 0,1,2 | 1,1,2 | 2,1,2
2 -> 0,2,2 | 1,2,2 | 2,2,2
]
Constructor
new (width:Int, height:Int, depth:Int, ?source:Array<T>)
Creates a three-dimensional array with dimensions width
, height
and depth
.
The minimum size is 2x2x2.
Parameters:
source | initial values for populating this three-dimensional array;
|
---|
Variables
read onlykey:Int = HashKey.next()
A unique identifier for this object.
A hash table transforms this key into an index of an array element by using a hash function.
reuseIterator:Bool = false
If true, reuses the iterator object instead of allocating a new one when calling this.iterator()
.
The default is false.
If this value is true, nested iterations will fail as only one iteration is allowed at a time.
read onlysize:Int
Methods
inlinecellOf (val:T, out:Array3Cell):Array3Cell
Returns the cell coordinates of the first occurrence of val
or null if val
does not exist.
Parameters:
out | stores the result. |
---|
Returns:
a reference to out
.
inlinecellToIndex (cell:Array3Cell):Int
Computes an array index into the linear array from the cell
coordinates.
clear (gc:Bool = false):Void
Clears this three-dimensional array by nullifying all elements.
The gc
parameter has no effect.
clone (byRef:Bool = true, ?copier:T ‑> T):Collection<T>
Creates and returns a shallow copy (structure only - default) or deep copy (structure & elements) of this three-dimensional array.
If byRef
is true, primitive elements are copied by value whereas objects are copied by reference.
If byRef
is false, the copier
function is used for copying elements. If omitted, clone()
is called on each element assuming all elements implement Cloneable
.
forEach (f:T ‑> Int ‑> Int ‑> Int ‑> T, z:Int = -1):Array3<T>
Calls f
on all elements.
The function signature is: f(input, x, y, z):output
- input: element at (x,y,z)
- x: current x index
- y: current y index
- z: current z index
- output: element to be stored at (x,y,z)
free ():Void
Destroys this object by explicitly nullifying all elements for GC'ing used resources.
Improves GC efficiency/performance (optional).
inlinegetAtCell (cell:Array3Cell):T
Returns the element that is stored in column cell.x
, row cell.y
and layer cell.z
.
getCol (z:Int, x:Int, out:Array<T>):Array<T>
Copies all elements stored in column x
and layer z
by reference to the out
array.
Parameters:
out | stores the result. |
---|
Returns:
a reference to the out
array.
inlinegetIndex (x:Int, y:Int, z:Int):Int
Computes an index into the linear array from the x
, y
and z
index.
getLayer (z:Int, out:Array2<T>):Array2<T>
Copies all elements stored in layer z
by reference into a two-dimensional array.
Parameters:
out | stores the "slice" of this three-dimensional array. |
---|
Returns:
a reference to out
.
getPile (x:Int, y:Int, out:Array<T>):Array<T>
Copies all elements stored in the pile at column x
and row y
by reference to the out
array.
Parameters:
out | stores the result. |
---|
Returns:
a reference to the out
array.
getRow (z:Int, y:Int, out:Array<T>):Array<T>
Copies all elements stored in row y
and layer z
by reference to the out
array.
Parameters:
out | stores the result. |
---|
Returns:
a reference to the out
array.
inlinegetStorage ():NativeArray<T>
Grants access to the rectangular sequential array storing the elements of this three-dimensional array.
Useful for fast iteration or low-level operations.
indexOf (val:T):Int
Returns the index of the first occurrence of val
or returns -1 if val
does not exist.
The index is in the range [0, this.size
- 1].
inlineindexToCell (i:Int, out:Array3Cell):Array3Cell
Transforms the index i
into out
coordinates.
Parameters:
out | stores the result. |
---|
Returns:
a reference to out
.
iterator ():Itr<T>
Returns a new Array3Iterator object to iterate over all elements contained in this three-dimensional array.
Order: Row-major order (layer-by-layer, row-by-row).
See:
remove (val:T):Bool
Nullifies all occurrences of val
.
The size is not altered.
Returns:
true if at least one occurrence of val
is nullified.
resize (width:Int, height:Int, depth:Int):Array3<T>
Resizes this three-dimensional array.
Parameters:
width | the new width (minimum is 2). |
---|---|
height | the new height (minimum is 2). |
depth | the new depth (minimum is 2). |
inlineset (x:Int, y:Int, z:Int, val:T):Array3<T>
Replaces the element at column x
, row y
and layer z
with val
.
setCol (z:Int, x:Int, input:Array<T>):Array3<T>
Overwrites all elements in column x
and layer z
with the elements stored in the input
array.
setPile (x:Int, y:Int, input:Array<T>):Array3<T>
Overwrites all elements in column x
and row y
with the elements stored in the input
array.
setRow (z:Int, y:Int, input:Array<T>):Array3<T>
Overwrites all elements in row y
and layer z
with the elements stored in the input
array.
shuffle (?rvals:Array<Float>):Array3<T>
Shuffles the elements of this collection by using the Fisher-Yates algorithm.
Parameters:
rvals | a list of random double values in the interval [0, 1) defining the new positions of the elements.
If omitted, random values are generated on-the-fly by calling |
---|
inlineswap (x0:Int, y0:Int, z0:Int, x1:Int, y1:Int, z1:Int):Array3<T>
Swaps the element at column/row/layer x0
, y0
, z0
with the element at column/row/layer x1
, y1
, z1
.
toArray ():Array<T>
Returns an array containing all elements in this three-dimensional array.
Order: Row-major order (layer-by-layer, row-by-row).