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 }