Module pl.array2d
Operations on two-dimensional arrays.
See ???
The size of the arrays is determined by using the length operator `#` hence the module is not `nil` safe, and the usual precautions apply.
Note: all functions taking `i1,j1,i2,j2` as arguments will normalize the arguments using `default_range`.
Dependencies: `pl.utils`, `pl.tablex`, `pl.types`
Functions
| size (a) | return the row and column size. |
| column (j) | extract a column from the 2D array. |
| row (i) | extract a row from the 2D array. |
| map (f, arg) | map a function over a 2D array |
| reduce_rows (f) | reduce the rows using a function. |
| reduce_cols (f) | reduce the columns using a function. |
| reduce2 (opc, opr, a) | reduce a 2D array into a scalar, using two operations. |
| map2 (f, ad, bd, a, b, arg) | map a function over two arrays. |
| product (f) | cartesian product of two 1d arrays. |
| flatten (t) | flatten a 2D array. |
| reshape (nrows, co) | reshape a 2D array. |
| transpose (t) | transpose a 2D array. |
| swap_rows (i1, i2) | swap two rows of an array. |
| swap_cols (j1, j2) | swap two columns of an array. |
| extract_rows (ridx) | extract the specified rows. |
| extract_cols (cidx) | extract the specified columns. |
| remove_row (i) | remove a row from an array. |
| remove_col (j) | remove a column from an array. |
| parse_range (s) | parse a spreadsheet range or cell. |
| range (...) | get a slice of a 2D array. |
| default_range ([i1=1[, j1=1[, i2=N[, j2=M]]]]) | normalizes coordinates to valid positive entries and defaults. |
| slice ([i1=1[, j1=1[, i2=N[, j2=M]]]]) | get a slice of a 2D array. |
| set (value[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | set a specified range of an array to a value. |
| write (f, fmt[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | write a 2D array to a file. |
| forall (row_op, end_row_op[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | perform an operation for all values in a 2D array. |
| move (di, dj[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | move a block from the destination to the source. |
| iter (indices[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | iterate over all elements in a 2D array, with optional indices. |
| columns (a) | iterate over all columns. |
| rows (a) | iterate over all rows. |
| new (rows, cols, val) | new array of specified dimensions |
Functions
- size (a)
-
return the row and column size.
Size is calculated using the Lua length operator #, so usual precautions
regarding `nil` values apply.
Parameters:
- a
Returns:
- int number of rows (`#a`)
- int number of cols (`#a[1]`)
- column (j)
-
extract a column from the 2D array.
Parameters:
- j column index
Returns:
-
1d array
- row (i)
-
extract a row from the 2D array.
Added in line with `column`, for read-only purposes directly
accessing a[i] is more performant.
Parameters:
- i row index
Returns:
-
1d array (copy of the row)
- map (f, arg)
-
map a function over a 2D array
Parameters:
- f func a function of at least one argument
- arg an optional extra argument to be passed to the function.
Returns:
-
2d array
- reduce_rows (f)
-
reduce the rows using a function.
Parameters:
- f func a binary function
Returns:
-
1d array
See also:
- reduce_cols (f)
-
reduce the columns using a function.
Parameters:
- f func a binary function
Returns:
-
1d array
See also:
- reduce2 (opc, opr, a)
-
reduce a 2D array into a scalar, using two operations.
Parameters:
- opc func operation to reduce the final result
- opr func operation to reduce the rows
- a 2D array
- map2 (f, ad, bd, a, b, arg)
-
map a function over two arrays.
They can be both or either 2D arrays
Parameters:
- f func function of at least two arguments
- ad int order of first array (`1` if `a` is a list/array, `2` if it is a 2d array)
- bd int order of second array (`1` if `b` is a list/array, `2` if it is a 2d array)
- a tab 1d or 2d array
- b tab 1d or 2d array
- arg optional extra argument to pass to function
Returns:
-
2D array, unless both arrays are 1D
- product (f)
-
cartesian product of two 1d arrays.
Parameters:
- f func a function of 2 arguments
Returns:
-
2d table
Usage:
product('..',{1,2},{'a','b'}) == {{'1a','2a'},{'1b','2b'}}
- flatten (t)
-
flatten a 2D array.
(this goes over columns first.)
Parameters:
- t
Returns:
-
a 1d table
Usage:
flatten {{1,2},{3,4},{5,6}} == {1,2,3,4,5,6} - reshape (nrows, co)
-
reshape a 2D array. Reshape the aray by specifying a new nr of rows.
Parameters:
- nrows int new number of rows
- co bool use column-order (Fortran-style) (default false)
Returns:
-
a new 2d array
- transpose (t)
-
transpose a 2D array.
Parameters:
- t
Returns:
-
a new 2d array
- swap_rows (i1, i2)
-
swap two rows of an array.
Parameters:
- i1 int a row index
- i2 int a row index
Returns:
-
t (same, modified 2d array)
- swap_cols (j1, j2)
-
swap two columns of an array.
Parameters:
- j1 int a column index
- j2 int a column index
Returns:
-
t (same, modified 2d array)
- extract_rows (ridx)
-
extract the specified rows.
Parameters:
- ridx {int} a table of row indices
Returns:
-
a new 2d array with the extracted rows
- extract_cols (cidx)
-
extract the specified columns.
Parameters:
- cidx {int} a table of column indices
Returns:
-
a new 2d array with the extracted colums
- remove_row (i)
-
remove a row from an array.
Parameters:
- i int a row index
- remove_col (j)
-
remove a column from an array.
Parameters:
- j int a column index
- parse_range (s)
-
parse a spreadsheet range or cell.
The range/cell can be specified either as 'A1:B2' or 'R1C1:R2C2' or for
single cells as 'A1' or 'R1C1'.
Parameters:
- s string a range (case insensitive).
Returns:
- int start row
- int start col
- int end row (or `nil` if the range was a single cell)
- int end col (or `nil` if the range was a single cell)
- range (...)
-
get a slice of a 2D array.
Same as `slice`.
Parameters:
- ...
See also:
- default_range ([i1=1[, j1=1[, i2=N[, j2=M]]]])
-
normalizes coordinates to valid positive entries and defaults.
Negative indices will be counted from the end, too low, or too high
will be limited by the array sizes.
Parameters:
- i1 int or string start row or spreadsheet range passed to `parse_range` (default 1)
- j1 int start col (default 1)
- i2 int end row (default N)
- j2 int end col (default M)
Returns:
-
i1, j1, i2, j2
See also:
- slice ([i1=1[, j1=1[, i2=N[, j2=M]]]])
-
get a slice of a 2D array. Note that if the specified range has
a 1D result, the rank of the result will be 1.
Parameters:
- i1 int or string start row or spreadsheet range passed to `parse_range` (default 1)
- j1 int start col (default 1)
- i2 int end row (default N)
- j2 int end col (default M)
Returns:
-
an array, 2D in general but 1D in special cases.
See also:
- set (value[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
set a specified range of an array to a value.
Parameters:
- value the value (may be a function, called as `val(i,j)`)
- i1 int or string start row or spreadsheet range passed to `parse_range` (default 1)
- j1 int start col (default 1)
- i2 int end row (default N)
- j2 int end col (default M)
See also:
- write (f, fmt[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
write a 2D array to a file.
Parameters:
- f a file object (default stdout)
- fmt string a format string (default is just to use tostring)
- i1 int or string start row or spreadsheet range passed to `parse_range` (default 1)
- j1 int start col (default 1)
- i2 int end row (default N)
- j2 int end col (default M)
See also:
- forall (row_op, end_row_op[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
perform an operation for all values in a 2D array.
Parameters:
- row_op func function to call on each value; `row_op(row,j)`
- end_row_op func function to call at end of each row; `end_row_op(i)`
- i1 int or string start row or spreadsheet range passed to `parse_range` (default 1)
- j1 int start col (default 1)
- i2 int end row (default N)
- j2 int end col (default M)
See also:
- move (di, dj[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
move a block from the destination to the source.
Parameters:
- di int start row in dest
- dj int start col in dest
- i1 int or string start row or spreadsheet range passed to `parse_range` (default 1)
- j1 int start col (default 1)
- i2 int end row (default N)
- j2 int end col (default M)
See also:
- iter (indices[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
iterate over all elements in a 2D array, with optional indices.
Parameters:
- indices bool with indices (default false)
- i1 int or string start row or spreadsheet range passed to `parse_range` (default 1)
- j1 int start col (default 1)
- i2 int end row (default N)
- j2 int end col (default M)
Returns:
-
either `value` or `i,j,value` depending on the value of `indices`
See also:
- columns (a)
-
iterate over all columns.
Parameters:
- a
Returns:
-
column, column-index
- rows (a)
-
iterate over all rows.
Returns a copy of the row, for read-only purposes directly iterating
is more performant; `ipairs(a)`
Parameters:
- a
Returns:
-
row, row-index
- new (rows, cols, val)
-
new array of specified dimensions
Parameters:
- rows int number of rows
- cols int number of cols
- val initial value; if it's a function then use `val(i,j)`
Returns:
-
new 2d array