Module pl.array2d
Operations on two-dimensional arrays.
See The Guide
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 (a, j) | extract a column from the 2D array. |
row (a, i) | extract a row from the 2D array. |
map (f, a, arg) | map a function over a 2D array |
reduce_rows (f, a) | reduce the rows using a function. |
reduce_cols (f, a) | 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, t1, t2) | cartesian product of two 1d arrays. |
flatten (t) | flatten a 2D array. |
reshape (t, nrows, co) | reshape a 2D array. |
transpose (t) | transpose a 2D array. |
swap_rows (t, i1, i2) | swap two rows of an array. |
swap_cols (t, j1, j2) | swap two columns of an array. |
extract_rows (t, ridx) | extract the specified rows. |
extract_cols (t, cidx) | extract the specified columns. |
remove_row (t, i) | remove a row from an array. |
remove_col (t, 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 (t[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | normalizes coordinates to valid positive entries and defaults. |
slice (t[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | get a slice of a 2D array. |
set (t, value[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | set a specified range of an array to a value. |
write (t, f, fmt[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | write a 2D array to a file. |
forall (t, row_op, end_row_op[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | perform an operation for all values in a 2D array. |
move (dest, di, dj, src[, i1=1[, j1=1[, i2=N[, j2=M]]]]) | move a block from the destination to the source. |
iter (a, 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 array a 2d array
Returns:
-
int
number of rows (
#a
) -
int
number of cols (
#a[1]
)
- column (a, j)
-
extract a column from the 2D array.
Parameters:
- a array 2d array
- j column index
Returns:
-
1d array
- row (a, 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:
- a array 2d array
- i row index
Returns:
-
1d array (copy of the row)
- map (f, a, arg)
-
map a function over a 2D array
Parameters:
- f func a function of at least one argument
- a array 2d array
- arg an optional extra argument to be passed to the function.
Returns:
-
2d array
- reduce_rows (f, a)
-
reduce the rows using a function.
Parameters:
- f func a binary function
- a array 2d array
Returns:
-
1d array
See also:
- reduce_cols (f, a)
-
reduce the columns using a function.
Parameters:
- f func a binary function
- a array 2d array
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
ifa
is a list/array,2
if it is a 2d array) - bd
int
order of second array (
1
ifb
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, t1, t2)
-
cartesian product of two 1d arrays.
Parameters:
- f func a function of 2 arguments
- t1 array a 1d table
- t2 array a 1d table
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 array 2d table
Returns:
-
a 1d table
Usage:
flatten {{1,2},{3,4},{5,6}} == {1,2,3,4,5,6}
- reshape (t, nrows, co)
-
reshape a 2D array. Reshape the aray by specifying a new nr of rows.
Parameters:
- t array 2d array
- 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 array 2d array
Returns:
-
a new 2d array
- swap_rows (t, i1, i2)
-
swap two rows of an array.
Parameters:
- t array a 2d array
- i1 int a row index
- i2 int a row index
Returns:
-
t (same, modified 2d array)
- swap_cols (t, j1, j2)
-
swap two columns of an array.
Parameters:
- t array a 2d array
- j1 int a column index
- j2 int a column index
Returns:
-
t (same, modified 2d array)
- extract_rows (t, ridx)
-
extract the specified rows.
Parameters:
- t array 2d array
- ridx {int} a table of row indices
Returns:
-
a new 2d array with the extracted rows
- extract_cols (t, cidx)
-
extract the specified columns.
Parameters:
- t array 2d array
- cidx {int} a table of column indices
Returns:
-
a new 2d array with the extracted colums
- remove_row (t, i)
-
remove a row from an array.
Parameters:
- t array a 2d array
- i int a row index
- remove_col (t, j)
-
remove a column from an array.
Parameters:
- t array a 2d array
- 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 (t[, 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:
- t array a 2D array
- 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 (t[, 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:
- t array a 2D array
- 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 (t, value[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
set a specified range of an array to a value.
Parameters:
- t array a 2D array
- 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 (t, f, fmt[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
write a 2D array to a file.
Parameters:
- t array a 2D array
- 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 (t, row_op, end_row_op[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
perform an operation for all values in a 2D array.
Parameters:
- t array 2D array
- 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 (dest, di, dj, src[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
move a block from the destination to the source.
Parameters:
- dest array a 2D array
- di int start row in dest
- dj int start col in dest
- src array a 2D array
- 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 (a, indices[, i1=1[, j1=1[, i2=N[, j2=M]]]])
-
iterate over all elements in a 2D array, with optional indices.
Parameters:
- a array 2D array
- 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
ori,j,value
depending on the value ofindices
See also:
- columns (a)
-
iterate over all columns.
Parameters:
- a array a 2D array
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 array a 2D array
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