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