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