# LLM Prompt for Documentation ## Documentation ### Array2D #### Array2D **Type Annotation** **Description** 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 **Type Annotation** ```roc {} -> Array2D * ``` **Description** Return an empty array with 0 rows, 0 columns, and no elements. #### identity **Type Annotation** ```roc U64 -> Array2D (Num *) ``` **Description** Return an [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix) with the specified number of `1`s along the diagonal. #### repeat **Type Annotation** ```roc a, Shape2D -> Array2D a ``` **Description** Create an array with the same value repeated for each element. #### init **Type Annotation** ```roc Shape2D, (Index2D -> a) -> Array2D a ``` **Description** Create an array of given `Shape`, populating elements via an init function. #### initWithList **Type Annotation** ```roc List a, Shape2D, (Result a [Empty], Index2D -> b) -> Array2D b ``` **Description** 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 **Type Annotation** ```roc List (List a), Shape2D, (Result a [Empty], Index2D -> b) -> Array2D b ``` **Description** 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 **Type Annotation** ```roc List a, [ Fit, Fill a Shape2D ] -> Array2D a ``` **Description** 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 **Type Annotation** ```roc List (List a), [ FitShortest, FitLongest a, Fill a Shape2D ] -> Array2D a ``` **Description** 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 **Type Annotation** ```roc List a, Shape2D -> Result (Array2D a) [ NotEnoughElements, TooManyElements ] ``` **Description** 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 **Type Annotation** ```roc List (List a) -> Result (Array2D a) [InconsistentRowLengths] ``` **Description** Create an array from a list of lists. If the row lists do not all have the same length then return `Err InconsistentRowLengths`. #### shape **Type Annotation** ```roc Array2D * -> Shape2D ``` **Description** Get the X/Y dimensions of an array. #### size **Type Annotation** ```roc Array2D * -> U64 ``` **Description** Get the total number of elements in an array. #### hasIndex **Type Annotation** ```roc Array2D *, Index2D -> Bool ``` **Description** Predicate to determine if an index is within the bounds of an array. #### isEmpty **Type Annotation** ```roc Array2D * -> Bool ``` **Description** Predicate to determine if an array has zero elements. An empty array will have at least one dimension of length 0. #### set **Type Annotation** ```roc Array2D a, Index2D, a -> Array2D a ``` **Description** Change the element at the given index. If the index is outside the bounds of the array, return the original array unmodified. #### get **Type Annotation** ```roc Array2D a, Index2D -> Result a [OutOfBounds] ``` **Description** Attempt to retrieve the array value at a given index. If the index is not within the array then return `Err OutOfBounds`. #### update **Type Annotation** ```roc Array2D a, Index2D, (a -> a) -> Array2D a ``` **Description** 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 **Type Annotation** ```roc Array2D a, Index2D, a -> { array : Array2D a, value : a } ``` **Description** 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 **Type Annotation** ```roc Array2D a, Index2D, Index2D -> Array2D a ``` **Description** Exchange elements at two array indices. If either index is out of bounds return the array unchanged. #### map **Type Annotation** ```roc Array2D a, (a -> b) -> Array2D b ``` **Description** Convert each element in the array to something new via a conversion function. Return a new array of the converted values. #### mapWithIndex **Type Annotation** ```roc Array2D a, (a, Index2D -> b) -> Array2D b ``` **Description** Similar to `Array2D.map`, also provide the index for each element. #### walk **Type Annotation** ```roc Array2D a, state, WalkOptions *, (state, a, Index2D -> state) -> state ``` **Description** 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](https://en.wikipedia.org/wiki/Row-_and_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 **Type Annotation** ```roc Array2D a, state, WalkOptions *, (state, a, Index2D -> [ Continue state, Break state ]) -> state ``` **Description** Similar to `Array2D.walk`, but the `step` function either continues walking with a `Continue`, or stops early with a `Break`. #### first **Type Annotation** ```roc Array2D a -> Result a [ArrayWasEmpty] ``` **Description** Return the first element in the array, or `Err ArrayWasEmpty` if the array was empty. #### last **Type Annotation** ```roc Array2D a -> Result a [ArrayWasEmpty] ``` **Description** Return the last element in the array, or `Err ArrayWasEmpty` if the array was empty. #### firstIndex **Type Annotation** ```roc Array2D * -> Result Index2D [ArrayWasEmpty] ``` **Description** Return the first index in the array, or `Err ArrayWasEmpty` if the array was empty. #### lastIndex **Type Annotation** ```roc Array2D * -> Result Index2D [ArrayWasEmpty] ``` **Description** Return the last index in the array, or `Err ArrayWasEmpty` if the array was empty. #### toList **Type Annotation** ```roc Array2D a -> List a ``` **Description** Convert an array to a flat list of elements. #### toLists **Type Annotation** ```roc Array2D a -> List (List a) ``` **Description** Convert an array to a list of lists, where each inner list is one array row. #### reshape **Type Annotation** ```roc Array2D a, a, Shape2D -> Array2D a ``` **Description** Change the shape of an array. Elements maintain [row-major order](https://en.wikipedia.org/wiki/Row-_and_column-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 **Type Annotation** ```roc Array2D a -> Array2D a ``` **Description** Take the [transpose](https://en.wikipedia.org/wiki/Transpose) of an array. This operation flips the array values along the diagonal. #### flipRows **Type Annotation** ```roc Array2D a -> Array2D a ``` **Description** 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 **Type Annotation** ```roc Array2D a -> Array2D a ``` **Description** 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 **Type Annotation** ```roc Array2D a -> Array2D a ``` **Description** Rotate every array element clockwise 90 degrees. This swaps the dimensions of the array. #### rotateCounterClockwise **Type Annotation** ```roc Array2D a -> Array2D a ``` **Description** Rotate every array element counter-clockwise 90 degrees. This swaps the dimensions of the array. #### countIf **Type Annotation** ```roc Array2D a, (a -> Bool) -> U64 ``` **Description** Run the given function on each element of an array and return the number of elements for which the function returned Bool.true. #### findFirstIndex **Type Annotation** ```roc Array2D a, (a -> Bool) -> Result Index2D [NotFound] ``` **Description** Return the index of the first element in the array satisfying a predicate function. If no satisfying element is found return `Err NotFound`. #### findLastIndex **Type Annotation** ```roc Array2D a, (a -> Bool) -> Result Index2D [NotFound] ``` **Description** Return the index of the last element in the array satisfying a predicate function. If no satisfying element is found return `Err NotFound`. #### joinWith **Type Annotation** ```roc Array2D Str, Str, Str -> Str ``` **Description** Concatenate an array of strings into a single string, interspersing each element with an element separator and each row with a row separator. #### subarray **Type Annotation** ```roc Array2D a, Index2D, Index2D -> Array2D a ``` **Description** 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 **Type Annotation** ```roc Array2D (Num a), Array2D (Num a) -> Result (Array2D (Num a)) [InnerDimensionsMismatch] ``` **Description** Perform [matrix multiplication](https://en.wikipedia.org/wiki/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`. ### Index2D #### Index2D **Type Annotation** **Description** Two-dimensional index for referencing elements in an `Array2D`. #### add **Type Annotation** ```roc Index2D, Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Add indices, returning a new index with the sum of the two `row` values and sum of the two `col` values as component parts. If the resulting index is not within the array shape then return `Err OutOfBounds`. #### sub **Type Annotation** ```roc Index2D, Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Subtract indices, returning a new index with the difference of the two `row` values and difference of the two `col` values as component parts. If the resulting index is not within the array shape then return `Err OutOfBounds`. #### incRow **Type Annotation** ```roc Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Go to the next row index within the array shape, wrapping to the next column when the end of a row is reached. If the next index is outside of the array shape then return `Err OutOfBounds`. #### incCol **Type Annotation** ```roc Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Go to the next column index within the array shape, wrapping to the next row when the end of a column is reached. If the next index is outside of the array shape then return `Err OutOfBounds`. #### decRow **Type Annotation** ```roc Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Go to the previous row index within the array shape, wrapping to the previous column when the start of a row is reached. If the next index is outside of the array shape then return `Err OutOfBounds`. #### decCol **Type Annotation** ```roc Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Go to the previous column index within the array shape, wrapping to the previous row when the start of a column is reached. If the next index is outside of the array shape then return `Err OutOfBounds`. #### adjacentTo **Type Annotation** ```roc Index2D, Shape2D, [ PrevRow, SameRow, NextRow ], [ PrevCol, SameCol, NextCol ] -> Result Index2D [OutOfBounds] ``` **Description** Try to get an index adjacent to the current index. If the specified adjacent index is outside of the array shape then return `Err OutOfBounds`. Note that `adjacent index shape SameRow SameCol` will return `Ok index`. #### allAdjacentTo **Type Annotation** ```roc Index2D, Shape2D -> List Index2D ``` **Description** List all indices adjacent to the given index and within the array shape. The list will contain 0 to 8 indices, and will not include the given index. #### flipRow **Type Annotation** ```roc Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Change the `row` component of the index, reflecting over the center row or rows. This swaps the first row with the last row, second row with second to last row, etc. #### flipCol **Type Annotation** ```roc Index2D, Shape2D -> Result Index2D [OutOfBounds] ``` **Description** Change the `col` component of the index, reflecting over the center column or columns. This swaps the first column with the last column, second column with second to last column, etc. #### transpose **Type Annotation** ```roc Index2D -> Index2D ``` **Description** Get the [transpose](https://en.wikipedia.org/wiki/Transpose) for an index. Swaps the `row` and `col` index components, reflecting the index over the center diagonal line. This operation is independent of array shape, since transposing an array also changes its shape. #### first **Type Annotation** ```roc Shape2D -> Result Index2D [ShapeWasEmpty] ``` **Description** The first index within the given array shape. If the shape is for an empty array then return `Err ShapeWasEmpty`. #### last **Type Annotation** ```roc Shape2D -> Result Index2D [ShapeWasEmpty] ``` **Description** The last index within the given array shape. If the shape is for an empty array then return `Err ShapeWasEmpty`. #### isRowStart **Type Annotation** ```roc Index2D -> Bool ``` **Description** Predicate to determine if an index is the first index in a row. #### isColStart **Type Annotation** ```roc Index2D -> Bool ``` **Description** Predicate to determine if an index is the first index in a column. #### isRowEnd **Type Annotation** ```roc Index2D, Shape2D -> Bool ``` **Description** Predicate to determine if an index is the last index in a row for a given array shape. #### isColEnd **Type Annotation** ```roc Index2D, Shape2D -> Bool ``` **Description** Predicate to determine if an index is the last index in a column for a given array shape. ### Shape2D #### Shape2D **Type Annotation** **Description** Dimensions of an `Array2D` where `rows` is the total number of rows and `cols` is that total number of columns. #### isEmpty **Type Annotation** ```roc Shape2D -> Bool ``` **Description** Predicate to determine if an array shape can contain indices. When the shape has zero rows or zero columns then there is no index that can fall within the shape bounds. #### hasIndex **Type Annotation** ```roc Shape2D, Index2D -> Bool ``` **Description** Predicate to determine if an index is within the bounds of an array shape. #### size **Type Annotation** ```roc Shape2D -> U64 ``` **Description** Total number of elements within the array shape.