Penlight Documentation

# 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:

  pl.tablex.reduce
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:

  pl.tablex.reduce
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:

  slice
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:

  parse_range
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:

  parse_range
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:

  - parse_range
  - tablex.set
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:

  parse_range
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:

  parse_range
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:

  parse_range
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:

  parse_range
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