← Back to branch summary

~ubuntu-branches/ubuntu/maverick/commons-math/maverick

« back to all changes in this revision

Viewing changes to src/main/java/org/apache/commons/math/linear/FieldMatrix.java

  • Committer: Bazaar Package Importer
  • Author(s): Damien Raude-Morvan
  • Date: 2009-08-22 01:13:25 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20090822011325-hi4peq1ua5weguwn
Tags: 2.0-1
* New upstream release.
* Set Maintainer field to Debian Java Team
* Add myself as Uploaders
* Switch to Quilt patch system:
  - Refresh all patchs
  - Remove B-D on dpatch, Add B-D on quilt
  - Include patchsys-quilt.mk in debian/rules
* Bump Standards-Version to 3.8.3:
  - Add a README.source to describe patch system
* Maven POMs:
  - Add a Build-Depends-Indep dependency on maven-repo-helper
  - Use mh_installpom and mh_installjar to install the POM and the jar to the
    Maven repository
* Use default-jdk/jre:
  - Depends on java5-runtime-headless
  - Build-Depends on default-jdk
  - Use /usr/lib/jvm/default-java as JAVA_HOME
* Move api documentation to /usr/share/doc/libcommons-math-java/api
* Build-Depends on junit4 instead of junit

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/main/java/org/apache/commons/math/linear/FieldMatrix.java
 
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
}