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