maspack.util
Class DataBuffer

java.lang.Object
  extended by maspack.util.DataBuffer
Direct Known Subclasses:
NumericState

public class DataBuffer
extends java.lang.Object

A general class for storing double, integer, and Object data. It is intended mainly as a convenience utility for storing component state.

DataBuffer maintains three independent buffers for storing double, integer, and Object data. Data is added to each using a put() operation and can be read back using a get() operation. Each buffer has a size and an offset. When data is added using put(), it is added at the end of the buffer and the size is increased. When data is read back using put(), it is read from the current offset location, and the offset is then increased. The offset is not allowed to increase beyond the current size. The put() and get() operations therefore act like inset and remove operations for a queue. However, unlike a queue, the get() operation does not actually remove data; it simply advances the offset. Other set() and peek() operations allow data to be set and read within the buffer without affecting its offset or size.

As an example, we consider storing and retriveing information about a vector. The store operation might look like this:

    saveVector (DataBuffer data) {
       data.zput (size);               // store vector size as an integer
       for (int i=0; i
 while the restore operation migth look like this:
 
    loadVector (DataBuffer data) {
       int size = data.zget ();        // get the vector size
       vector = new VectorNd(size);
       for (int i=0; i

 

Internally, each buffer is implementing as an array, whose length defines the current buffer capacity. When the size increases beyond the capacity, the array is resized automatically and the capacity is increased. Attempting to move the offset beyond the current size will cause an excpetion to be thrown. The buffer structure is shown in the following diagram, in which entries marked with 'x' contain actual data.

 |x|x|x|x|x|x|x|x|x|x|x|x|x|x|x|x|x|x| | | | | | | | | | | | | | |
          |                           |                           |
   offset-+                      size-+                  capacity-+
 


Constructor Summary
DataBuffer()
           
DataBuffer(int dcap, int zcap)
           
DataBuffer(int dcap, int zcap, int ocap)
          Creates a new DataBuffer with specified capacities for its double, integer, and Object buffers.
 
Method Summary
 void clear()
           
 double[] dbuffer()
          Returns the current array used to store the double buffer.
 void dEnsureCapacity(int cap)
          Ensures that the double buffer has a specified capacity.
 boolean dequals(DataBuffer data)
          Returns true if the double buffer contents of this DataBuffer and another DataBuffer are equal.
 double dget()
          Returns the double value at the current double buffer offset, and increases the offset.
 int doffset()
          Returns the current double buffer offset.
 double dpeek()
          Returns the double value at the current double buffer offset, but does not increase the offset.
 double dpeek(int i)
          Returns the double value at a specified location i.
 void dput(double d)
          Adds a double to the double buffer, increasing its size.
 void dset(int i, double d)
          Overwrites a value in the double buffer at a specified location i.
 void dsetOffset(int off)
          Sets the double buffer offset.
 void dsetSize(int size)
          Resets the size of the double buffer.
 int dsize()
          Returns the amount of data in the double buffer.
 void dskip(int n)
          Advances the double buffer offset forward by n.
 boolean equals(DataBuffer data)
           
 boolean equals(DataBuffer data, boolean printFailPoint)
           
 java.lang.Object[] obuffer()
          Returns the current array used to store the Object buffer.
 void oEnsureCapacity(int cap)
          Ensures that the Object buffer has a specified capacity.
 boolean oequals(DataBuffer data)
          Returns true if the Object buffer contents of this DataBuffer and another DataBuffer are equal.
 java.lang.Object oget()
          Returns the Object value at the current Object buffer offset, and increases the offset.
 int ooffset()
          Returns the current Object buffer offset.
 java.lang.Object opeek()
          Returns the Object value at the current Object buffer offset, but does not increase the offset.
 java.lang.Object opeek(int i)
          Returns the Object value at a specified location i.
 void oput(java.lang.Object o)
          Adds a Object to the Object buffer, increasing its size.
 void oputs(java.util.Collection<? extends java.lang.Object> objs)
          Adds a collection of Objects to the Object buffer, increasing its size.
 void oset(int i, java.lang.Object o)
          Overwrites a value in the Object buffer at a specified location i.
 void osetOffset(int off)
          Sets the Object buffer offset.
 void osetSize(int size)
          Resets the size of the Object buffer.
 int osize()
          Returns the amount of data in the Object buffer.
 void oskip(int n)
          Advances the Object buffer offset forward by n.
 void putData(DataBuffer data, int numd, int numz)
           
 void resetOffsets()
           
 void set(DataBuffer data)
           
 void setBuffersAndOffsets(DataBuffer data)
           
 void setSize(int dsize, int zsize)
           
 int[] zbuffer()
          Returns the current array used to store the integer buffer.
 void zEnsureCapacity(int cap)
          Ensures that the integer buffer has a specified capacity.
 boolean zequals(DataBuffer data)
          Returns true if the integer buffer contents of this DataBuffer and another DataBuffer are equal.
 int zget()
          Returns the integer value at the current integer buffer offset, and increases the offset.
 int zoffset()
          Returns the current integer buffer offset.
 int zpeek()
          Returns the integer value at the current integer buffer offset, but does not increase the offset.
 int zpeek(int i)
          Returns the integer value at a specified location i.
 void zput(int z)
          Adds a integer to the integer buffer, increasing its size.
 void zset(int i, int z)
          Overwrites a value in the integer buffer at a specified location i.
 void zsetOffset(int off)
          Sets the integer buffer offset.
 void zsetSize(int size)
          Resets the size of the integer buffer.
 int zsize()
          Returns the amount of data in the integer buffer.
 void zskip(int n)
          Advances the integer buffer offset forward by n.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DataBuffer

public DataBuffer()

DataBuffer

public DataBuffer(int dcap,
                  int zcap,
                  int ocap)
Creates a new DataBuffer with specified capacities for its double, integer, and Object buffers.


DataBuffer

public DataBuffer(int dcap,
                  int zcap)
Method Detail

dsize

public int dsize()
Returns the amount of data in the double buffer.

Returns:
amount of data in the double buffer

dput

public void dput(double d)
Adds a double to the double buffer, increasing its size.

Parameters:
d - double to add

dset

public void dset(int i,
                 double d)
Overwrites a value in the double buffer at a specified location i. If the location is outside the range 0 to dsize()-1, inclusive, an exception is thrown.

Parameters:
i - index at which to overwrite data
d - new data value to set

dsetSize

public void dsetSize(int size)
Resets the size of the double buffer. If the size is increased, the new space will be padded with zeros. If the size is decreased, the offset will be adjusted to enusre that is does not exceed the size.

Parameters:
size - new size for the double buffer

dget

public double dget()
Returns the double value at the current double buffer offset, and increases the offset. If the current offset is equal to dsize(), an exception is thrown.

Returns:
double value at the current offset

dpeek

public double dpeek()
Returns the double value at the current double buffer offset, but does not increase the offset. If the current offset is equal to dsize(), an exception is thrown.

Returns:
double value at the current offset

dpeek

public double dpeek(int i)
Returns the double value at a specified location i. If the location is outside the range 0 to dsize()-1, inclusive, an exception is thrown.

Parameters:
i - index at which to obtain the data
Returns:
double value at location i

dskip

public void dskip(int n)
Advances the double buffer offset forward by n. If this causes the offset to exceed dsize(), an exception is thrown.

Parameters:
n - amount to advance the double buffer

doffset

public int doffset()
Returns the current double buffer offset.

Returns:
current double buffer offset

dsetOffset

public void dsetOffset(int off)
Sets the double buffer offset. If the requested offset is outside the range 0 to dsize()-1, inclusive, an exception is thrown.

Parameters:
off - new double buffer offset

dequals

public boolean dequals(DataBuffer data)
Returns true if the double buffer contents of this DataBuffer and another DataBuffer are equal.

Returns:
true if the double buffers are equal

dEnsureCapacity

public void dEnsureCapacity(int cap)
Ensures that the double buffer has a specified capacity. The actualy capacity allocated may exceed this.

Parameters:
cap - request double buffer capacity

dbuffer

public double[] dbuffer()
Returns the current array used to store the double buffer. Note that this array may be changed by any operation that changes the double buffer's size or capacity.

Returns:
current double buffer

zsize

public int zsize()
Returns the amount of data in the integer buffer.

Returns:
amount of data in the integer buffer

zput

public void zput(int z)
Adds a integer to the integer buffer, increasing its size.

Parameters:
z - integer to add

zset

public void zset(int i,
                 int z)
Overwrites a value in the integer buffer at a specified location i. If the location is outside the range 0 to zsize()-1, inclusive, an exception is thrown.

Parameters:
i - index at which to overwrite data
z - new data value to set

zsetSize

public void zsetSize(int size)
Resets the size of the integer buffer. If the size is increased, the new space will be padded with zeros. If the size is decreased, the offset will be adjusted to enusre that is does not exceed the size.

Parameters:
size - new size for the integer buffer

zget

public int zget()
Returns the integer value at the current integer buffer offset, and increases the offset. If the current offset is equal to zsize(), an exception is thrown.

Returns:
integer value at the current offset

zpeek

public int zpeek()
Returns the integer value at the current integer buffer offset, but does not increase the offset. If the current offset is equal to zsize(), an exception is thrown.

Returns:
integer value at the current offset

zpeek

public int zpeek(int i)
Returns the integer value at a specified location i. If the location is outside the range 0 to zsize()-1, inclusive, an exception is thrown.

Parameters:
i - index at which to obtain the data
Returns:
integer value at location i

zskip

public void zskip(int n)
Advances the integer buffer offset forward by n. If this causes the offset to exceed zsize(), an exception is thrown.

Parameters:
n - amount to advance the integer buffer

zoffset

public int zoffset()
Returns the current integer buffer offset.

Returns:
current integer buffer offset

zsetOffset

public void zsetOffset(int off)
Sets the integer buffer offset. If the requested offset is outside the range 0 to zsize()-1, inclusive, an exception is thrown.

Parameters:
off - new integer buffer offset

zequals

public boolean zequals(DataBuffer data)
Returns true if the integer buffer contents of this DataBuffer and another DataBuffer are equal.

Returns:
true if the integer buffers are equal

zEnsureCapacity

public void zEnsureCapacity(int cap)
Ensures that the integer buffer has a specified capacity. The actualy capacity allocated may exceed this.

Parameters:
cap - request integer buffer capacity

zbuffer

public int[] zbuffer()
Returns the current array used to store the integer buffer. Note that this array may be changed by any operation that changes the integer buffer's size or capacity.

Returns:
current integer buffer

osize

public int osize()
Returns the amount of data in the Object buffer.

Returns:
amount of data in the Object buffer

oput

public void oput(java.lang.Object o)
Adds a Object to the Object buffer, increasing its size.

Parameters:
o - Object to add

oputs

public void oputs(java.util.Collection<? extends java.lang.Object> objs)
Adds a collection of Objects to the Object buffer, increasing its size.

Parameters:
objs - Objects to add

oset

public void oset(int i,
                 java.lang.Object o)
Overwrites a value in the Object buffer at a specified location i. If the location is outside the range 0 to osize()-1, inclusive, an exception is thrown.

Parameters:
i - index at which to overwrite data
o - new data value to set

osetSize

public void osetSize(int size)
Resets the size of the Object buffer. If the size is increased, the new space will be padded with nulls. If the size is decreased, the offset will be adjusted to enusre that is does not exceed the size.

Parameters:
size - new size for the Object buffer

oget

public java.lang.Object oget()
Returns the Object value at the current Object buffer offset, and increases the offset. If the current offset is equal to osize(), an exception is thrown.

Returns:
Object value at the current offset

opeek

public java.lang.Object opeek()
Returns the Object value at the current Object buffer offset, but does not increase the offset. If the current offset is equal to osize(), an exception is thrown.

Returns:
Object value at the current offset

opeek

public java.lang.Object opeek(int i)
Returns the Object value at a specified location i. If the location is outside the range 0 to osize()-1, inclusive, an exception is thrown.

Parameters:
i - index at which to obtain the data
Returns:
Object value at location i

oskip

public void oskip(int n)
Advances the Object buffer offset forward by n. If this causes the offset to exceed osize(), an exception is thrown.

Parameters:
n - amount to advance the Object buffer

ooffset

public int ooffset()
Returns the current Object buffer offset.

Returns:
current Object buffer offset

osetOffset

public void osetOffset(int off)
Sets the Object buffer offset. If the requested offset is outside the range 0 to osize()-1, inclusive, an exception is thrown.

Parameters:
off - new Object buffer offset

oequals

public boolean oequals(DataBuffer data)
Returns true if the Object buffer contents of this DataBuffer and another DataBuffer are equal.

Returns:
true if the Object buffers are equal

oEnsureCapacity

public void oEnsureCapacity(int cap)
Ensures that the Object buffer has a specified capacity. The actualy capacity allocated may exceed this.

Parameters:
cap - request Object buffer capacity

obuffer

public java.lang.Object[] obuffer()
Returns the current array used to store the Object buffer. Note that this array may be changed by any operation that changes the Object buffer's size or capacity.

Returns:
current Object buffer

setSize

public void setSize(int dsize,
                    int zsize)

clear

public void clear()

set

public void set(DataBuffer data)

equals

public boolean equals(DataBuffer data)

equals

public boolean equals(DataBuffer data,
                      boolean printFailPoint)

resetOffsets

public void resetOffsets()

setBuffersAndOffsets

public void setBuffersAndOffsets(DataBuffer data)

putData

public void putData(DataBuffer data,
                    int numd,
                    int numz)