15.3.531  src/lib/std/src/rw-matrix.api

## rw-matrix.api
#
# Two-dimensional matrices laid out in row-major order, like C but unlike Fortran and Matlab.
# For background on row-major order see:  http://en.wikipedia.org/wiki/Row-major_order
#
# Use (_[]) and (_[]:=) to improve readability:
#
#     eval:  m = rw_matrix::make_matrix ((2, 2), 0.0);
#     eval:  rw_matrix::get (m, (0,0));
#     0.0
#     
#     eval:  rw_matrix::set (m, (0,0), 1.0);
#     eval:  rw_matrix::get (m, (0,0));
#     1.0
#     
#     eval:  (_[])   =  rw_matrix::get;
#     eval:  (_[]:=) =  rw_matrix::set;
#     eval:  m[0,0] :=  2.0;
#     eval:  m[0,0]; 
#     2.0
#
# See also:
#
#     src/lib/std/src/typelocked-rw-matrix.api

# Compiled by:
#     src/lib/std/src/standard-core.sublib



stipulate
    package rwv =  rw_vector;                                                   # rw_vector             is from   src/lib/std/src/rw-vector.pkg
    package vec =  vector;                                                      # vector                is from   src/lib/std/src/vector.pkg
herein

    # This api is immplemented in:
    #
    #     src/lib/std/src/rw-matrix.pkg
    #
    api Rw_Matrix {
        #
        Rw_Matrix(X)                                                            # Duplicated as poly_rw_matrix::Rw_matrix(X)    in  src/lib/core/init/built-in.pkg
            =
            { rw_vector:        rwv::Rw_Vector(X),
              rows:             Int,
              cols:             Int
            };

        Region(X)                                                               # Specify an ROI ("Region Of Interest") within a matrix.
            =
            { rw_matrix:        Rw_Matrix(X),                                   # Matrix containing the ROI.
              row:              Int,                                            # Low corner of ROI is (row, col).  ("col" == "column".)
              col:              Int,                                            # 
              rows:             Null_Or( Int ),                                 # Number of rows    in ROI.  Defaults to max possible given 'row' value.
              cols:             Null_Or( Int )                                  # Number of columns in ROI.  Defaults to max possible given 'col' value.
            };

        make_rw_matrix: ((Int, Int), X) -> Rw_Matrix(X);                        # Arg is ((rows, cols), initval).

        from_list:   (Int, Int) -> List(X) -> Rw_Matrix(X);
        from_lists:  List( List(X) ) -> Rw_Matrix(X);
        from_fn:    ((Int, Int), (Int, Int) -> X) -> Rw_Matrix(X);

        get:        (Rw_Matrix(X), (Int, Int)) -> X;                            # Arg is (row, col)
        (_[]):      (Rw_Matrix(X), (Int, Int)) -> X;                            # Synonym for previous;  supports   foo = matrix[row,col];   syntax.

        set:        (Rw_Matrix(X), (Int, Int), X) -> Void;
        (_[]:=):    (Rw_Matrix(X), (Int, Int), X) -> Void;                      # Synonym for previous;  supports   matrix[row,col] := foo;   syntax.

        rowscols:    Rw_Matrix(X) -> (Int, Int);
        cols:        Rw_Matrix(X) -> Int;
        rows:        Rw_Matrix(X) -> Int;

        row:        (Rw_Matrix(X), Int) -> vec::Vector(X);
        col:        (Rw_Matrix(X), Int) -> vec::Vector(X);

        copy_region:
              { region:         Region(X),                                      # Copy contents of this region
                to:             Rw_Matrix(X),                                   # to this matrix, with low corner at (to_row, to_col).
                #
                to_row:  Int,                                                   #
                to_col:  Int                                                    #
              }
             ->
             Void;

        apply:                  (X             -> Void) -> Rw_Matrix(X) -> Void;
        region_apply:           ((Int, Int, X) -> Void) ->    Region(X) -> Void;

        map_in_place:           (X             -> X) -> Rw_Matrix(X) -> Void;
        region_map_in_place:    ((Int, Int, X) -> X) ->    Region(X) -> Void;

        fold_forward:           ((X, Y) -> Y) -> Y -> Rw_Matrix(X) -> Y;
        region_fold_forward:    ((Int, Int, X, Y) -> Y) -> Y -> Region(X) -> Y;

    };
end;


## COPYRIGHT (c) 1997 AT&T Research.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2015,
## released per terms of SMLNJ-COPYRIGHT.