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.
range (t, rstr) | get a slice of a 2D array using spreadsheet range notation.
default_range (t, i1, j1, i2, j2) | normalizes coordinates to valid positive entries and defaults.
slice (t, i1, j1, i2, j2) | get a slice of a 2D array.
set (t, value, i1, j1, i2, j2) | set a specified range of an array to a value.
write (t, f, fmt, i1, j1, i2, j2) | write a 2D array to a file.
forall (t, row_op, end_row_op, i1, j1, i2, j2) | perform an operation for all values in a 2D array.
move (dest, di, dj, src, i1, j1, i2, j2) | move a block from the destination to the source.
iter (a, indices, i1, j1, i2, j2) | 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 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:

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

  pl.tablex.reduce
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, 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. The range can be specified either as 'A1:B2' or 'R1C1:R2C2'; a special case is a single element (e.g 'A1' or 'R1C1')

  ### Parameters:

  - s string a range (case insensitive).

  ### Returns:

  1. int start row
  2. int start col
  3. int end row
  4. int end col
range (t, rstr)
  get a slice of a 2D array using spreadsheet range notation. @see parse_range

  ### Parameters:

  - t array a 2D array
  - rstr string range expression

  ### Returns:

  a slice

  ### See also:

  - array2d.parse_range
  - array2d.slice
default_range (t, i1, j1, i2, j2)
  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 start row (default 1)
  - j1 int start col (default 1)
  - i2 int end row (default N)
  - j2 int end col (default M) return i1, j1, i2, j2
slice (t, i1, j1, i2, j2)
  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 start row (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.
set (t, value, i1, j1, i2, j2)
  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 start row (default 1)
  - j1 int start col (default 1)
  - i2 int end row (default N)
  - j2 int end col (default M)

  ### See also:

  tablex.set
write (t, f, fmt, i1, j1, i2, j2)
  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 start row (default 1)
  - j1 int start col (default 1)
  - i2 int end row (default N)
  - j2 int end col (default M)
forall (t, row_op, end_row_op, i1, j1, i2, j2)
  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 start row (default 1)
  - j1 int start col (default 1)
  - i2 int end row (default N)
  - j2 int end col (default M)
move (dest, di, dj, src, i1, j1, i2, j2)
  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 start row (default 1)
  - j1 int start col (default 1)
  - i2 int end row (default N)
  - j2 int end col (default M)
iter (a, indices, i1, j1, i2, j2)
  iterate over all elements in a 2D array, with optional indices.

  ### Parameters:

  - a array 2D array
  - indices bool with indices (default false)
  - i1 int start row (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`
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 purrposes 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

generated by LDoc 1.4.6