View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math.linear;
19  
20  
21  import org.apache.commons.math.Field;
22  import org.apache.commons.math.FieldElement;
23  
24  /**
25   * Interface defining field-valued matrix with basic algebraic operations.
26   * <p>
27   * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
28   * returns the element in the first row, first column of the matrix.</p>
29   * 
30   * @param <T> the type of the field elements
31   * @version $Revision: 781122 $ $Date: 2009-06-02 14:53:23 -0400 (Tue, 02 Jun 2009) $
32   */
33  public interface FieldMatrix<T extends FieldElement<T>> extends AnyMatrix {
34  
35      /**
36       * Get the type of field elements of the matrix.
37       * @return type of field elements of the matrix
38       */
39      Field<T> getField();
40  
41      /**
42       * Create a new FieldMatrix<T> of the same type as the instance with the supplied
43       * row and column dimensions.
44       *
45       * @param rowDimension  the number of rows in the new matrix
46       * @param columnDimension  the number of columns in the new matrix
47       * @return a new matrix of the same type as the instance
48       * @throws IllegalArgumentException if row or column dimension is not positive
49       * @since 2.0
50       */
51      FieldMatrix<T> createMatrix(final int rowDimension, final int columnDimension);
52  
53      /**
54       * Returns a (deep) copy of this.
55       *
56       * @return matrix copy
57       */
58      FieldMatrix<T> copy();
59  
60      /**
61       * Compute the sum of this and m.
62       *
63       * @param m    matrix to be added
64       * @return     this + m
65       * @throws  IllegalArgumentException if m is not the same size as this
66       */
67      FieldMatrix<T> add(FieldMatrix<T> m) throws IllegalArgumentException;
68  
69      /**
70       * Compute this minus m.
71       *
72       * @param m    matrix to be subtracted
73       * @return     this + m
74       * @throws  IllegalArgumentException if m is not the same size as this
75       */
76      FieldMatrix<T> subtract(FieldMatrix<T> m) throws IllegalArgumentException;
77  
78       /**
79       * Returns the result of adding d to each entry of this.
80       *
81       * @param d    value to be added to each entry
82       * @return     d + this
83       */
84      FieldMatrix<T> scalarAdd(T d);
85  
86      /**
87       * Returns the result multiplying each entry of this by d.
88       *
89       * @param d    value to multiply all entries by
90       * @return     d * this
91       */
92      FieldMatrix<T> scalarMultiply(T d);
93  
94      /**
95       * Returns the result of postmultiplying this by m.
96       *
97       * @param m    matrix to postmultiply by
98       * @return     this * m
99       * @throws     IllegalArgumentException
100      *             if columnDimension(this) != rowDimension(m)
101      */
102     FieldMatrix<T> multiply(FieldMatrix<T> m) throws IllegalArgumentException;
103 
104     /**
105      * Returns the result premultiplying this by <code>m</code>.
106      * @param m    matrix to premultiply by
107      * @return     m * this
108      * @throws     IllegalArgumentException
109      *             if rowDimension(this) != columnDimension(m)
110      */
111     public FieldMatrix<T> preMultiply(FieldMatrix<T> m) throws IllegalArgumentException;
112 
113     /**
114      * Returns matrix entries as a two-dimensional array.
115      *
116      * @return    2-dimensional array of entries
117      */
118     T[][] getData();
119 
120     /**
121      * Gets a submatrix. Rows and columns are indicated
122      * counting from 0 to n-1.
123      *
124      * @param startRow Initial row index
125      * @param endRow Final row index (inclusive)
126      * @param startColumn Initial column index
127      * @param endColumn Final column index (inclusive)
128      * @return The subMatrix containing the data of the
129      *         specified rows and columns
130      * @exception MatrixIndexException  if the indices are not valid
131      */
132    FieldMatrix<T> getSubMatrix(int startRow, int endRow, int startColumn, int endColumn)
133        throws MatrixIndexException;
134    
135    /**
136     * Gets a submatrix. Rows and columns are indicated
137     * counting from 0 to n-1.
138     *
139     * @param selectedRows Array of row indices.
140     * @param selectedColumns Array of column indices.
141     * @return The subMatrix containing the data in the
142     *         specified rows and columns
143     * @exception MatrixIndexException if row or column selections are not valid
144     */
145    FieldMatrix<T> getSubMatrix(int[] selectedRows, int[] selectedColumns)
146        throws MatrixIndexException;
147 
148    /**
149     * Copy a submatrix. Rows and columns are indicated
150     * counting from 0 to n-1.
151     *
152     * @param startRow Initial row index
153     * @param endRow Final row index (inclusive)
154     * @param startColumn Initial column index
155     * @param endColumn Final column index (inclusive)
156     * @param destination The arrays where the submatrix data should be copied
157     * (if larger than rows/columns counts, only the upper-left part will be used)
158     * @exception MatrixIndexException if the indices are not valid
159     * @exception IllegalArgumentException if the destination array is too small
160     */
161   void copySubMatrix(int startRow, int endRow, int startColumn, int endColumn,
162                      T[][] destination)
163       throws MatrixIndexException, IllegalArgumentException;
164   
165   /**
166    * Copy a submatrix. Rows and columns are indicated
167    * counting from 0 to n-1.
168    *
169     * @param selectedRows Array of row indices.
170     * @param selectedColumns Array of column indices.
171    * @param destination The arrays where the submatrix data should be copied
172    * (if larger than rows/columns counts, only the upper-left part will be used)
173    * @exception MatrixIndexException if the indices are not valid
174    * @exception IllegalArgumentException if the destination array is too small
175    */
176   void copySubMatrix(int[] selectedRows, int[] selectedColumns, T[][] destination)
177       throws MatrixIndexException, IllegalArgumentException;
178  
179    /**
180     * Replace the submatrix starting at <code>row, column</code> using data in
181     * the input <code>subMatrix</code> array. Indexes are 0-based.
182     * <p> 
183     * Example:<br>
184     * Starting with <pre>
185     * 1  2  3  4
186     * 5  6  7  8
187     * 9  0  1  2
188     * </pre>
189     * and <code>subMatrix = {{3, 4} {5,6}}</code>, invoking 
190     * <code>setSubMatrix(subMatrix,1,1))</code> will result in <pre>
191     * 1  2  3  4
192     * 5  3  4  8
193     * 9  5  6  2
194     * </pre></p>
195     * 
196     * @param subMatrix  array containing the submatrix replacement data
197     * @param row  row coordinate of the top, left element to be replaced
198     * @param column  column coordinate of the top, left element to be replaced
199     * @throws MatrixIndexException  if subMatrix does not fit into this 
200     *    matrix from element in (row, column) 
201     * @throws IllegalArgumentException if <code>subMatrix</code> is not rectangular
202     *  (not all rows have the same length) or empty
203     * @throws NullPointerException if <code>subMatrix</code> is null
204     * @since 2.0
205     */
206    void setSubMatrix(T[][] subMatrix, int row, int column) 
207        throws MatrixIndexException;
208 
209    /**
210     * Returns the entries in row number <code>row</code>
211     * as a row matrix.  Row indices start at 0.
212     *
213     * @param row the row to be fetched
214     * @return row matrix
215     * @throws MatrixIndexException if the specified row index is invalid
216     */
217    FieldMatrix<T> getRowMatrix(int row) throws MatrixIndexException;
218    
219    /**
220     * Sets the entries in row number <code>row</code>
221     * as a row matrix.  Row indices start at 0.
222     *
223     * @param row the row to be set
224     * @param matrix row matrix (must have one row and the same number of columns
225     * as the instance)
226     * @throws MatrixIndexException if the specified row index is invalid
227     * @throws InvalidMatrixException if the matrix dimensions do not match one
228     * instance row
229     */
230    void setRowMatrix(int row, FieldMatrix<T> matrix)
231        throws MatrixIndexException, InvalidMatrixException;
232    
233    /**
234     * Returns the entries in column number <code>column</code>
235     * as a column matrix.  Column indices start at 0.
236     *
237     * @param column the column to be fetched
238     * @return column matrix
239     * @throws MatrixIndexException if the specified column index is invalid
240     */
241    FieldMatrix<T> getColumnMatrix(int column) throws MatrixIndexException;
242 
243    /**
244     * Sets the entries in column number <code>column</code>
245     * as a column matrix.  Column indices start at 0.
246     *
247     * @param column the column to be set
248     * @param matrix column matrix (must have one column and the same number of rows
249     * as the instance)
250     * @throws MatrixIndexException if the specified column index is invalid
251     * @throws InvalidMatrixException if the matrix dimensions do not match one
252     * instance column
253     */
254    void setColumnMatrix(int column, FieldMatrix<T> matrix)
255        throws MatrixIndexException, InvalidMatrixException;
256    
257    /**
258     * Returns the entries in row number <code>row</code>
259     * as a vector.  Row indices start at 0.
260     *
261     * @param row the row to be fetched
262     * @return row vector
263     * @throws MatrixIndexException if the specified row index is invalid
264     */
265    FieldVector<T> getRowVector(int row) throws MatrixIndexException;
266 
267    /**
268     * Sets the entries in row number <code>row</code>
269     * as a vector.  Row indices start at 0.
270     *
271     * @param row the row to be set
272     * @param vector row vector (must have the same number of columns
273     * as the instance)
274     * @throws MatrixIndexException if the specified row index is invalid
275     * @throws InvalidMatrixException if the vector dimension does not match one
276     * instance row
277     */
278    void setRowVector(int row, FieldVector<T> vector)
279        throws MatrixIndexException, InvalidMatrixException;
280    
281    /**
282     * Returns the entries in column number <code>column</code>
283     * as a vector.  Column indices start at 0.
284     *
285     * @param column the column to be fetched
286     * @return column vector
287     * @throws MatrixIndexException if the specified column index is invalid
288     */
289    FieldVector<T> getColumnVector(int column) throws MatrixIndexException;
290 
291    /**
292     * Sets the entries in column number <code>column</code>
293     * as a vector.  Column indices start at 0.
294     *
295     * @param column the column to be set
296     * @param vector column vector (must have the same number of rows as the instance)
297     * @throws MatrixIndexException if the specified column index is invalid
298     * @throws InvalidMatrixException if the vector dimension does not match one
299     * instance column
300     */
301    void setColumnVector(int column, FieldVector<T> vector)
302        throws MatrixIndexException, InvalidMatrixException;
303    
304     /**
305      * Returns the entries in row number <code>row</code> as an array.
306      * <p>
307      * Row indices start at 0.  A <code>MatrixIndexException</code> is thrown
308      * unless <code>0 <= row < rowDimension.</code></p>
309      *
310      * @param row the row to be fetched
311      * @return array of entries in the row
312      * @throws MatrixIndexException if the specified row index is not valid
313      */
314     T[] getRow(int row) throws MatrixIndexException;
315 
316     /**
317      * Sets the entries in row number <code>row</code>
318      * as a row matrix.  Row indices start at 0.
319      *
320      * @param row the row to be set
321      * @param array row matrix (must have the same number of columns as the instance)
322      * @throws MatrixIndexException if the specified row index is invalid
323      * @throws InvalidMatrixException if the array size does not match one
324      * instance row
325      */
326     void setRow(int row, T[] array)
327         throws MatrixIndexException, InvalidMatrixException;
328     
329     /**
330      * Returns the entries in column number <code>col</code> as an array.
331      * <p>
332      * Column indices start at 0.  A <code>MatrixIndexException</code> is thrown
333      * unless <code>0 <= column < columnDimension.</code></p>
334      *
335      * @param column the column to be fetched
336      * @return array of entries in the column
337      * @throws MatrixIndexException if the specified column index is not valid
338      */
339     T[] getColumn(int column) throws MatrixIndexException;
340 
341     /**
342      * Sets the entries in column number <code>column</code>
343      * as a column matrix.  Column indices start at 0.
344      *
345      * @param column the column to be set
346      * @param array column array (must have the same number of rows as the instance)
347      * @throws MatrixIndexException if the specified column index is invalid
348      * @throws InvalidMatrixException if the array size does not match one
349      * instance column
350      */
351     void setColumn(int column, T[] array)
352         throws MatrixIndexException, InvalidMatrixException;
353     
354     /**
355      * Returns the entry in the specified row and column.
356      * <p>
357      * Row and column indices start at 0 and must satisfy 
358      * <ul>
359      * <li><code>0 <= row < rowDimension</code></li>
360      * <li><code> 0 <= column < columnDimension</code></li>
361      * </ul>
362      * otherwise a <code>MatrixIndexException</code> is thrown.</p>
363      * 
364      * @param row  row location of entry to be fetched
365      * @param column  column location of entry to be fetched
366      * @return matrix entry in row,column
367      * @throws MatrixIndexException if the row or column index is not valid
368      */
369     T getEntry(int row, int column) throws MatrixIndexException;
370 
371     /**
372      * Set the entry in the specified row and column.
373      * <p>
374      * Row and column indices start at 0 and must satisfy 
375      * <ul>
376      * <li><code>0 <= row < rowDimension</code></li>
377      * <li><code> 0 <= column < columnDimension</code></li>
378      * </ul>
379      * otherwise a <code>MatrixIndexException</code> is thrown.</p>
380      * 
381      * @param row  row location of entry to be set
382      * @param column  column location of entry to be set
383      * @param value matrix entry to be set in row,column
384      * @throws MatrixIndexException if the row or column index is not valid
385      * @since 2.0
386      */
387     void setEntry(int row, int column, T value) throws MatrixIndexException;
388 
389     /**
390      * Change an entry in the specified row and column.
391      * <p>
392      * Row and column indices start at 0 and must satisfy 
393      * <ul>
394      * <li><code>0 <= row < rowDimension</code></li>
395      * <li><code> 0 <= column < columnDimension</code></li>
396      * </ul>
397      * otherwise a <code>MatrixIndexException</code> is thrown.</p>
398      * 
399      * @param row  row location of entry to be set
400      * @param column  column location of entry to be set
401      * @param increment value to add to the current matrix entry in row,column
402      * @throws MatrixIndexException if the row or column index is not valid
403      * @since 2.0
404      */
405     void addToEntry(int row, int column, T increment) throws MatrixIndexException;
406 
407     /**
408      * Change an entry in the specified row and column.
409      * <p>
410      * Row and column indices start at 0 and must satisfy 
411      * <ul>
412      * <li><code>0 <= row < rowDimension</code></li>
413      * <li><code> 0 <= column < columnDimension</code></li>
414      * </ul>
415      * otherwise a <code>MatrixIndexException</code> is thrown.</p>
416      * 
417      * @param row  row location of entry to be set
418      * @param column  column location of entry to be set
419      * @param factor multiplication factor for the current matrix entry in row,column
420      * @throws MatrixIndexException if the row or column index is not valid
421      * @since 2.0
422      */
423     void multiplyEntry(int row, int column, T factor) throws MatrixIndexException;
424 
425     /**
426      * Returns the transpose of this matrix.
427      *
428      * @return transpose matrix
429      */
430     FieldMatrix<T> transpose();
431 
432     /**
433      * Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
434      * trace</a> of the matrix (the sum of the elements on the main diagonal).
435      *
436      * @return trace
437      * @throws NonSquareMatrixException if the matrix is not square
438      */
439     T getTrace() throws NonSquareMatrixException;
440 
441     /**
442      * Returns the result of multiplying this by the vector <code>v</code>.
443      *
444      * @param v the vector to operate on
445      * @return this*v
446      * @throws IllegalArgumentException if columnDimension != v.size()
447      */
448     T[] operate(T[] v) throws IllegalArgumentException;
449 
450     /**
451      * Returns the result of multiplying this by the vector <code>v</code>.
452      *
453      * @param v the vector to operate on
454      * @return this*v
455      * @throws IllegalArgumentException if columnDimension != v.size()
456      */
457     FieldVector<T> operate(FieldVector<T> v) throws IllegalArgumentException;
458 
459     /**
460      * Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
461      *
462      * @param v the row vector to premultiply by
463      * @return v*this
464      * @throws IllegalArgumentException if rowDimension != v.size()
465      */
466     T[] preMultiply(T[] v) throws IllegalArgumentException;
467 
468     /**
469      * Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
470      *
471      * @param v the row vector to premultiply by
472      * @return v*this
473      * @throws IllegalArgumentException if rowDimension != v.size()
474      */
475     FieldVector<T> preMultiply(FieldVector<T> v) throws IllegalArgumentException;
476 
477     /**
478      * Visit (and possibly change) all matrix entries in row order.
479      * <p>Row order starts at upper left and iterating through all elements
480      * of a row from left to right before going to the leftmost element
481      * of the next row.</p>
482      * @param visitor visitor used to process all matrix entries
483      * @exception  MatrixVisitorException if the visitor cannot process an entry
484      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
485      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
486      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
487      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
488      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
489      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
490      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
491      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
492      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
493      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
494      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
495      * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
496      * of the walk
497      */
498     T walkInRowOrder(FieldMatrixChangingVisitor<T> visitor)
499         throws MatrixVisitorException;
500 
501     /**
502      * Visit (but don't change) all matrix entries in row order.
503      * <p>Row order starts at upper left and iterating through all elements
504      * of a row from left to right before going to the leftmost element
505      * of the next row.</p>
506      * @param visitor visitor used to process all matrix entries
507      * @exception  MatrixVisitorException if the visitor cannot process an entry
508      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
509      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
510      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
511      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
512      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
513      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
514      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
515      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
516      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
517      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
518      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
519      * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
520      * of the walk
521      */
522     T walkInRowOrder(FieldMatrixPreservingVisitor<T> visitor)
523         throws MatrixVisitorException;
524 
525     /**
526      * Visit (and possibly change) some matrix entries in row order.
527      * <p>Row order starts at upper left and iterating through all elements
528      * of a row from left to right before going to the leftmost element
529      * of the next row.</p>
530      * @param visitor visitor used to process all matrix entries
531      * @param startRow Initial row index
532      * @param endRow Final row index (inclusive)
533      * @param startColumn Initial column index
534      * @param endColumn Final column index
535      * @exception  MatrixVisitorException if the visitor cannot process an entry
536      * @exception MatrixIndexException  if the indices are not valid
537      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
538      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
539      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
540      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
541      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
542      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
543      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
544      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
545      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
546      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
547      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
548      * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
549      * of the walk
550      */
551     T walkInRowOrder(FieldMatrixChangingVisitor<T> visitor,
552                           int startRow, int endRow, int startColumn, int endColumn)
553         throws MatrixIndexException, MatrixVisitorException;
554 
555     /**
556      * Visit (but don't change) some matrix entries in row order.
557      * <p>Row order starts at upper left and iterating through all elements
558      * of a row from left to right before going to the leftmost element
559      * of the next row.</p>
560      * @param visitor visitor used to process all matrix entries
561      * @param startRow Initial row index
562      * @param endRow Final row index (inclusive)
563      * @param startColumn Initial column index
564      * @param endColumn Final column index
565      * @exception  MatrixVisitorException if the visitor cannot process an entry
566      * @exception MatrixIndexException  if the indices are not valid
567      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
568      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
569      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
570      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
571      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
572      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
573      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
574      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
575      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
576      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
577      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
578      * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
579      * of the walk
580      */
581     T walkInRowOrder(FieldMatrixPreservingVisitor<T> visitor,
582                           int startRow, int endRow, int startColumn, int endColumn)
583         throws MatrixIndexException, MatrixVisitorException;
584 
585     /**
586      * Visit (and possibly change) all matrix entries in column order.
587      * <p>Column order starts at upper left and iterating through all elements
588      * of a column from top to bottom before going to the topmost element
589      * of the next column.</p>
590      * @param visitor visitor used to process all matrix entries
591      * @exception  MatrixVisitorException if the visitor cannot process an entry
592      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
593      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
594      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
595      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
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 FieldMatrixChangingVisitor#end()} at the end
604      * of the walk
605      */
606     T walkInColumnOrder(FieldMatrixChangingVisitor<T> visitor)
607         throws MatrixVisitorException;
608 
609     /**
610      * Visit (but don't change) all matrix entries in column order.
611      * <p>Column order starts at upper left and iterating through all elements
612      * of a column from top to bottom before going to the topmost element
613      * of the next column.</p>
614      * @param visitor visitor used to process all matrix entries
615      * @exception  MatrixVisitorException if the visitor cannot process an entry
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(FieldMatrixChangingVisitor)
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 FieldMatrixPreservingVisitor#end()} at the end
628      * of the walk
629      */
630     T walkInColumnOrder(FieldMatrixPreservingVisitor<T> visitor)
631         throws MatrixVisitorException;
632 
633     /**
634      * Visit (and possibly change) some matrix entries in column order.
635      * <p>Column order starts at upper left and iterating through all elements
636      * of a column from top to bottom before going to the topmost element
637      * of the next column.</p>
638      * @param visitor visitor used to process all matrix entries
639      * @param startRow Initial row index
640      * @param endRow Final row index (inclusive)
641      * @param startColumn Initial column index
642      * @param endColumn Final column index
643      * @exception  MatrixVisitorException if the visitor cannot process an entry
644      * @exception MatrixIndexException  if the indices are not valid
645      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
646      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
647      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
648      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
649      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
650      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
651      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
652      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
653      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
654      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
655      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
656      * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
657      * of the walk
658      */
659     T walkInColumnOrder(FieldMatrixChangingVisitor<T> visitor,
660                              int startRow, int endRow, int startColumn, int endColumn)
661         throws MatrixIndexException, MatrixVisitorException;
662 
663     /**
664      * Visit (but don't change) some matrix entries in column order.
665      * <p>Column order starts at upper left and iterating through all elements
666      * of a column from top to bottom before going to the topmost element
667      * of the next column.</p>
668      * @param visitor visitor used to process all matrix entries
669      * @param startRow Initial row index
670      * @param endRow Final row index (inclusive)
671      * @param startColumn Initial column index
672      * @param endColumn Final column index
673      * @exception  MatrixVisitorException if the visitor cannot process an entry
674      * @exception MatrixIndexException  if the indices are not valid
675      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
676      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
677      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
678      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
679      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
680      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
681      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
682      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
683      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
684      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
685      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
686      * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
687      * of the walk
688      */
689     T walkInColumnOrder(FieldMatrixPreservingVisitor<T> visitor,
690                              int startRow, int endRow, int startColumn, int endColumn)
691         throws MatrixIndexException, MatrixVisitorException;
692 
693     /**
694      * Visit (and possibly change) all matrix entries using the fastest possible order.
695      * <p>The fastest walking order depends on the exact matrix class. It may be
696      * different from traditional row or column orders.</p>
697      * @param visitor visitor used to process all matrix entries
698      * @exception  MatrixVisitorException if the visitor cannot process an entry
699      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
700      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
701      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
702      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
703      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
704      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
705      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
706      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
707      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
708      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
709      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
710      * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
711      * of the walk
712      */
713     T walkInOptimizedOrder(FieldMatrixChangingVisitor<T> visitor)
714         throws MatrixVisitorException;
715 
716     /**
717      * Visit (but don't 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      * @exception  MatrixVisitorException if the visitor cannot process an entry
722      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
723      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
724      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
725      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
726      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
727      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
728      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
729      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
730      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
731      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
732      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
733      * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
734      * of the walk
735      */
736     T walkInOptimizedOrder(FieldMatrixPreservingVisitor<T> visitor)
737         throws MatrixVisitorException;
738 
739     /**
740      * Visit (and possibly change) some matrix entries using the fastest possible order.
741      * <p>The fastest walking order depends on the exact matrix class. It may be
742      * different from traditional row or column orders.</p>
743      * @param visitor visitor used to process all matrix entries
744      * @param startRow Initial row index
745      * @param endRow Final row index (inclusive)
746      * @param startColumn Initial column index
747      * @param endColumn Final column index (inclusive)
748      * @exception  MatrixVisitorException if the visitor cannot process an entry
749      * @exception MatrixIndexException  if the indices are not valid
750      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
751      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
752      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
753      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
754      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
755      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
756      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
757      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
758      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
759      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
760      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor, int, int, int, int)
761      * @return the value returned by {@link FieldMatrixChangingVisitor#end()} at the end
762      * of the walk
763      */
764     T walkInOptimizedOrder(FieldMatrixChangingVisitor<T> visitor,
765                                 int startRow, int endRow, int startColumn, int endColumn)
766         throws MatrixIndexException, MatrixVisitorException;
767 
768     /**
769      * Visit (but don't change) some matrix entries using the fastest possible order.
770      * <p>The fastest walking order depends on the exact matrix class. It may be
771      * different from traditional row or column orders.</p>
772      * @param visitor visitor used to process all matrix entries
773      * @param startRow Initial row index
774      * @param endRow Final row index (inclusive)
775      * @param startColumn Initial column index
776      * @param endColumn Final column index (inclusive)
777      * @exception  MatrixVisitorException if the visitor cannot process an entry
778      * @exception MatrixIndexException  if the indices are not valid
779      * @see #walkInRowOrder(FieldMatrixChangingVisitor)
780      * @see #walkInRowOrder(FieldMatrixPreservingVisitor)
781      * @see #walkInRowOrder(FieldMatrixChangingVisitor, int, int, int, int)
782      * @see #walkInRowOrder(FieldMatrixPreservingVisitor, int, int, int, int)
783      * @see #walkInColumnOrder(FieldMatrixChangingVisitor)
784      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor)
785      * @see #walkInColumnOrder(FieldMatrixChangingVisitor, int, int, int, int)
786      * @see #walkInColumnOrder(FieldMatrixPreservingVisitor, int, int, int, int)
787      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor)
788      * @see #walkInOptimizedOrder(FieldMatrixPreservingVisitor)
789      * @see #walkInOptimizedOrder(FieldMatrixChangingVisitor, int, int, int, int)
790      * @return the value returned by {@link FieldMatrixPreservingVisitor#end()} at the end
791      * of the walk
792      */
793     T walkInOptimizedOrder(FieldMatrixPreservingVisitor<T> visitor,
794                                 int startRow, int endRow, int startColumn, int endColumn)
795         throws MatrixIndexException, MatrixVisitorException;
796 
797 }