net.rim.device.api.util
Class ByteVector

java.lang.Object
  net.rim.device.api.util.ByteVector

All Implemented Interfaces:

Persistable

public class ByteVector
extends Object
implements Persistable

Vector-like class for storing byte values. Note that this implementation is not synchronized. If multiple threads access this object concurrently, and at least one of the threads modifies the object, it must be synchronized externally.

Since:

BlackBerry API 3.6.0

Field Summary
protected int	capacityIncrement The amount by which the capacity of the vector is automatically incremented when its size becomes greater than its capacity.
protected int	elementCount The number of valid components in the vector.
protected byte[]	elementData The array buffer into which the components of the vector are stored.

Constructor Summary

ByteVector()
Constructs an empty vector.

ByteVector(int initialCapacity)
Constructs an empty vector with the specified initial capacity.

ByteVector(int initialCapacity, int capacityIncrement)
Constructs an empty vector with the specified initial capacity and capacity increment.

Method Summary
void	addElement(byte obj) Adds the specified component to the end of this vector, increasing its size by one.
int	capacity() Returns the current capacity of this vector.
boolean	contains(byte elem) Tests if the specified element is a component in this vector.
void	copyInto(byte[] anArray) Copies the components of this vector into the specified array.
byte	elementAt(int index) Returns the component at the specified index.
void	ensureCapacity(int minCapacity) Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.
byte	firstElement() Returns the first component of this vector.
byte[]	getArray() Retrieves the vector values.
int	indexOf(byte elem) Searches for the first occurence of the given argument, testing for equality.
int	indexOf(byte elem, int index) Searches for the first occurence of the given argument, beginning the search at index.
void	insertElementAt(byte obj, int index) Inserts the specified element as a component in this vector at the specified index.
boolean	isEmpty() Tests if this vector has no components.
byte	lastElement() Returns the last component of the vector.
int	lastIndexOf(byte elem) Returns the index of the last occurrence of the specified element in this vector.
int	lastIndexOf(byte elem, int index) Searches backwards for the specified element, starting from the specified index, and returns an index to it.
void	removeAllElements() Removes all components from this vector and sets its size to zero.
boolean	removeElement(byte obj) Removes the first occurrence of the argument from this vector.
void	removeElementAt(int index) Deletes the component at the specified index.
void	setElementAt(byte obj, int index) Sets the component at the specified index of this vector to be the specified element.
void	setSize(int newSize) Sets the size of this vector.
int	size() Returns the number of components in this vector.
byte[]	toArray() Retrieves a copy of the underlying store.
void	trimToSize() Trims the capacity of this vector to be the vector's current size.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

elementData

protected byte[] elementData

The array buffer into which the components of the vector are stored. The capacity of the vector is the length of this array buffer.

Since:

BlackBerry API 3.6.0

elementCount

protected int elementCount

The number of valid components in the vector.

Since:

BlackBerry API 3.6.0

capacityIncrement

protected int capacityIncrement

The amount by which the capacity of the vector is automatically incremented when its size becomes greater than its capacity. If the capacity increment is 0, the capacity of the vector is doubled each time it needs to grow.

Since:

BlackBerry API 3.6.0

Constructor Detail

ByteVector

public ByteVector(int initialCapacity,
                  int capacityIncrement)

Constructs an empty vector with the specified initial capacity and capacity increment.

Parameters:

initialCapacity - the initial capacity of the vector.

capacityIncrement - the amount by which the capacity is increased when the vector overflows.

Throws:

IllegalArgumentException - if the specified initial capacity is negative

Since:

BlackBerry API 3.6.0

ByteVector

public ByteVector(int initialCapacity)

Constructs an empty vector with the specified initial capacity.

Parameters:

initialCapacity - the initial capacity of the vector.

Since:

BlackBerry API 3.6.0

ByteVector

public ByteVector()

Constructs an empty vector.

Since:

BlackBerry API 3.6.0

Method Detail

copyInto

public void copyInto(byte[] anArray)

Copies the components of this vector into the specified array. The array must be big enough to hold all the elements in this vector.

Parameters:

anArray - the array into which the components get copied.

Since:

BlackBerry API 3.6.0

toArray

public byte[] toArray()

Retrieves a copy of the underlying store. The resulting array is trimmed.

Returns:

A copy of the vector values.

Since:

BlackBerry API 3.6.0

getArray

public byte[] getArray()

Retrieves the vector values. The array is not trimmed and is not a copy.

Returns:

Vector values (not a copy).

Since:

BlackBerry API 3.6.0

trimToSize

public void trimToSize()

Trims the capacity of this vector to be the vector's current size. An application can use this operation to minimize the storage of a vector.

Since:

BlackBerry API 3.6.0

ensureCapacity

public void ensureCapacity(int minCapacity)

Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.

Parameters:

minCapacity - the desired minimum capacity.

Since:

BlackBerry API 3.6.0

setSize

public void setSize(int newSize)

Sets the size of this vector. If the new size is greater than the current size, new items are added to the end of the vector. If the new size is less than the current size, all components at index newSize and greater are discarded. If a negative number is set as input, the function throws IllegalArgumentException.

Parameters:

newSize - the new size of this vector.

Throws:

IllegalArgumentException - if the specified new size is negative

Since:

BlackBerry API 3.6.0

capacity

public int capacity()

Returns the current capacity of this vector.

Returns:

the current capacity of this vector.

Since:

BlackBerry API 3.6.0

size

public int size()

Returns the number of components in this vector.

Returns:

the number of components in this vector.

Since:

BlackBerry API 3.6.0

isEmpty

public boolean isEmpty()

Tests if this vector has no components.

Returns:

true if this vector has no components; false otherwise.

Since:

BlackBerry API 3.6.0

contains

public boolean contains(byte elem)

Tests if the specified element is a component in this vector.

Parameters:

elem - the desired component.

Returns:

true if the specified element is a component in this vector; false otherwise.

Since:

BlackBerry API 3.6.0

indexOf

public int indexOf(byte elem)

Searches for the first occurence of the given argument, testing for equality.

Parameters:

elem - the desired component.

Returns:

the index of the first occurrence of the argument in this vector; returns -1 if the element is not found.

Since:

BlackBerry API 3.6.0

indexOf

public int indexOf(byte elem,
                   int index)

Searches for the first occurence of the given argument, beginning the search at index.

Parameters:

elem - the desired component.

index - the index to start searching from.

Returns:

the index of the first occurrence of the element argument in this vector at position index or later in the vector; returns -1 if the element is not found.

Since:

BlackBerry API 3.6.0

lastIndexOf

public int lastIndexOf(byte elem)

Returns the index of the last occurrence of the specified element in this vector.

Parameters:

elem - the desired component.

Returns:

the index of the last occurrence of the specified element in this vector; returns -1 if the element is not found.

Since:

BlackBerry API 3.6.0

lastIndexOf

public int lastIndexOf(byte elem,
                       int index)

Searches backwards for the specified element, starting from the specified index, and returns an index to it.

Parameters:

elem - the desired component.

index - the index to start searching from.

Returns:

the index of the last occurrence of the specified element in this vector at position index or earlier in the vector; -1 if the element is not found.

Since:

BlackBerry API 3.6.0

elementAt

public byte elementAt(int index)

Returns the component at the specified index.

Parameters:

index - an index into this vector.

Returns:

the component at the specified index.

Throws:

ArrayIndexOutOfBoundsException - if an invalid index was given.

Since:

BlackBerry API 3.6.0

firstElement

public byte firstElement()

Returns the first component of this vector.

Returns:

the first component of this vector.

Throws:

NoSuchElementException - if this vector has no components.

Since:

BlackBerry API 3.6.0

lastElement

public byte lastElement()

Returns the last component of the vector.

Returns:

the last component of the vector, i.e., the component at index size() - 1.

Throws:

NoSuchElementException - if this vector is empty.

Since:

BlackBerry API 3.6.0

setElementAt

public void setElementAt(byte obj,
                         int index)

Sets the component at the specified index of this vector to be the specified element. The previous component at that position is discarded.

The index must be a value greater than or equal to 0 and less than the current size of the vector.

Parameters:

obj - what the component is to be set to.

index - the specified index.

Throws:

ArrayIndexOutOfBoundsException - if the index was invalid.

Since:

BlackBerry API 3.6.0

removeElementAt

public void removeElementAt(int index)

Deletes the component at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously.

The index must be a value greater than or equal to 0 and less than the current size of the vector.

Parameters:

index - the index of the element to remove.

Throws:

ArrayIndexOutOfBoundsException - if the index was invalid.

Since:

BlackBerry API 3.6.0

insertElementAt

public void insertElementAt(byte obj,
                            int index)

Inserts the specified element as a component in this vector at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

The index must be a value greater than or equal to 0 and less than or equal to the current size of the vector.

Parameters:

obj - the component to insert.

index - where to insert the new component.

Throws:

ArrayIndexOutOfBoundsException - if the index was invalid.

Since:

BlackBerry API 3.6.0

addElement

public void addElement(byte obj)

Adds the specified component to the end of this vector, increasing its size by one. The capacity of this vector is increased if its size becomes greater than its capacity.

Parameters:

obj - the component to be added.

Since:

BlackBerry API 3.6.0

removeElement

public boolean removeElement(byte obj)

Removes the first occurrence of the argument from this vector. If the element is found in this vector, each component in the vector with an index greater or equal to the element's index is shifted downward to have an index one smaller than the value it had previously.

Parameters:

obj - the component to be removed.

Returns:

true if the argument was a component of this vector; false otherwise.

Since:

BlackBerry API 3.6.0

removeAllElements

public void removeAllElements()

Removes all components from this vector and sets its size to zero.

Since:

BlackBerry API 3.6.0