ostore.oil
Class Array

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

public class Array
extends Object
implements Cloneable, QuickSerializable

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

The Array objects understand the concept of a default element, which is returned for unknown IDs. Using this functionality, an Array could explicitly store only interesting elements, yet appear to store a full array. This class is synchronized.

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

Field Summary
static double DEFAULT_DEFAULT
          The default value for default_elt.
protected  double default_elt
          The value to return for unknown IDs.
protected  HashMap map
          The internal storage mechanism.
 
Constructor Summary
Array()
          Construct a new Array with the default default.
Array(byte[] data, int[] offset)
          Implied from ostore.util.QuickSerializable interface Construct an Array from its QuickSerializable form.
Array(byte[] data, int[] offset, HashMap decompression_map)
          Construct an Array from its QuickSerializable form.
Array(double default_elt)
          Construct a new Array with the specified default.
 
Method Summary
 void add(Array addend)
          Adds the contents of the specified Array to this one.
 void add(QuickSerializable id, double value)
          Adds the specified value to this Array.
 void clear()
          Removes all elements from this Array.
 Object clone()
          Performs a slightly deeper copy than Object.clone.
 boolean contains(QuickSerializable id)
          Shows whether the specified ID is explicitly stored in this Array.
 double get_default()
          Returns the value that this Array should return for unknown IDs.
 double get(QuickSerializable id)
          Returns the value indexed by the specified ID, or the default element if no such value exists.
 Iterator ids()
          Returns an Iterator over the IDs stored explicitly in this Array.
static void max(double[] array, int[] indices)
          Finds the indices of the largest elements of the specified array.
 double put(QuickSerializable id, double value)
          Places the specified mapping into this Array.
 double remove(QuickSerializable id)
          Removes the value indexed by the specified ID
 void set_default(double default_elt)
          Defines the value that this Array should return for unknown IDs.
 int size()
          Returns the size of the Array.
 void sparsify(int new_size)
          Shrinks this Array to new_size, keeping only the largest elements.
 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)
          Stores this Array 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 Array.
static String toString(double[] array)
          Returns a human-readable representation of the specified array.
static String toString(double[] array, int[] indices)
          Returns a human-readable representation of the specified array, with indices.
 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

DEFAULT_DEFAULT

public static final double DEFAULT_DEFAULT
The default value for default_elt. Currently: Double.Nan

default_elt

protected double default_elt
The value to return for unknown IDs.

map

protected HashMap map
The internal storage mechanism.
Constructor Detail

Array

public Array()
Construct a new Array with the default default.

Array

public Array(double default_elt)
Construct a new Array with the specified default.
Parameters:
default_elt - The value to be returned for any unknown IDs

Array

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

Array

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

toString

public static String toString(double[] array)
Returns a human-readable representation of the specified array. Formatting assumes small, positive array values. Other arrays may not look as pretty.
Parameters:
array - the array to print
Returns:
a human-readable representation of the specified array.

toString

public static String toString(double[] array,
                              int[] indices)
Returns a human-readable representation of the specified array, with indices. This method should be used to print sub-arrays, or simply because the indices are helpful Formatting assumes small, positive array values. Other arrays may not look as pretty.
Parameters:
array - the array to print
indices - the indices, in order, of the elements to print
Returns:
a human-readable representation of the specified array.
Throws:
IllegalArgumentException - if indices.length > array.length.
See Also:
max(double[], int[])

max

public static void max(double[] array,
                       int[] indices)
Finds the indices of the largest elements of the specified array. The length of indices determines the number of top elements to find; it must be greater than array.length.
Parameters:
array - the array to check
indices - the array into which to put the (sorted) indices of the largest elements of array.
Throws:
IllegalArgumentException - if indices.length > array.length.

get_default

public double get_default()
Returns the value that this Array should return for unknown IDs.

set_default

public void set_default(double default_elt)
Defines the value that this Array should return for unknown IDs.
Parameters:
default_elt - The value to return for unknown IDs.

size

public int size()
Returns the size of the Array.
Returns:
the number of elements explicitly stored in this Array.

ids

public Iterator ids()
Returns an Iterator over the IDs stored explicitly in this Array.
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 Array.
Parameters:
id - The unique ID for the element to check.
Returns:
true iff id is explicitly mapped to a value.

get

public double get(QuickSerializable id)
Returns the value indexed by the specified ID, or the default element if no such value exists.
Parameters:
id - The unique ID for an element of this Array.
Returns:
the value stored under id, or the default element.

put

public double put(QuickSerializable id,
                  double value)
Places the specified mapping into this Array. If id already maps to a value, the old value is overwritten and returned.
Parameters:
id - The index under which to store this element.
value - The value to store for this index.
Returns:
the value previously mapped by this index, or the default element if there was no previous mapping.

remove

public double remove(QuickSerializable id)
Removes the value indexed by the specified ID
Parameters:
id - The unique ID for an element of this Array.
Returns:
the value stored under id, or the default element.

clear

public void clear()
Removes all elements from this Array. This method does not reset the default return value.

add

public void add(Array addend)
Adds the contents of the specified Array to this one. Values for known IDs are added to their current values. Unknown IDs are added directly (default elements are not considered).
Parameters:
addend - The Array whose contents to add

add

public void add(QuickSerializable id,
                double value)
Adds the specified value to this Array. If the ID is known, the value is added to the current value. Otherwise it is inserted as in put(ostore.util.QuickSerializable, double).
Parameters:
id - The unique ID for value.
value - The value to add.

sparsify

public void sparsify(int new_size)
Shrinks this Array to new_size, keeping only the largest elements. Ties are broken in an arbitrary, non-deterministic fashion.
Parameters:
new_size - The number of elements to keep.

clone

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

toString

public String toString()
Produce a human-readable version of this Array.
Overrides:
toString in class Object
Returns:
a String of < id:value > 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)
Stores this Array in its QuickSerializable format, much like to_bytes(byte[], int[]), using an index over the IDs for compression. This method uses the specified mapping to replace each ID with an associated integer. When several Arrays with similar sets of IDs must be stored, this method allows the (possibly large) IDs to be stored only once, saving significant storage space.

If this Array contains an ID not present in the compression_map, it adds a new mapping, using the next available number. Therefore the map should not be serialized until after this Array, 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.

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