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    }