net.sf.kdgcommons.util

Class ByteArray

java.lang.Object

net.sf.kdgcommons.util.ByteArray

public class ByteArray
extends Object

This class manages a variable-length array of bytes. It's primary use is as a replacement for StringBuffer for applications that need to deal with 8-bit character strings (eg, those that exchange data with legacy C programs).

Field Summary

Fields

Modifier and Type	Field and Description
protected byte[]	_data
protected int	_expandBy
protected int	_size

Constructor Summary

Constructors

Constructor and Description
ByteArray() Creates a new, empty ByteArray, using a default capacity and expansion factor.
ByteArray(byte[] src) Constructs a new ByteArray from a byte[].
ByteArray(int capacity, int factor) Constructs a new ByteArray, with specified initial capacity and expansion factor.
ByteArray(String src) Constructs a new ByteArray from a String, using ISO-8859-1 encoding.
ByteArray(String src, String encoding) Constructs a new ByteArray from a String, using the specified encoding.

Method Summary

Modifier and Type	Method and Description
void	add(byte val) Adds a single byte to the end of this array.
void	add(byte[] src) Adds a byte[] to the end of this array.
void	add(byte[] src, int off, int len) Adds a segment of a byte[] to the end of this array.
void	add(ByteArray src) Adds another ByteArray to the end of this array.
void	add(char src) Adds the low-order 8 bits of the passed character to this array.
void	add(String src) Adds a String to the end of this array, converting it with ISO-8859-1 encoding.
void	add(String src, String encoding) Adds a String to the end of this array, using the specified encoding.
byte	get(int idx) Returns a single byte from the array.
byte[]	getArray() Returns the underlying array.
byte[]	getBytes() Returns a byte[] containing all bytes in this array.
byte[]	getBytes(int off) Returns a byte[] containing the bytes from a specified offset to the end of the array.
byte[]	getBytes(int off, int len) Returns a specified sub-section of the array.
void	insert(int off, byte[] src) Inserts the passed array at an arbitrary point in this array.
void	insert(int off, byte[] src, int srcOff, int srcLen) Inserts the passed array of bytes into the middle of this array.
void	insert(int off, ByteArray src) Inserts the passed array at an arbitrary point in this array.
void	insert(int off, ByteArray src, int srcOff, int srcLen) Inserts a portion of the passed array at an arbitrary point in this array.
void	remove(int idx) Removes a specified byte from this array, shifting subsequent bytes down and reducing the size of the array.
void	remove(int off, int len) Removes a subset of the bytes in this array, shifting subsequent bytes down and reducing the size of the array.
void	removeLast() Removes the last byte in the array.
void	setSize(int size) Resizes the array.
int	size() Returns the current size of this array.

Methods inherited from class java.lang.Object

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

Field Detail

_data

protected byte[] _data

_size

protected int _size

_expandBy

protected int _expandBy

Constructor Detail

ByteArray

public ByteArray(int capacity,
                 int factor)

Constructs a new ByteArray, with specified initial capacity and expansion factor. This is the basic constructor.

Parameters:

capacity - The initial size of the underlying array.

factor - The exansion factor. This is the percentage by which the array should be expanded, whenever additions run out of space.

ByteArray

public ByteArray(byte[] src)

Constructs a new ByteArray from a byte[]. The source array is copied into the new object, with some room to grow, and it is given a default expansion factor.

ByteArray

public ByteArray(String src)

Constructs a new ByteArray from a String, using ISO-8859-1 encoding. The array is given the default expansion factor. Null strings will be converted to a zero-length array.

Throws:

IllegalArgumentException - if the passed string contains characters outside the 8-bit range.

ByteArray

public ByteArray(String src,
                 String encoding)
          throws UnsupportedEncodingException

Constructs a new ByteArray from a String, using the specified encoding. The array is given the default expansion factor.

Throws:

UnsupportedEncodingException

ByteArray

public ByteArray()

Creates a new, empty ByteArray, using a default capacity and expansion factor.

Method Detail

add

public void add(byte val)

Adds a single byte to the end of this array.

add

public void add(byte[] src)

Adds a byte[] to the end of this array.

add

public void add(byte[] src,
                int off,
                int len)

Adds a segment of a byte[] to the end of this array.

add

public void add(char src)

Adds the low-order 8 bits of the passed character to this array. Only useful with ASCII or 8-bit character sets.

add

public void add(String src)

Adds a String to the end of this array, converting it with ISO-8859-1 encoding.

add

public void add(String src,
                String encoding)
         throws UnsupportedEncodingException

Adds a String to the end of this array, using the specified encoding. Note that this may result in multi-byte characters.

Throws:

UnsupportedEncodingException

add

public void add(ByteArray src)

Adds another ByteArray to the end of this array.

get

public byte get(int idx)

Returns a single byte from the array.

Parameters:

idx - The index of the byte to be removed.

Throws:

ArrayIndexOutOfBoundsException - if idx is outside the current bounds of the array.

getArray

public byte[] getArray()

Returns the underlying array. This method exists for efficiency; most callers should use getBytes(int, int) instead.

Note that the returned array may be significantly larger than what is reported by size().

getBytes

public byte[] getBytes(int off,
                       int len)

Returns a specified sub-section of the array. The returned bytes are copied from the actual array, and will not reflect subsequent changes.

Parameters:

off - The starting byte of the subarray.

len - The length of the subarray.

Throws:

IllegalArgumentException - if off and/or len specify indexes that are outside the bounds of the array.

getBytes

public byte[] getBytes(int off)

Returns a byte[] containing the bytes from a specified offset to the end of the array. The returned array is a copy of the managed array, and will not reflect subsequent changes.

Parameters:

off - The starting byte of the subarray.

Throws:

ArrayIndexOutOfBoundsException - if any of the bytes defined by off and len are outside the current bounds of the array.

getBytes

public byte[] getBytes()

Returns a byte[] containing all bytes in this array. The returned array is a copy of this object's data, and will not reflect subsequent changes.

insert

public void insert(int off,
                   ByteArray src)

Inserts the passed array at an arbitrary point in this array. All existing contents are moved up to make room.

Parameters:

off - The position where the passed array is inserted.

src - The array to insert.

insert

public void insert(int off,
                   ByteArray src,
                   int srcOff,
                   int srcLen)

Inserts a portion of the passed array at an arbitrary point in this array. All existing contents are moved up to make room.

Parameters:

off - The position where the passed array is inserted.

src - The array to insert.

srcOff - The offset within the source array where the inserted data begins.

srcLen - The number of bytes to transfer from the source array.

Throws:

IllegalArgumentException - if off is larger than the current size of the array, or if srcOff or srcOff + srcLen is outside the bounds of the source array. These are checked prior to performing any moves, so this array will not be corrupted.

insert

public void insert(int off,
                   byte[] src)

Inserts the passed array at an arbitrary point in this array. All existing contents are moved up to make room.

Parameters:

off - The position where the passed array is inserted.

src - The array to insert.

insert

public void insert(int off,
                   byte[] src,
                   int srcOff,
                   int srcLen)

Inserts the passed array of bytes into the middle of this array.

Parameters:

off - The position where the passed array is inserted.

src - The array to insert.

srcOff - The offset within the source array where the inserted data begins.

srcLen - The number of bytes to transfer from the source array.

Throws:

IllegalArgumentException - if off is larger than the current size of the array, or if srcOff or srcOff + srcLen is outside the bounds of the source array. These are checked prior to performing any moves, so this array will not be corrupted.

remove

public void remove(int idx)

Removes a specified byte from this array, shifting subsequent bytes down and reducing the size of the array.

Parameters:

idx - The index of the byte to be removed.

Throws:

ArrayIndexOutOfBoundsException - if idx is outside the current bounds of the array.

remove

public void remove(int off,
                   int len)

Removes a subset of the bytes in this array, shifting subsequent bytes down and reducing the size of the array.

Parameters:

off - The starting byte to be removed.

len - The number of bytes to be removed.

Throws:

ArrayIndexOutOfBoundsException - if any of the bytes defined by off and len are outside the current bounds of the array.

removeLast

public void removeLast()

Removes the last byte in the array.

size

public int size()

Returns the current size of this array.

setSize

public void setSize(int size)

Resizes the array. If the specified size is less than the current size, the array is truncated. If it is greater than the current size, the array is expanded and the new space is filled with zero-bytes.

Parameters:

size - The desired size of the array.