Documentation

Array2D a

Fixed size two dimensional array. Unlike the builtin List data type Array2D is fully allocated on creation, with a starting element for each valid index.

empty : {} -> Array2D *

Return an empty array with 0 rows, 0 columns, and no elements.

identity : U64 -> Array2D (Num *)

Return an identity matrix with the specified number of 1s along the diagonal.

repeat : a, Shape2D -> Array2D a

Create an array with the same value repeated for each element.

init : Shape2D, (Index2D -> a) -> Array2D a

Create an array of given Shape, populating elements via an init function.

initWithList : List a, Shape2D, (Result a [Empty], Index2D -> b) -> Array2D b

Fill an array of the given Shape, populating elements via a starting list and an init function. If there are not enough list elements to fill the array then the init function is ran with Err Empty as the element.

initWithLists : List (List a), Shape2D, (Result a [Empty], Index2D -> b) -> Array2D b

Fill an array of the given Shape with elements from a list of lists, via an init function. Each inner list is used to populate one row of the Array2D. If there are not enough lists, or if there are not enough elements in a list to fill an array row, then the init function is ran with Err Empty as the element.

fromList : List a, [ Fit, Fill a Shape2D ] -> Array2D a

Create an array from a list. The strategy determines how the array is initialized:

• Fit - Return an array with 1 row and enough columns to exactly fitting the list elements.

• Fill default shape - Return an array of shape. If there are not enough list elements to fill the array then default is used for all remaining elements.

fromLists : List (List a), [ FitShortest, FitLongest a, Fill a Shape2D ] -> Array2D a

Create an array from a list of lists. The strategy determines how the array is initialized:

• FitShortest - Return an array where each list is a row. The array has columns equal to the number of elements in the shortest list. Any additional elements are dropped per row.

• FitLongest default - Return an array where each list is a row. The array has columns equal to the number of elements in the longest list. If there are not enough list elements to fill a row then default is used for all remaining values.

• Fill default shape - Return an array of shape. If there are not enough lists or not enough elements in a list to fill a row then default is used for all remaining values.

fromExactList : List a, Shape2D -> Result (Array2D a) [ NotEnoughElements, TooManyElements ]

Create an array of given Shape, populating elements via a starting list. If the list does not have enough elements to fill the array then return Err NotEnoughElements. If the list has more elements than the size of the array then return Err TooManyElements.

fromExactLists : List (List a) -> Result (Array2D a) [InconsistentRowLengths]

Create an array from a list of lists. If the row lists do not all have the same length then return Err InconsistentRowLengths.

shape : Array2D * -> Shape2D

Get the X/Y dimensions of an array.

size : Array2D * -> U64

Get the total number of elements in an array.

hasIndex : Array2D *, Index2D -> Bool

Predicate to determine if an index is within the bounds of an array.

isEmpty : Array2D * -> Bool

Predicate to determine if an array has zero elements. An empty array will have at least one dimension of length 0.

set : Array2D a, Index2D, a -> Array2D a

Change the element at the given index. If the index is outside the bounds of the array, return the original array unmodified.

get : Array2D a, Index2D -> Result a [OutOfBounds]

Attempt to retrieve the array value at a given index. If the index is not within the array then return Err OutOfBounds.

update : Array2D a, Index2D, (a -> a) -> Array2D a

Update the value at the given index with the given function. If the index is outside the bounds of the array, return the original array unmodified.

replace : Array2D a, Index2D, a -> { array : Array2D a, value : a }

Update the value at the given index, returning the new array and the replaced value. If the index is outside the bounds of the array, return the original array unmodified and the intended replacement value as value.

swap : Array2D a, Index2D, Index2D -> Array2D a

Exchange elements at two array indices. If either index is out of bounds return the array unchanged.

map : Array2D a, (a -> b) -> Array2D b

Convert each element in the array to something new via a conversion function. Return a new array of the converted values.

mapWithIndex : Array2D a, (a, Index2D -> b) -> Array2D b

Similar to Array2D.map, also provide the index for each element.

walk : Array2D a, state, WalkOptions *, (state, a, Index2D -> state) -> state

Build a value using each element in the array.

Starting with a given state value, walk through the array elements in the order specified by the options record, running a given step function to produce a new state.

Options:

• direction - Required, Forwards to traverse elements from the first index to the last index, Backwards to go from the last index to the first index.

• orientation - Optional, defaults to Rows. Determines if elements are visited in row-major or column-major order.

• start - Optional, defaults to the first index for Forwards and the last index for Backwards. The index to start walking from. If the start index is outside of the array bounds then either no elements will be walked Forwards, or all elements will be walked Backwards.

walkUntil : Array2D a, state, WalkOptions *, (state, a, Index2D -> [ Continue state, Break state ]) -> state

Similar to Array2D.walk, but the step function either continues walking with a Continue, or stops early with a Break.

first : Array2D a -> Result a [ArrayWasEmpty]

Return the first element in the array, or Err ArrayWasEmpty if the array was empty.

last : Array2D a -> Result a [ArrayWasEmpty]

Return the last element in the array, or Err ArrayWasEmpty if the array was empty.

firstIndex : Array2D * -> Result Index2D [ArrayWasEmpty]

Return the first index in the array, or Err ArrayWasEmpty if the array was empty.

lastIndex : Array2D * -> Result Index2D [ArrayWasEmpty]

Return the last index in the array, or Err ArrayWasEmpty if the array was empty.

toList : Array2D a -> List a

Convert an array to a flat list of elements.

toLists : Array2D a -> List (List a)

Convert an array to a list of lists, where each inner list is one array row.

reshape : Array2D a, a, Shape2D -> Array2D a

Change the shape of an array. Elements maintain row-major order but might be wrapped onto a new row by the change in dimensions. If the new array size is smaller then elements at the end will be truncated. If the new array size is larger then new elements will be set to the given default value.

transpose : Array2D a -> Array2D a

Take the transpose of an array. This operation flips the array values along the diagonal.

flipRows : Array2D a -> Array2D a

Swap the position of each element so that their row component changes and col component stays the same. This exchanges the top row of the array with the bottom row, the second row with the second to last row, etc.

flipCols : Array2D a -> Array2D a

Swap the position of each element so that their col component changes and row component stays the same. This exchanges the first element of each row with the last element of the row, the second element with the second to last element, etc.

rotateClockwise : Array2D a -> Array2D a

Rotate every array element clockwise 90 degrees. This swaps the dimensions of the array.

rotateCounterClockwise : Array2D a -> Array2D a

Rotate every array element counter-clockwise 90 degrees. This swaps the dimensions of the array.

countIf : Array2D a, (a -> Bool) -> U64

Run the given function on each element of an array and return the number of elements for which the function returned Bool.true.

findFirstIndex : Array2D a, (a -> Bool) -> Result Index2D [NotFound]

Return the index of the first element in the array satisfying a predicate function. If no satisfying element is found return Err NotFound.

findLastIndex : Array2D a, (a -> Bool) -> Result Index2D [NotFound]

Return the index of the last element in the array satisfying a predicate function. If no satisfying element is found return Err NotFound.

joinWith : Array2D Str, Str, Str -> Str

Concatenate an array of strings into a single string, interspersing each element with an element separator and each row with a row separator.

subarray : Array2D a, Index2D, Index2D -> Array2D a

Create a new array containing elements from a rectangular area within the given array. The firstCorner and secondCorner indices can specify any two corners of the subarray area.

mul : Array2D (Num a), Array2D (Num a) -> Result (Array2D (Num a)) [InnerDimensionsMismatch]

Perform matrix multiplication on two arrays. A prerequisite of this operation is that the number of columns in the first array must match the number of rows in the second array. If this doesn't hold then return Err InnerDimensionsMismatch.