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:

  1. int number of rows (#a)
  2. 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 function 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 function a binary function
  • a array 2d array

Returns:

    1d array

See also:

reduce_cols (f, a)
reduce the columns using a function.

Parameters:

  • f function 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 function operation to reduce the final result
  • opr function 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 function function of at least two arguments
  • ad integer order of first array (1 if a is a list/array, 2 if it is a 2d array)
  • bd integer order of second array (1 if b is a list/array, 2 if it is a 2d array)
  • a table 1d or 2d array
  • b table 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 function 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 array by specifying a new nr of rows.

Parameters:

  • t array 2d array
  • nrows integer new number of rows
  • co boolean 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 integer a row index
  • i2 integer 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 integer a column index
  • j2 integer 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 columns
remove_row (t, i)
remove a row from an array.

Parameters:

  • t array a 2d array
  • i integer a row index
remove_col (t, j)
remove a column from an array.

Parameters:

  • t array a 2d array
  • j integer 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:

  1. int start row
  2. int start col
  3. int end row (or nil if the range was a single cell)
  4. 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 function function to call on each value; row_op(row,j)
  • end_row_op function 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 integer start row in dest
  • dj integer 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 boolean 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 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 integer number of rows
  • cols integer number of cols
  • val initial value; if it's a function then use val(i,j)

Returns:

    new 2d array
generated by LDoc 1.5.0