com.javaranch.common
Class ByteVector

java.lang.Object
  |
  +--com.javaranch.common.ByteVector

public class ByteVector

extends java.lang.Object

Like the Vector object, except rather than tracking dynamic array of pointers to different objects, this is simply a dynamic array of bytes.

The advantage is speed and memory savings.

- - - - - - - - - - - - - - - - -

Copyright (c) 1998-2004 Paul Wheaton

You are welcome to do whatever you want to with this source file provided that you maintain this comment fragment (between the dashed lines). Modify it, change the package name, change the class name ... personal or business use ... sell it, share it ... add a copyright for the portions you add ...

My goal in giving this away and maintaining the copyright is to hopefully direct developers back to JavaRanch.

The original source can be found at JavaRanch

- - - - - - - - - - - - - - - - -

Author:

Paul Wheaton

Constructor Summary

ByteVector()
The object has memory allocated to store a moderate number of bytes.

ByteVector(byte[] b)
The object is inititialized to contain a copy of a byte array.

ByteVector(ByteVector b)
The object is inititialized to contain a copy of another ByteVector.

ByteVector(int initialSize)
Create a new ByteVector with a specific initial capacity.

ByteVector(int initialSize, int initialExtra)
Create a new ByteVector with a specific initial capacity and to be able to grow by a specific increment.

Method Summary

void	append(byte b) Add one byte to the end of the vector.
void	append(byte[] b) Add an array of bytes to the end of this object.
void	append(byte[] b, int numBytes) Add an array of bytes to the end of this object.
void	append(ByteVector b) Add all of the bytes in another ByteVector to the end of this object.
void	delete(int index, int howMany) Remove bytes from your object.
byte	get(int index) Get a copy of one byte.
ByteVector	get(int index, int length) Get a copy of a "sub-vector".
int	getCapacity() Get the number of bytes this object can hold without doing a reallocation.
int	indexOf(byte b) Find the position within your object of a particular character.
int	indexOf(byte[] b) Find the position within your object of a particular sequence of bytes.
int	indexOf(byte[] b, int startPos) Find the position within your object of a particular sequence of bytes.
int	indexOf(byte b, int startPos) Find the position within your object of a particular byte.
void	insert(byte[] b, int index) Insert an array of bytes immediately before a particular byte in the object.
void	insert(byte b, int index) Insert a byte immediately before a particular byte in the object.
byte	last() Get a copy of the last byte.
int	length() Get the number of bytes currently being used.
byte	pop() If you wish to treat your object like a stack, you can push and pop bytes.
void	push(byte b) If you wish to treat your object like a stack, you can push and pop bytes.
void	replace(byte[] b1, byte b2) Search for a particular sequence of bytes and replace them with one byte.
void	replace(byte[] b1, byte[] b2) Search for a particular sequence of bytes and replace it with a different sequence of bytes.
void	replace(byte b1, byte b2) Replace all instances of one byte with another byte.
void	replace(byte b1, byte[] b2) Replace all instances of one byte with several bytes.
void	set(int index, byte b) Set one byte in the object.
void	setCapacity(int howMuch) Force this object to be able to hold a specific number of bytes without reallocation.
void	setExtra(int howMuch) Set how much to grow when growth is needed.
void	setLength(int newLength) Force the number of bytes to be currently used.
boolean	startsWith(byte[] b) A fast way to test the first few bytes of your object.
byte[]	toByteArray() Copy the existing object into a byte array.

Methods inherited from class java.lang.Object

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

Constructor Detail

ByteVector

public ByteVector(int initialSize)

Create a new ByteVector with a specific initial capacity.

Parameters:

initialSize - The initial capacity.

ByteVector

public ByteVector(int initialSize,
                  int initialExtra)

Create a new ByteVector with a specific initial capacity and to be able to grow by a specific increment.

Parameters:

initialSize - The initial capacity.

initialExtra - How many bytes the object will grow by when more memory is needed.

ByteVector

public ByteVector()

The object has memory allocated to store a moderate number of bytes.

ByteVector

public ByteVector(byte[] b)

The object is inititialized to contain a copy of a byte array.

Enough memory is allocated for some growth.

Parameters:

b - A byte array to copy.

ByteVector

public ByteVector(ByteVector b)

The object is inititialized to contain a copy of another ByteVector.

Enough memory is allocated for some growth.

Parameters:

b - A ByteVector to copy.

Method Detail

length

public int length()

Get the number of bytes currently being used.

Not the same as the number of bytes currently allocated.

Returns:

The number of bytes in use.

setLength

public void setLength(int newLength)

Force the number of bytes to be currently used.

If you want to empty your ByteVector, use setLength(0);

If the new length is longer than the existing length, the previously unused bytes will be set to zero.

Parameters:

newLength - The new length.

setExtra

public void setExtra(int howMuch)

Set how much to grow when growth is needed.

Smaller values will usually save memory, but frequent reallocation may take a lot of time.

Parameters:

howMuch - The number of extra bytes to allocate when memory reallocation is required. Values must be greater than zero.

getCapacity

public int getCapacity()

Get the number of bytes this object can hold without doing a reallocation.

Returns:

The number of bytes this object can hold without doing a reallocation.

setCapacity

public void setCapacity(int howMuch)

Force this object to be able to hold a specific number of bytes without reallocation.

Any attempt to make the object grow bigger than this size will succeed.

Setting the capacity to be smaller than the current object size will result in trailing bytes being clipped.

Parameters:

howMuch - How many bytes will be the new capacity.

get

public byte get(int index)

Get a copy of one byte.

Parameters:

index - Which byte (0 is the first byte).

Returns:

The retrieved byte. Returns a zero if index is outside of 0..length.

last

public byte last()

Get a copy of the last byte.

Returns:

A copy of the last byte.

get

public ByteVector get(int index,
                      int length)

Get a copy of a "sub-vector".

Parameters:

index - Where to start copying.

length - How many bytes to copy.

Returns:

A ByteVector object that contains a copy of the "sub-vector".

toByteArray

public byte[] toByteArray()

Copy the existing object into a byte array.

Returns:

A copy of this object as a byte array.

set

public void set(int index,
                byte b)

Set one byte in the object.

Parameters:

index - Which byte to set. If index references a byte beyond the last byte of the object, the object will be lengthened and the last byte will be set appropriately (undefined bytes will be set to zero).

b - The byte to be placed at index.

append

public void append(byte b)

Add one byte to the end of the vector.

Parameters:

b - The byte to append.

append

public void append(byte[] b,
                   int numBytes)

Add an array of bytes to the end of this object.

Parameters:

b - The array containing the bytes to be appended.

numBytes - The number of bytes to append from b

append

public void append(byte[] b)

Add an array of bytes to the end of this object.

Parameters:

b - The byte array to be appended.

append

public void append(ByteVector b)

Add all of the bytes in another ByteVector to the end of this object.

Parameters:

b - The ByteVector to be appended.

insert

public void insert(byte b,
                   int index)

Insert a byte immediately before a particular byte in the object.

Parameters:

b - The byte to be inserted.

index - Where to insert b. The byte currently at index will me moved to the right.

insert

public void insert(byte[] b,
                   int index)

Insert an array of bytes immediately before a particular byte in the object.

Parameters:

b - The array of bytes to be inserted.

index - Where to insert b. The byte currently at index will me moved to the right.

delete

public void delete(int index,
                   int howMany)

Remove bytes from your object.

Parameters:

index - Referencing the first byte to be removed.

howMany - The number of bytes to remove.

push

public void push(byte b)

If you wish to treat your object like a stack, you can push and pop bytes.

Parameters:

b - The byte that will be appended to the end of your object.

pop

public byte pop()

If you wish to treat your object like a stack, you can push and pop bytes.

Remember the old assembly programming pearl: May all your pushes be popped.

Returns:

The last byte in your object. If there are no more bytes in the object, a zero is returned.

startsWith

public boolean startsWith(byte[] b)

A fast way to test the first few bytes of your object.

Parameters:

b - An array of bytes to compare to.

Returns:

True if all of the bytes in b exactly matches the first few bytes in your object.

indexOf

public int indexOf(byte b,
                   int startPos)

Find the position within your object of a particular byte.

Parameters:

b - The byte to search for.

startPos - The byte position in your object to start looking for b.

Returns:

The position of the byte that matches b where 0 is the first byte of the object. -1 is returned if a matching byte could not be found.

indexOf

public int indexOf(byte[] b,
                   int startPos)

Find the position within your object of a particular sequence of bytes.

Parameters:

b - A byte array representing the byte sequence to search for.

startPos - The byte position in your object to start looking for b.

Returns:

-1 is returned if a match could not be found. Otherwise the position of the first byte of the match is returned.

indexOf

public int indexOf(byte b)

Find the position within your object of a particular character.

Searching begins with the first byte in your object.

Parameters:

b - The byte to search for.

Returns:

The position of the byte that matches b. -1 is returned if a matching byte could not be found.

indexOf

public int indexOf(byte[] b)

Find the position within your object of a particular sequence of bytes.

Searching begins with the first byte in your object.

Parameters:

b - A byte array representing the byte sequence to search for.

Returns:

-1 is returned if a match could not be found. Otherwise the position of the first byte of the match is returned.

replace

public void replace(byte b1,
                    byte b2)

Replace all instances of one byte with another byte.

All occurances are replaced.

Searching for the "next instance" of a byte will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

b1 - The byte to search for.

b2 - The byte that is to replace b1.

replace

public void replace(byte b1,
                    byte[] b2)

Replace all instances of one byte with several bytes.

All occurances are replaced.

Searching for the "next instance" of a byte will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

b1 - The byte to search for.

b2 - The array of bytes that is to replace b1.

replace

public void replace(byte[] b1,
                    byte b2)

Search for a particular sequence of bytes and replace them with one byte.

All occurances are replaced.

Searching for the "next instance" of a byte sequence will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

b1 - A byte array representing a byte sequence to search for.

b2 - The byte that is to replace b1.

replace

public void replace(byte[] b1,
                    byte[] b2)

Search for a particular sequence of bytes and replace it with a different sequence of bytes.

All occurances are replaced.

Searching for the "next instance" of a byte sequence will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

b1 - A byte array representing a byte sequence to search for.

b2 - A byte array representing a byte sequence that is to replace b1.