From 42ec7286b2d36a9ba22925f816a17cb1cc2aa5ce Mon Sep 17 00:00:00 2001 From: chai Date: Sat, 30 Oct 2021 11:32:16 +0800 Subject: + Penlight --- .../Penlight/docs/libraries/pl.array2d.html | 1319 ++++++++++++++++++++ 1 file changed, 1319 insertions(+) create mode 100644 Data/Libraries/Penlight/docs/libraries/pl.array2d.html (limited to 'Data/Libraries/Penlight/docs/libraries/pl.array2d.html') diff --git a/Data/Libraries/Penlight/docs/libraries/pl.array2d.html b/Data/Libraries/Penlight/docs/libraries/pl.array2d.html new file mode 100644 index 0000000..8ee905b --- /dev/null +++ b/Data/Libraries/Penlight/docs/libraries/pl.array2d.html @@ -0,0 +1,1319 @@ + + + + + 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. +
  2. + int + number of cols (#a[1])
    3. +
+ + + + +
+
+ + 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 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. +
  2. + int + start col
    3. +
  3. + int + end row
    4. +
  4. + int + end col
    5. +
+ + + + +
+
+ + 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:

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

+ + + +
+
+ + 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 +
+
+ + -- cgit v1.1-26-g67d0