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