1 /*
2 Copyright � 1999 CERN - European Organization for Nuclear Research.
3 Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose
4 is hereby granted without fee, provided that the above copyright notice appear in all copies and
5 that both that copyright notice and this permission notice appear in supporting documentation.
6 CERN makes no representations about the suitability of this software for any purpose.
7 It is provided "as is" without expressed or implied warranty.
8 */
9 package cern.colt.matrix;
10
11 import cern.colt.matrix.impl.DenseObjectMatrix3D;
12 import cern.colt.matrix.impl.SparseObjectMatrix3D;
13 /**
14 Factory for convenient construction of 3-d matrices holding <tt>Object</tt> cells.
15 Use idioms like <tt>ObjectFactory3D.dense.make(4,4,4)</tt> to construct dense matrices,
16 <tt>ObjectFactory3D.sparse.make(4,4,4)</tt> to construct sparse matrices.
17
18 If the factory is used frequently it might be useful to streamline the notation.
19 For example by aliasing:
20 <table>
21 <td class="PRE">
22 <pre>
23 ObjectFactory3D F = ObjectFactory3D.dense;
24 F.make(4,4,4);
25 ...
26 </pre>
27 </td>
28 </table>
29
30 @author wolfgang.hoschek@cern.ch
31 @version 1.0, 09/24/99
32 */
33 public class ObjectFactory3D extends cern.colt.PersistentObject {
34 /**
35 * A factory producing dense matrices.
36 */
37 public static final ObjectFactory3D dense = new ObjectFactory3D();
38
39 /**
40 * A factory producing sparse matrices.
41 */
42 public static final ObjectFactory3D sparse = new ObjectFactory3D();
43 /**
44 * Makes this class non instantiable, but still let's others inherit from it.
45 */
ObjectFactory3D()46 protected ObjectFactory3D() {}
47 /**
48 * Constructs a matrix with the given cell values.
49 * <tt>values</tt> is required to have the form <tt>values[slice][row][column]</tt>
50 * and have exactly the same number of slices, rows and columns as the receiver.
51 * <p>
52 * The values are copied. So subsequent changes in <tt>values</tt> are not reflected in the matrix, and vice-versa.
53 *
54 * @param values the values to be filled into the cells.
55 * @return <tt>this</tt> (for convenience only).
56 * @throws IllegalArgumentException if <tt>values.length != slices() || for any 0 <= slice < slices(): values[slice].length != rows()</tt>.
57 * @throws IllegalArgumentException if <tt>for any 0 <= column < columns(): values[slice][row].length != columns()</tt>.
58 */
make(Object[][][] values)59 public ObjectMatrix3D make(Object[][][] values) {
60 if (this==sparse) return new SparseObjectMatrix3D(values);
61 return new DenseObjectMatrix3D(values);
62 }
63 /**
64 * Constructs a matrix with the given shape, each cell initialized with zero.
65 */
make(int slices, int rows, int columns)66 public ObjectMatrix3D make(int slices, int rows, int columns) {
67 if (this==sparse) return new SparseObjectMatrix3D(slices,rows,columns);
68 return new DenseObjectMatrix3D(slices,rows,columns);
69 }
70 /**
71 * Constructs a matrix with the given shape, each cell initialized with the given value.
72 */
make(int slices, int rows, int columns, Object initialValue)73 public ObjectMatrix3D make(int slices, int rows, int columns, Object initialValue) {
74 return make(slices,rows,columns).assign(initialValue);
75 }
76 }
77