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
024 /**
025 * Interface defining field-valued matrix with basic algebraic operations.
026 * <p>
027 * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
028 * returns the element in the first row, first column of the matrix.</p>
029 *
030 * @param <T> the type of the field elements
031 * @version $Revision: 811786 $ $Date: 2009-09-06 05:36:08 -0400 (Sun, 06 Sep 2009) $
032 */
033 public interface FieldMatrix<T extends FieldElement<T>> extends AnyMatrix {
034
035 /**
036 * Get the type of field elements of the matrix.
037 * @return type of field elements of the matrix
038 */
039 Field<T> getField();
040
041 /**
042 * Create a new FieldMatrix<T> of the same type as the instance with the supplied
043 * row and column dimensions.
044 *
045 * @param rowDimension the number of rows in the new matrix
046 * @param columnDimension the number of columns in the new matrix
047 * @return a new matrix of the same type as the instance
048 * @throws IllegalArgumentException if row or column dimension is not positive
049 * @since 2.0
050 */
051 FieldMatrix<T> createMatrix(final int rowDimension, final int columnDimension);
052
053 /**
054 * Returns a (deep) copy of this.
055 *
056 * @return matrix copy
057 */
058 FieldMatrix<T> copy();
059
060 /**
061 * Compute the sum of this and m.
062 *
063 * @param m matrix to be added
064 * @return this + m
065 * @throws IllegalArgumentException if m is not the same size as this
066 */
067 FieldMatrix<T> add(FieldMatrix<T> m) throws IllegalArgumentException;
068
069 /**
070 * Compute this minus m.
071 *
072 * @param m matrix to be subtracted
073 * @return this + m
074 * @throws IllegalArgumentException if m is not the same size as this
075 */
076 FieldMatrix<T> subtract(FieldMatrix<T> m) throws IllegalArgumentException;
077
078 /**
079 * Returns the result of adding d to each entry of this.
080 *
081 * @param d value to be added to each entry
082 * @return d + this
083 */
084 FieldMatrix<T> scalarAdd(T d);
085
086 /**
087 * Returns the result multiplying each entry of this by d.
088 *
089 * @param d value to multiply all entries by
090 * @return d * this
091 */
092 FieldMatrix<T> scalarMultiply(T d);
093
094 /**
095 * Returns the result of postmultiplying this by m.
096 *
097 * @param m matrix to postmultiply by
098 * @return this * m
099 * @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 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 }