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