ostore.oil
Class Matrix

java.lang.Object
  |
  +--ostore.oil.Matrix
All Implemented Interfaces:
Cloneable, QuickSerializable

public class Matrix
extends Object
implements Cloneable, QuickSerializable

A sparse array of Arrays. Elements are indexed by arbitrary QuickSerializable objects.

This class is synchronized.

Version:
$Id: Matrix.java,v 1.5 2001/11/28 23:03:15 geels Exp $
Author:
Dennis Geels

Field Summary
protected  HashMap map
          The internal storage mechanism.
 
Constructor Summary
Matrix()
          Construct a new Matrix.
Matrix(byte[] data, int[] offset)
          Implied from ostore.util.QuickSerializable interface Construct an Matrix from its QuickSerializable form.
Matrix(byte[] data, int[] offset, HashMap decompression_map, HashMap row_decompression_map)
          Construct an Matrix from its QuickSerializable form.
 
Method Summary
 void add(Matrix addend)
          Adds the contents of the specified Matrix to this one.
 void add(QuickSerializable id, Array addend)
          Adds the specified Array to this Matrix.
 Object clone()
          Performs a slightly deeper copy than Object.clone.
 boolean contains(QuickSerializable id)
          Shows whether the specified ID is explicitly stored in this Matrix.
 int full_size()
          Returns the full size of the Matrix.
 Array get(QuickSerializable id)
          Returns the Array indexed by the specified ID.
 Iterator ids()
          Returns an Iterator over the IDs stored explicitly in this Matrix.
static void max(double[][] matrix, int[][] indices)
          Finds the indices of the largest elements of the specified Matrix.
 Array put(QuickSerializable id, Array row)
          Places the specified mapping into this Matrix.
 int size()
          Returns the size of the Matrix.
 void to_bytes(byte[] data, int[] offset)
          Store the object in its "on the wire" form in the byte array data, starting at index offset [0], and increment offset [0] by the number of bytes written; if data == null, increment offset [0] by the number of bytes that would have been written otherwise.
 void to_bytes(byte[] data, int[] offset, HashMap compression_map, HashMap row_compression_map)
          Stores this Matrix in its QuickSerializable format, much like to_bytes(byte[], int[]), using an index over the IDs for compression.
 String toString()
          Produce a human-readable version of this Matrix.
static String toString(double[][] matrix)
          Returns a human-readable representation of the specified matrix.
static String toString(double[][] matrix, int[][] indices)
          Returns a human-readable representation of the specified matrix, with indices.
static double[][] transpose(double[][] matrix)
          Returns the transpose of the specified matrix.
 int type_code()
          Returns the unique integer associated with this class in the TypeTable.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

map

protected HashMap map
The internal storage mechanism.
Constructor Detail

Matrix

public Matrix()
Construct a new Matrix.

Matrix

public Matrix(byte[] data,
              int[] offset)
       throws QSException
Implied from ostore.util.QuickSerializable interface Construct an Matrix from its QuickSerializable form.
Parameters:
data - The matrix containing the serialized form.
offset - The start index in data. On return, contains the first unused offset.

Matrix

public Matrix(byte[] data,
              int[] offset,
              HashMap decompression_map,
              HashMap row_decompression_map)
       throws QSException
Construct an Matrix from its QuickSerializable form. See to_bytes(byte[], int[], HashMap, HashMap) for more details.
Parameters:
data - The matrix containing the serialized form.
offset - The start index in data. On return, contains the first unused offset.
decompression_map - An Integer->QuickSerializable mapping for decompressing IDs.
row_decompression_map - An Integer->QuickSerializable mapping for decompressing IDs within rows.
Method Detail

toString

public static String toString(double[][] matrix)
Returns a human-readable representation of the specified matrix.
Parameters:
matrix - the matrix to print
Returns:
a human-readable representation of the specified matrix.

toString

public static String toString(double[][] matrix,
                              int[][] indices)
Returns a human-readable representation of the specified matrix, with indices. This method should be used to print sub-matrices, or simply because the indices are helpful. This method calls Array.toString(double[], int[]) on each row of the matrix.
Parameters:
matrix - the matrix to print
indices - the indices, in order, of the elements to print
Returns:
a human-readable representation of the specified matrix.
Throws:
IllegalArgumentException - if width of indices greater than width of corresponding row of matrix.
See Also:
max(double[][], int[][])

transpose

public static final double[][] transpose(double[][] matrix)
Returns the transpose of the specified matrix. The width of the new matrix is the length of the specified matrix, and vice versa. WARNING This method is in some ways even more expensive than toString.
Parameters:
matrix - the matrix to flip
Returns:
the transpose of the specified matrix.

max

public static void max(double[][] matrix,
                       int[][] indices)
Finds the indices of the largest elements of the specified Matrix. This method calls Array.max(double[], int[]) on each row of the matrix. Thus the width of indices determines the number of top elements of each row to find. To find the top elements of each column (instead of by row) use transpose to flip the matrix first.
Parameters:
matrix - the matrix to check
indices - the matrix into which to put the (sorted) indices of the largest elements of matrix.
Throws:
IllegalArgumentException - if width of indices greater than width of corresponding row of matrix.

size

public int size()
Returns the size of the Matrix.
Returns:
the number of Arrays stored in this Matrix.

full_size

public int full_size()
Returns the full size of the Matrix.
Returns:
the total number of elements explicitly stored in the Arrays stored in this Matrix.

ids

public Iterator ids()
Returns an Iterator over the IDs stored explicitly in this Matrix.
Returns:
a HashIterator over the backing map's keys.

contains

public boolean contains(QuickSerializable id)
Shows whether the specified ID is explicitly stored in this Matrix.
Parameters:
id - The unique ID for the row to check.
Returns:
true iff id is explicitly mapped to a row.

get

public Array get(QuickSerializable id)
Returns the Array indexed by the specified ID.
Parameters:
id - The unique ID for a row of this Matrix.
Returns:
the Array stored under id, or null if the ID is unknown.

put

public Array put(QuickSerializable id,
                 Array row)
Places the specified mapping into this Matrix. If id already maps to an Array, the old one is replaced and returned.
Parameters:
id - The index under which to store this row.
row - The Array to store for this index.
Returns:
the Array previously mapped by this index, or null if the ID is unknown.

add

public void add(Matrix addend)
Adds the contents of the specified Matrix to this one. Arrays for known IDs are added to the current rows. Unknown IDs are inserted directly (not cloned).
Parameters:
addend - The Matrix whose contents to add

add

public void add(QuickSerializable id,
                Array addend)
Adds the specified Array to this Matrix. If the ID is known, the Array is added to the current row. Otherwise it is cloned and inserted.
Parameters:
id - The unique ID for addend
addend - The Array to add

clone

public Object clone()
Performs a slightly deeper copy than Object.clone. The mapping is cloned, so the new Matrix can be modified independently of this one. Neither the IDs nor the rows are themselves cloned.
Overrides:
clone in class Object
Returns:
a new Matrix with the same set of elements as this one.

toString

public String toString()
Produce a human-readable version of this Matrix. This method consumes O(full_size()) time and String length.
Overrides:
toString in class Object
Returns:
a String of < id:row > pairs.

to_bytes

public void to_bytes(byte[] data,
                     int[] offset)
Description copied from interface: QuickSerializable
Store the object in its "on the wire" form in the byte array data, starting at index offset [0], and increment offset [0] by the number of bytes written; if data == null, increment offset [0] by the number of bytes that would have been written otherwise.
Specified by:
to_bytes in interface QuickSerializable
Following copied from interface: ostore.util.QuickSerializable
Parameters:
data - The byte array to store into, or null.
offset - A single element array whose first element is the index in data to begin writing at on function entry, and which on function exit has been incremented by the number of bytes written.

to_bytes

public void to_bytes(byte[] data,
                     int[] offset,
                     HashMap compression_map,
                     HashMap row_compression_map)
Stores this Matrix in its QuickSerializable format, much like to_bytes(byte[], int[]), using an index over the IDs for compression. This method uses the specified mappings to replace each ID with an associated integer. This method allows the (possibly large) IDs to be stored only once, saving significant storage space.

If this Matrix contains an ID not present in the compression_maps, it adds a new mapping, using the next available number. Therefore the maps should not be serialized until after this Matrix, to avoid losing the added mappings.

Parameters:
data - The array into which to store, or null.
offset - The index in data at which to start. On return, contains the first unused offset.
compression_map - A QuickSerializable->Integer mapping for ID compression.
row_compression_map - A QuickSerializable->Integer mapping for ID compression within rows.

type_code

public final int type_code()
Description copied from interface: QuickSerializable
Returns the unique integer associated with this class in the TypeTable.
Specified by:
type_code in interface QuickSerializable
Following copied from interface: ostore.util.QuickSerializable
Returns:
an integer unique to this class