    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017
    018    package org.apache.commons.math3.linear;
    019
    020
    021    import org.apache.commons.math3.Field;
    022    import org.apache.commons.math3.FieldElement;
    023    import org.apache.commons.math3.exception.DimensionMismatchException;
    024    import org.apache.commons.math3.exception.NoDataException;
    025    import org.apache.commons.math3.exception.NotPositiveException;
    026    import org.apache.commons.math3.exception.NotStrictlyPositiveException;
    027    import org.apache.commons.math3.exception.NullArgumentException;
    028    import org.apache.commons.math3.exception.NumberIsTooSmallException;
    029    import org.apache.commons.math3.exception.OutOfRangeException;
    030
    031    /**
    032     * Interface defining field-valued matrix with basic algebraic operations.
    033     * <p>
    034     * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
    035     * returns the element in the first row, first column of the matrix.</p>
    036     *
    037     * @param <T> the type of the field elements
    038     * @version $Id: FieldMatrix.java 1416643 2012-12-03 19:37:14Z tn $
    039     */
    040    public interface FieldMatrix<T extends FieldElement<T>> extends AnyMatrix {
    041        /**
    042         * Get the type of field elements of the matrix.
    043         *
    044         * @return the type of field elements of the matrix.
    045         */
    046        Field<T> getField();
    047
    048        /**
    049         * Create a new FieldMatrix<T> of the same type as the instance with
    050         * the supplied row and column dimensions.
    051         *
    052         * @param rowDimension  the number of rows in the new matrix
    053         * @param columnDimension  the number of columns in the new matrix
    054         * @return a new matrix of the same type as the instance
    055         * @throws NotStrictlyPositiveException if row or column dimension is not
    056         * positive.
    057         * @since 2.0
    058         */
    059        FieldMatrix<T> createMatrix(final int rowDimension, final int columnDimension)
    060        throws NotStrictlyPositiveException;
    061
    062        /**
    063         * Make a (deep) copy of this.
    064         *
    065         * @return a copy of this matrix.
    066         */
    067        FieldMatrix<T> copy();
    068
    069        /**
    070         * Compute the sum of this and m.
    071         *
    072         * @param m Matrix to be added.
    073         * @return {@code this} + {@code m}.
    074         * @throws MatrixDimensionMismatchException if {@code m} is not the same
    075         * size as {@code this} matrix.
    076         */
    077        FieldMatrix<T> add(FieldMatrix<T> m) throws MatrixDimensionMismatchException;
    078
    079        /**
    080         * Subtract {@code m} from this matrix.
    081         *
    082         * @param m Matrix to be subtracted.
    083         * @return {@code this} - {@code m}.
    084         * @throws MatrixDimensionMismatchException if {@code m} is not the same
    085         * size as {@code this} matrix.
    086         */
    087        FieldMatrix<T> subtract(FieldMatrix<T> m) throws MatrixDimensionMismatchException;
    088
    089         /**
    090         * Increment each entry of this matrix.
    091         *
    092         * @param d Value to be added to each entry.
    093         * @return {@code d} + {@code this}.
    094         */
    095        FieldMatrix<T> scalarAdd(T d);
    096
    097        /**
    098         * Multiply each entry by {@code d}.
    099         *
    100         * @param d Value to multiply all entries by.
    101         * @return {@code d} * {@code this}.
    102         */
    103        FieldMatrix<T> scalarMultiply(T d);
    104
    105        /**
    106         * Postmultiply this matrix by {@code m}.
    107         *
    108         * @param m  Matrix to postmultiply by.
    109         * @return {@code this} * {@code m}.
    110         * @throws DimensionMismatchException if the number of columns of
    111         * {@code this} matrix is not equal to the number of rows of matrix
    112         * {@code m}.
    113         */
    114        FieldMatrix<T> multiply(FieldMatrix<T> m) throws DimensionMismatchException;
    115
    116        /**
    117         * Premultiply this matrix by {@code m}.
    118         *
    119         * @param m Matrix to premultiply by.
    120         * @return {@code m} * {@code this}.
    121         * @throws DimensionMismatchException if the number of columns of {@code m}
    122         * differs from the number of rows of {@code this} matrix.
    123         */
    124        FieldMatrix<T> preMultiply(FieldMatrix<T> m) throws DimensionMismatchException;
    125
    126        /**
    127         * Returns the result multiplying this with itself <code>p</code> times.
    128         * Depending on the type of the field elements, T, instability for high
    129         * powers might occur.
    130         *
    131         * @param p raise this to power p
    132         * @return this^p
    133         * @throws NotPositiveException if {@code p < 0}
    134         * @throws NonSquareMatrixException if {@code this matrix} is not square
    135         */
    136        FieldMatrix<T> power(final int p) throws NonSquareMatrixException,
    137        NotPositiveException;
    138
    139        /**
    140         * Returns matrix entries as a two-dimensional array.
    141         *
    142         * @return a 2-dimensional array of entries.
    143         */
    144        T[][] getData();
    145
    146        /**
    147         * Get a submatrix. Rows and columns are indicated
    148         * counting from 0 to n - 1.
    149         *
    150         * @param startRow Initial row index
    151         * @param endRow Final row index (inclusive)
    152         * @param startColumn Initial column index
    153         * @param endColumn Final column index (inclusive)
    154         * @return the matrix containing the data of the specified rows and columns.
    155         * @throws NumberIsTooSmallException is {@code endRow < startRow} of
    156         * {@code endColumn < startColumn}.
    157         * @throws OutOfRangeException if the indices are not valid.
    158         */
    159       FieldMatrix<T> getSubMatrix(int startRow, int endRow, int startColumn, int endColumn)
    160       throws NumberIsTooSmallException, OutOfRangeException;
    161
    162       /**
    163        * Get a submatrix. Rows and columns are indicated
    164        * counting from 0 to n - 1.
    165        *
    166        * @param selectedRows Array of row indices.
    167        * @param selectedColumns Array of column indices.
    168        * @return the matrix containing the data in the
    169        * specified rows and columns.
    170        * @throws NoDataException if {@code selectedRows} or
    171        * {@code selectedColumns} is empty
    172        * @throws NullArgumentException if {@code selectedRows} or
    173        * {@code selectedColumns} is {@code null}.
    174        * @throws OutOfRangeException if row or column selections are not valid.
    175        */
    176       FieldMatrix<T> getSubMatrix(int[] selectedRows, int[] selectedColumns)
    177       throws NoDataException, NullArgumentException, OutOfRangeException;
    178
    179       /**
    180        * Copy a submatrix. Rows and columns are indicated
    181        * counting from 0 to n-1.
    182        *
    183        * @param startRow Initial row index.
    184        * @param endRow Final row index (inclusive).
    185        * @param startColumn Initial column index.
    186        * @param endColumn Final column index (inclusive).
    187        * @param destination The arrays where the submatrix data should be copied
    188        * (if larger than rows/columns counts, only the upper-left part will be used).
    189        * @throws MatrixDimensionMismatchException if the dimensions of
    190        * {@code destination} do not match those of {@code this}.
    191        * @throws NumberIsTooSmallException is {@code endRow < startRow} of
    192        * {@code endColumn < startColumn}.
    193        * @throws OutOfRangeException if the indices are not valid.
    194        * @exception IllegalArgumentException if the destination array is too small.
    195        */
    196        void copySubMatrix(int startRow, int endRow, int startColumn, int endColumn,
    197                           T[][] destination)
    198        throws MatrixDimensionMismatchException, NumberIsTooSmallException,
    199        OutOfRangeException;
    200
    201      /**
    202       * Copy a submatrix. Rows and columns are indicated
    203       * counting from 0 to n - 1.
    204       *
    205       * @param selectedRows Array of row indices.
    206       * @param selectedColumns Array of column indices.
    207       * @param destination Arrays where the submatrix data should be copied
    208       * (if larger than rows/columns counts, only the upper-left part will be used)
    209       * @throws MatrixDimensionMismatchException if the dimensions of
    210       * {@code destination} do not match those of {@code this}.
    211       * @throws NoDataException if {@code selectedRows} or
    212       * {@code selectedColumns} is empty
    213       * @throws NullArgumentException if {@code selectedRows} or
    214       * {@code selectedColumns} is {@code null}.
    215       * @throws OutOfRangeException if the indices are not valid.
    216       */
    217      void copySubMatrix(int[] selectedRows, int[] selectedColumns, T[][] destination)
    218      throws MatrixDimensionMismatchException, NoDataException, NullArgumentException,
    219      OutOfRangeException;
    220
    221        /**
    222         * Replace the submatrix starting at {@code (row, column)} using data in the
    223         * input {@code subMatrix} array. Indexes are 0-based.
    224         * <p>
    225         * Example:<br>
    226         * Starting with
    227         *
    228         * <pre>
    229         * 1  2  3  4
    230         * 5  6  7  8
    231         * 9  0  1  2
    232         * </pre>
    233         *
    234         * and <code>subMatrix = {{3, 4} {5,6}}</code>, invoking
    235         * <code>setSubMatrix(subMatrix,1,1))</code> will result in
    236         *
    237         * <pre>
    238         * 1  2  3  4
    239         * 5  3  4  8
    240         * 9  5  6  2
    241         * </pre>
    242         *
    243         * </p>
    244         *
    245         * @param subMatrix Array containing the submatrix replacement data.
    246         * @param row Row coordinate of the top-left element to be replaced.
    247         * @param column Column coordinate of the top-left element to be replaced.
    248         * @throws OutOfRangeException if {@code subMatrix} does not fit into this
    249         * matrix from element in {@code (row, column)}.
    250         * @throws NoDataException if a row or column of {@code subMatrix} is empty.
    251         * @throws DimensionMismatchException if {@code subMatrix} is not
    252         * rectangular (not all rows have the same length).
    253         * @throws NullArgumentException if {@code subMatrix} is {@code null}.
    254         * @since 2.0
    255         */
    256        void setSubMatrix(T[][] subMatrix, int row, int column)
    257            throws DimensionMismatchException, OutOfRangeException,
    258            NoDataException, NullArgumentException;
    259
    260       /**
    261        * Get the entries in row number {@code row}
    262        * as a row matrix.
    263        *
    264        * @param row Row to be fetched.
    265        * @return a row matrix.
    266        * @throws OutOfRangeException if the specified row index is invalid.
    267        */
    268       FieldMatrix<T> getRowMatrix(int row) throws OutOfRangeException;
    269
    270       /**
    271        * Set the entries in row number {@code row}
    272        * as a row matrix.
    273        *
    274        * @param row Row to be set.
    275        * @param matrix Row matrix (must have one row and the same number
    276        * of columns as the instance).
    277        * @throws OutOfRangeException if the specified row index is invalid.
    278        * @throws MatrixDimensionMismatchException
    279        * if the matrix dimensions do not match one instance row.
    280        */
    281       void setRowMatrix(int row, FieldMatrix<T> matrix)
    282       throws MatrixDimensionMismatchException, OutOfRangeException;
    283
    284       /**
    285        * Get the entries in column number {@code column}
    286        * as a column matrix.
    287        *
    288        * @param column Column to be fetched.
    289        * @return a column matrix.
    290        * @throws OutOfRangeException if the specified column index is invalid.
    291        */
    292       FieldMatrix<T> getColumnMatrix(int column) throws OutOfRangeException;
    293
    294       /**
    295        * Set the entries in column number {@code column}
    296        * as a column matrix.
    297        *
    298        * @param column Column to be set.
    299        * @param matrix column matrix (must have one column and the same
    300        * number of rows as the instance).
    301        * @throws OutOfRangeException if the specified column index is invalid.
    302        * @throws MatrixDimensionMismatchException if the matrix dimensions do
    303        * not match one instance column.
    304        */
    305       void setColumnMatrix(int column, FieldMatrix<T> matrix)
    306       throws MatrixDimensionMismatchException, OutOfRangeException;
    307
    308       /**
    309        * Get the entries in row number {@code row}
    310        * as a vector.
    311        *
    312        * @param row Row to be fetched
    313        * @return a row vector.
    314        * @throws OutOfRangeException if the specified row index is invalid.
    315        */
    316       FieldVector<T> getRowVector(int row) throws OutOfRangeException;
    317
    318       /**
    319        * Set the entries in row number {@code row}
    320        * as a vector.
    321        *
    322        * @param row Row to be set.
    323        * @param vector row vector (must have the same number of columns
    324        * as the instance).
    325        * @throws OutOfRangeException if the specified row index is invalid.
    326        * @throws MatrixDimensionMismatchException if the vector dimension does not
    327        * match one instance row.
    328        */
    329       void setRowVector(int row, FieldVector<T> vector)
    330       throws MatrixDimensionMismatchException, OutOfRangeException;
    331
    332       /**
    333        * Returns the entries in column number {@code column}
    334        * as a vector.
    335        *
    336        * @param column Column to be fetched.
    337        * @return a column vector.
    338        * @throws OutOfRangeException if the specified column index is invalid.
    339        */
    340       FieldVector<T> getColumnVector(int column) throws OutOfRangeException;
    341
    342       /**
    343        * Set the entries in column number {@code column}
    344        * as a vector.
    345        *
    346        * @param column Column to be set.
    347        * @param vector Column vector (must have the same number of rows
    348        * as the instance).
    349        * @throws OutOfRangeException if the specified column index is invalid.
    350        * @throws MatrixDimensionMismatchException if the vector dimension does not
    351        * match one instance column.
    352        */
    353       void setColumnVector(int column, FieldVector<T> vector)
    354       throws MatrixDimensionMismatchException, OutOfRangeException;
    355
    356        /**
    357         * Get the entries in row number {@code row} as an array.
    358         *
    359         * @param row Row to be fetched.
    360         * @return array of entries in the row.
    361         * @throws OutOfRangeException if the specified row index is not valid.
    362         */
    363        T[] getRow(int row) throws OutOfRangeException;
    364
    365        /**
    366         * Set the entries in row number {@code row}
    367         * as a row matrix.
    368         *
    369         * @param row Row to be set.
    370         * @param array Row matrix (must have the same number of columns as
    371         * the instance).
    372         * @throws OutOfRangeException if the specified row index is invalid.
    373         * @throws MatrixDimensionMismatchException if the array size does not match
    374         * one instance row.
    375         */
    376        void setRow(int row, T[] array) throws MatrixDimensionMismatchException,
    377        OutOfRangeException;
    378
    379        /**
    380         * Get the entries in column number {@code col} as an array.
    381         *
    382         * @param column the column to be fetched
    383         * @return array of entries in the column
    384         * @throws OutOfRangeException if the specified column index is not valid.
    385         */
    386        T[] getColumn(int column) throws OutOfRangeException;
    387
    388        /**
    389         * Set the entries in column number {@code column}
    390         * as a column matrix.
    391         *
    392         * @param column the column to be set
    393         * @param array column array (must have the same number of rows as the instance)
    394         * @throws OutOfRangeException if the specified column index is invalid.
    395         * @throws MatrixDimensionMismatchException if the array size does not match
    396         * one instance column.
    397         */
    398        void setColumn(int column, T[] array) throws MatrixDimensionMismatchException,
    399        OutOfRangeException;
    400
    401        /**
    402         * Returns the entry in the specified row and column.
    403         *
    404         * @param row  row location of entry to be fetched
    405         * @param column  column location of entry to be fetched
    406         * @return matrix entry in row,column
    407         * @throws OutOfRangeException if the row or column index is not valid.
    408         */
    409        T getEntry(int row, int column) throws OutOfRangeException;
    410
    411        /**
    412         * Set the entry in the specified row and column.
    413         *
    414         * @param row  row location of entry to be set
    415         * @param column  column location of entry to be set
    416         * @param value matrix entry to be set in row,column
    417         * @throws OutOfRangeException if the row or column index is not valid.
    418         * @since 2.0
    419         */
    420        void setEntry(int row, int column, T value) throws OutOfRangeException;
    421
    422        /**
    423         * Change an entry in the specified row and column.
    424         *
    425         * @param row Row location of entry to be set.
    426         * @param column Column location of entry to be set.
    427         * @param increment Value to add to the current matrix entry in
    428         * {@code (row, column)}.
    429         * @throws OutOfRangeException if the row or column index is not valid.
    430         * @since 2.0
    431         */
    432        void addToEntry(int row, int column, T increment) throws OutOfRangeException;
    433
    434        /**
    435         * Change an entry in the specified row and column.
    436         *
    437         * @param row Row location of entry to be set.
    438         * @param column Column location of entry to be set.
    439         * @param factor Multiplication factor for the current matrix entry
    440         * in {@code (row,column)}
    441         * @throws OutOfRangeException if the row or column index is not valid.
    442         * @since 2.0
    443         */
    444        void multiplyEntry(int row, int column, T factor) throws OutOfRangeException;
    445
    446        /**
    447         * Returns the transpose of this matrix.
    448         *
    449         * @return transpose matrix
    450         */
    451        FieldMatrix<T> transpose();
    452
    453        /**
    454         * Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
    455         * trace</a> of the matrix (the sum of the elements on the main diagonal).
    456         *
    457         * @return trace
    458         * @throws NonSquareMatrixException if the matrix is not square.
    459         */
    460        T getTrace() throws NonSquareMatrixException;
    461
    462        /**
    463         * Returns the result of multiplying this by the vector {@code v}.
    464         *
    465         * @param v the vector to operate on
    466         * @return {@code this * v}
    467         * @throws DimensionMismatchException if the number of columns of
    468         * {@code this} matrix is not equal to the size of the vector {@code v}.
    469         */
    470        T[] operate(T[] v) throws DimensionMismatchException;
    471
    472        /**
    473         * Returns the result of multiplying this by the vector {@code v}.
    474         *
    475         * @param v the vector to operate on
    476         * @return {@code this * v}
    477         * @throws DimensionMismatchException if the number of columns of
    478         * {@code this} matrix is not equal to the size of the vector {@code v}.
    479         */
    480        FieldVector<T> operate(FieldVector<T> v) throws DimensionMismatchException;
    481
    482        /**
    483         * Returns the (row) vector result of premultiplying this by the vector
    484         * {@code v}.
    485         *
    486         * @param v the row vector to premultiply by
    487         * @return {@code v * this}
    488         * @throws DimensionMismatchException if the number of rows of {@code this}
    489         * matrix is not equal to the size of the vector {@code v}
    490         */
    491        T[] preMultiply(T[] v) throws DimensionMismatchException;
    492
    493        /**
    494         * Returns the (row) vector result of premultiplying this by the vector
    495         * {@code v}.
    496         *
    497         * @param v the row vector to premultiply by
    498         * @return {@code v * this}
    499         * @throws DimensionMismatchException if the number of rows of {@code this}
    500         * matrix is not equal to the size of the vector {@code v}
    501         */
    502        FieldVector<T> preMultiply(FieldVector<T> v) throws DimensionMismatchException;
    503
    504        /**
    505         * Visit (and possibly change) all matrix entries in row order.
    506         * <p>Row order starts at upper left and iterating through all elements
    507         * of a row from left to right before going to the leftmost element
    508         * of the next row.</p>
    509         * @param visitor visitor used to process all matrix entries
    510         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    511         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    512         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    513         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    514         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    515         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    516         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    517         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    518         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    519         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    520         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    521         * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
    522         * of the walk
    523         */
    524        T walkInRowOrder(FieldMatrixChangingVisitor<T> visitor);
    525
    526        /**
    527         * Visit (but don't change) all matrix entries in row order.
    528         * <p>Row order starts at upper left and iterating through all elements
    529         * of a row from left to right before going to the leftmost element
    530         * of the next row.</p>
    531         * @param visitor visitor used to process all matrix entries
    532         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    533         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    534         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    535         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    536         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    537         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    538         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    539         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    540         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    541         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    542         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    543         * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
    544         * of the walk
    545         */
    546        T walkInRowOrder(FieldMatrixPreservingVisitor<T> visitor);
    547
    548        /**
    549         * Visit (and possibly change) some matrix entries in row order.
    550         * <p>Row order starts at upper left and iterating through all elements
    551         * of a row from left to right before going to the leftmost element
    552         * of the next row.</p>
    553         * @param visitor visitor used to process all matrix entries
    554         * @param startRow Initial row index
    555         * @param endRow Final row index (inclusive)
    556         * @param startColumn Initial column index
    557         * @param endColumn Final column index
    558         * @throws OutOfRangeException if the indices are not valid.
    559         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    560         * {@code endColumn < startColumn}.
    561         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    562         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    563         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    564         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    565         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    566         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    567         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    568         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    569         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    570         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    571         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    572         * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
    573         * of the walk
    574         */
    575        T walkInRowOrder(FieldMatrixChangingVisitor<T> visitor,
    576                         int startRow, int endRow, int startColumn, int endColumn)
    577        throws OutOfRangeException, NumberIsTooSmallException;
    578
    579        /**
    580         * Visit (but don't change) some matrix entries in row order.
    581         * <p>Row order starts at upper left and iterating through all elements
    582         * of a row from left to right before going to the leftmost element
    583         * of the next row.</p>
    584         * @param visitor visitor used to process all matrix entries
    585         * @param startRow Initial row index
    586         * @param endRow Final row index (inclusive)
    587         * @param startColumn Initial column index
    588         * @param endColumn Final column index
    589         * @throws OutOfRangeException if the indices are not valid.
    590         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    591         * {@code endColumn < startColumn}.
    592         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    593         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    594         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    595         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    596         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    597         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    598         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    599         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    600         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    601         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    602         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    603         * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
    604         * of the walk
    605         */
    606        T walkInRowOrder(FieldMatrixPreservingVisitor<T> visitor,
    607                         int startRow, int endRow, int startColumn, int endColumn)
    608        throws OutOfRangeException, NumberIsTooSmallException;
    609
    610        /**
    611         * Visit (and possibly change) all matrix entries in column order.
    612         * <p>Column order starts at upper left and iterating through all elements
    613         * of a column from top to bottom before going to the topmost element
    614         * of the next column.</p>
    615         * @param visitor visitor used to process all matrix entries
    616         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    617         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    618         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    619         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    620         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    621         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    622         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    623         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    624         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    625         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    626         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    627         * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
    628         * of the walk
    629         */
    630        T walkInColumnOrder(FieldMatrixChangingVisitor<T> visitor);
    631
    632        /**
    633         * Visit (but don't change) all matrix entries in column order.
    634         * <p>Column order starts at upper left and iterating through all elements
    635         * of a column from top to bottom before going to the topmost element
    636         * of the next column.</p>
    637         * @param visitor visitor used to process all matrix entries
    638         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    639         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    640         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    641         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    642         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    643         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    644         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    645         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    646         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    647         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    648         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    649         * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
    650         * of the walk
    651         */
    652        T walkInColumnOrder(FieldMatrixPreservingVisitor<T> visitor);
    653
    654        /**
    655         * Visit (and possibly change) some matrix entries in column order.
    656         * <p>Column order starts at upper left and iterating through all elements
    657         * of a column from top to bottom before going to the topmost element
    658         * of the next column.</p>
    659         * @param visitor visitor used to process all matrix entries
    660         * @param startRow Initial row index
    661         * @param endRow Final row index (inclusive)
    662         * @param startColumn Initial column index
    663         * @param endColumn Final column index
    664         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    665         * {@code endColumn < startColumn}.
    666         * @throws OutOfRangeException if the indices are not valid.
    667         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    668         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    669         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    670         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    671         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    672         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    673         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    674         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    675         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    676         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    677         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    678         * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
    679         * of the walk
    680         */
    681        T walkInColumnOrder(FieldMatrixChangingVisitor<T> visitor,
    682                            int startRow, int endRow, int startColumn, int endColumn)
    683        throws NumberIsTooSmallException, OutOfRangeException;
    684
    685        /**
    686         * Visit (but don't change) some matrix entries in column order.
    687         * <p>Column order starts at upper left and iterating through all elements
    688         * of a column from top to bottom before going to the topmost element
    689         * of the next column.</p>
    690         * @param visitor visitor used to process all matrix entries
    691         * @param startRow Initial row index
    692         * @param endRow Final row index (inclusive)
    693         * @param startColumn Initial column index
    694         * @param endColumn Final column index
    695         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    696         * {@code endColumn < startColumn}.
    697         * @throws OutOfRangeException if the indices are not valid.
    698         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    699         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    700         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    701         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    702         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    703         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    704         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    705         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    706         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    707         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    708         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    709         * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
    710         * of the walk
    711         */
    712        T walkInColumnOrder(FieldMatrixPreservingVisitor<T> visitor,
    713                            int startRow, int endRow, int startColumn, int endColumn)
    714        throws NumberIsTooSmallException, OutOfRangeException;
    715
    716        /**
    717         * Visit (and possibly change) all matrix entries using the fastest possible order.
    718         * <p>The fastest walking order depends on the exact matrix class. It may be
    719         * different from traditional row or column orders.</p>
    720         * @param visitor visitor used to process all matrix entries
    721         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    722         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    723         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    724         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    725         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    726         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    727         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    728         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    729         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    730         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    731         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    732         * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
    733         * of the walk
    734         */
    735        T walkInOptimizedOrder(FieldMatrixChangingVisitor<T> visitor);
    736
    737        /**
    738         * Visit (but don't change) all matrix entries using the fastest possible order.
    739         * <p>The fastest walking order depends on the exact matrix class. It may be
    740         * different from traditional row or column orders.</p>
    741         * @param visitor visitor used to process all matrix entries
    742         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    743         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    744         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    745         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    746         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    747         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    748         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    749         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    750         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    751         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    752         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    753         * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
    754         * of the walk
    755         */
    756        T walkInOptimizedOrder(FieldMatrixPreservingVisitor<T> visitor);
    757
    758        /**
    759         * Visit (and possibly change) some matrix entries using the fastest possible order.
    760         * <p>The fastest walking order depends on the exact matrix class. It may be
    761         * different from traditional row or column orders.</p>
    762         * @param visitor visitor used to process all matrix entries
    763         * @param startRow Initial row index
    764         * @param endRow Final row index (inclusive)
    765         * @param startColumn Initial column index
    766         * @param endColumn Final column index (inclusive)
    767         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    768         * {@code endColumn < startColumn}.
    769         * @throws OutOfRangeException if the indices are not valid.
    770         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    771         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    772         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    773         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    774         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    775         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    776         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    777         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    778         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    779         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    780         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    781         * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
    782         * of the walk
    783         */
    784        T walkInOptimizedOrder(FieldMatrixChangingVisitor<T> visitor,
    785                               int startRow, int endRow, int startColumn, int endColumn)
    786        throws NumberIsTooSmallException, OutOfRangeException;
    787
    788        /**
    789         * Visit (but don't change) some matrix entries using the fastest possible order.
    790         * <p>The fastest walking order depends on the exact matrix class. It may be
    791         * different from traditional row or column orders.</p>
    792         * @param visitor visitor used to process all matrix entries
    793         * @param startRow Initial row index
    794         * @param endRow Final row index (inclusive)
    795         * @param startColumn Initial column index
    796         * @param endColumn Final column index (inclusive)
    797         * @throws NumberIsTooSmallException if {@code endRow < startRow} or
    798         * {@code endColumn < startColumn}.
    799         * @throws OutOfRangeException if the indices are not valid.
    800         * @see #walkInRowOrder(FieldMatrixChangingVisitor)
    801         * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
    802         * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
    803         * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    804         * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
    805         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
    806         * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
    807         * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
    808         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
    809         * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
    810         * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
    811         * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
    812         * of the walk
    813         */
    814        T walkInOptimizedOrder(FieldMatrixPreservingVisitor<T> visitor,
    815                               int startRow, int endRow, int startColumn, int endColumn)
    816        throws NumberIsTooSmallException, OutOfRangeException;
    817    }