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.16 2002/07/20 19:38:03 srhea 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(double default_elt)
Construct a new Array with the specified default.

Array(InputBuffer buffer)
Constructs a Array from its serialized form.

Array(InputBuffer buffer, HashMap decompression_map)
Constructs a Array from its serialized form.

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	serialize(OutputBuffer buffer) Add the object to the buffer.
void	serialize(OutputBuffer buffer, HashMap compression_map) Serializes the Array using a compression map.
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.
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.

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

See Also:

Constant Field Values

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(InputBuffer buffer)
      throws QSException

Constructs a Array from its serialized form.

Array

public Array(InputBuffer buffer,
             HashMap decompression_map)
      throws QSException

Constructs a Array from its serialized form.

Parameters:

decompression_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.

serialize

public void serialize(OutputBuffer buffer)

Description copied from interface: QuickSerializable

Add the object to the buffer.

Specified by:

serialize in interface QuickSerializable

Parameters:

buffer - the output buffer to add the object to

serialize

public void serialize(OutputBuffer buffer,
                      HashMap compression_map)

Serializes the Array using a compression map.