# Structure Array2

Identifier index | Structure index
--- | ---

    (* Array2 -- SML Basis Library *)

    eqtype 'a array

    datatype traversal = RowMajor | ColMajor

    val array      : int * int * '_a -> '_a array
    val fromList   : '_a list list -> '_a array
    val tabulate   : traversal -> int * int * (int * int -> '_a) -> '_a array

    val dimensions : 'a array -> int * int
    val nCols      : 'a array -> int
    val nRows      : 'a array -> int

    val sub        : 'a array * int * int -> 'a
    val update     : 'a array * int * int * 'a -> unit

    val row        : 'a array * int -> 'a Vector.vector
    val column     : 'a array * int -> 'a Vector.vector

    type 'a region = { base : 'a array, row : int, col : int,
                       nrows : int option, ncols : int option}

    val copy       : { src : 'a region, dst : 'a array,
                       dst_row : int, dst_col : int } -> unit

    val app        : traversal -> ('a -> unit) -> 'a array -> unit
    val modify     : traversal -> ('a -> 'a) -> 'a array -> unit
    val fold       : traversal -> ('a * 'b -> 'b) -> 'b -> 'a array -> 'b

    val appi       : traversal -> (int * int * 'a -> unit) -> 'a region -> unit
    val modifyi    : traversal -> (int * int * 'a -> 'a) -> 'a region -> unit
    val foldi      : traversal -> (int * int * 'a * 'b -> 'b) -> 'b
                     -> 'a region -> 'b

    (*
       ['ty array] is the type of two-dimensional, mutable, zero-based
       constant-time-access arrays with elements of type 'ty.
       Type 'ty array admits equality even if 'ty does not.  Arrays a1 and a2
       are equal if both were created by the same call to one of the
       primitives array, fromList, and tabulate.

       [traversal] is the type of traversal orders: row major or column major.

       [RowMajor] specifies that an operation must be done in row-major
       order, that is, one row at a time, from top to bottom, and from
       left to right within each row.  Row-major traversal visits the
       elements of an (m,n)-array with m rows and n columns in this
       order:
                (0,0), (0,1), (0,2), ..., (0,n-1),
                (1,0), (1,1), (1,2), ..., (1,n-1),
                        ...
       that is, in order of lexicographically increasing (i, j).  In
       Moscow ML, row-major traversal is usually faster than column-major
       traversal.

       [ColMajor] specifies that an operation must be done in column-major
       order, that is, one column at a time, from left to right, and from
       top to bottom within each column.  Column-major traversal visits
       the elements of an (m,n)-array with m rows and n columns in this
       order:
                (0,0), (1,0), (2,0), ..., (m-1,0),
                (0,1), (1,1), (2,1), ..., (m-1,1),
                        ...
       that is, in order of lexicographically increasing (j, i).

       [array(m, n, x)] returns a new m * n matrix whose elements are all x.
       Raises Size if n<0 or m<0.

       [fromList xss] returns a new array whose first row has elements
       xs1, second row has elements xs2, ..., where xss = [xs1,xs2,...,xsm].
       Raises Size if the lists in xss do not all have the same length.

       [tabulate RowMajor (m, n, f)] returns a new m-by-n array whose
       elements are f(0,0), f(0,1), ..., f(0, n-1),
                    f(1,0), f(1,1), ..., f(1, n-1),
                        ...
                    f(m-1,0),    ...,    f(m-1, n-1)
       created in row-major order: f(0,0), f(0,1), ..., f(1,0), f(1,1), ...
       Raises Size if n<0 or m<0.

       [tabulate ColMajor (m, n, f)] returns a new m-by-n array whose
       elements are as above, but created in the column-major order:
       f(0,0), f(1,0), ..., f(0, 1), f(1, 1), ...  Raises Size if n<0 or m<0.

       [dimensions a] returns the dimensions (m, n) of a, where m is the
       number of rows and n the number of columns.

       [nCols a] returns the number of n of columns of a.

       [nRows a] returns the number of m of rows of a.

       [sub(a, i, j)] returns the i'th row's j'th element, counting from 0.
       Raises Subscript if i<0 or j<0 or i>=m or j>=n
       where (m,n) = dimensions a.

       [update(a, i, j, x)] destructively replaces the (i,j)'th element of a
       by x. Raises Subscript if i<0 or j<0 or i>=m or j>=n
       where (m,n) = dimensions a.

       [row (a, i)] returns a vector containing the elements of the ith
       row of a.  Raises Subscript if i < 0 or i >= height a.

       [column (a, j)] returns a vector containing the elements of the jth
       column of a.  Raises Subscript if j < 0 or j >= width a.

       [app RowMajor f a] applies f to the elements a[0,0], a[0,1], ...,
       a[0,n-1], a[1,0], ..., a[m-1, n-1] of a, where (m, n) = dimensions a.

       [app ColMajor f a] applies f to the elements a[0,0], a[1,0], ...,
       a[n-1,0], a[0,1], a[1,1], ..., a[m-1, n-1] of a, where (m, n) =
       dimensions a.

       [modify RowMajor f a] applies f to the elements a[0,0], a[0,1],
       ..., a[0,n-1], a[1,0], ..., a[m-1, n-1] of a, updating each element
       with the result of the application, where (m, n) = dimensions a.

       [modify ColMajor f a] applies f to the elements a[0,0], a[1,0],
       ..., a[n-1,0], a[0,1], a[1,1], ..., a[m-1, n-1] of a, updating each
       element with the result of the application, where (m, n) =
       dimensions a.

       [fold RowMajor f b a] folds f left-right and top-down over the
       elements of a in row-major order.  That is, computes
            f(a[m-1, n-1], f(a[m-1, n-2], ..., f(a[0,1], f(a[0,0], b)) ...))
       where (m, n) = dimensions a.

       [fold ColMajor f b a] folds f left-right and top-down over the
       elements of a in column-major order.  That is, computes
            f(a[m-1, n-1], f(a[m-2, n-1], ..., f(a[1,0], f(a[0,0], b)) ...))
       where (m, n) = dimensions a.

       The following iterators generalize the above ones in two ways:

         * the indexes i and j are also being passed to the function;
         * the iterators work on a region (submatrix) of a matrix.

       [region] is the type of records { base, row, col, nrows, ncols }
       determining the region or submatrix of array base whose upper left
       corner has index (row, col).

       If nrows = SOME r, then the region has r rows: row, row+1, ..., row+r-1.
       If nrows = NONE, then the region extends to the bottom of the matrix.
       The field ncols similarly determines the number of columns.

       A region is valid for an array with dimensions (m, n) if
           (1) either nrows = NONE and 0 <= row <= m
               or nrows = SOME r and 0 <= row <= row + r <= m
       and (2) either ncols = NONE and 0 <= col <= n
               or ncols = SOME c and 0 <= col <= col + c <= n.

       [appi RowMajor f reg] applies f to (i, j, a[i, j]) in order of
       lexicographically increasing (i, j) within the region reg.  Raises
       Subscript if reg is not valid.  Note that app tr f a is equivalent
       to appi tr (f o #3) {base=a, row=0, col=0, nrows=NONE, ncols=NONE}

       [appi ColMajor f reg] applies f to (i, j, a[i, j]) in order of
       lexicographically increasing (j, i) within the region reg.  Raises
       Subscript if reg is not valid.

       [modifyi RowMajor f reg)] applies f to (i, j, a[i, j]) in order of
       lexicographically increasing (i, j) within the region reg.  Raises
       Subscript if reg is not valid.  Note that modify tr f a is equivalent
       to modifyi (f o #3) {base=a, row=0, col=0, nrows=NONE, ncols=NONE}).

       [modifyi ColMajor f reg)] applies f to (i, j, a[i, j]) in order of
       lexicographically increasing (j, i) within the region reg.  Raises
       Subscript if reg is not valid.

       [foldi RowMajor f b a] folds f over (i, j, a[i, j]) in row-major
       order within the region reg, that is, for lexicographically
       increasing (i, j) in the region.  Raises Subscript if reg is not
       valid.

       [foldi ColMajor f b a] folds f over (i, j, a[i, j]) in column-major
       order within the region reg, that is, for lexicographically
       increasing (j, i) in the region.  Raises Subscript if reg is not
       valid.

       [copy { src, dst, dst_row, dst_col }] copies the region determined
       by src to array dst such that the upper leftmost corner of src is
       copied to dst[dst_row, dst_col].  Works correctly even when src and
       dst are the same and the source and destination regions overlap.
       Raises Subscript if the src region is invalid, or if src translated
       to (dst_row, dst_col) is invalid for dst.
    *)

Identifier index | Structure index
--- | ---

Moscow ML 2.10