simple.util
Class Buffer

java.lang.Object
  extended by simple.util.Buffer
All Implemented Interfaces:
ByteStore

public final class Buffer
extends java.lang.Object
implements ByteStore

The Buffer is intended to be a general purpose byte Buffer. The intended use of the Buffer is to allow the constructiuon of buffering for streams to be seamless and easy.

This provides several convinence methods which make the use of the Buffer easy and useful. The Buffer object allows an initial capacity to be specified however if there is a need for extra space to be added to the Buffer then the append methods will expand the capacity of the Buffer as needed.

This is also capable of appending other Buffer objects, which is quicker that extracting the bytes and then appending those bytes to the second Buffer. The append methods have much the same semantics as the java.lang.StringBuffer.

Author:
Niall Gallagher
See Also:
ByteStore

Constructor Summary
Buffer()
          This creates a default Buffer object.
Buffer(Buffer buf)
          This creates a Buffer with the data given.
Buffer(Buffer buf, int off, int len)
          This creates a Buffer with the data given.
Buffer(byte[] b)
          This creates a Buffer with the data given.
Buffer(byte[] b, int off, int len)
          This creates a Buffer with the data given.
Buffer(int size)
          This creates a Buffer.
 
Method Summary
 void append(Buffer buf)
          This method is used to append bytes to the end of the Buffer.
 void append(Buffer buf, int off, int len)
          This method is used to append bytes to the end of the Buffer.
 void append(byte[] b)
          This method is used to append bytes to the end of the Buffer.
 void append(byte[] b, int off, int len)
          This method is used to append bytes to the end of the Buffer.
 void append(int b)
          This method is used to append bytes to the end of the Buffer.
 int capacity()
          This provides the number of bytes that can fit inside this buffer without requiring an expensive resize.
 void clear()
          This will clear all data from the Buffer.
 void delete(int pos)
          This is used to delete a region of data from the Buffer.
 void delete(int pos, int len)
          This is used to delete a region of data from the Buffer.
 boolean equals(Buffer buf)
          This is used to compare the contents of one Buffer with the contents of another.
 byte getByte(int pos)
          This is used to read data from the Buffer.
 void getBytes(int pos, byte[] b)
          This is used to read data from the Buffer.
 void getBytes(int pos, byte[] b, int off, int len)
          This is used to read data from the Buffer.
 java.io.InputStream getInputStream()
          This method is used so that the Buffer can be represented as an input stream.
 void insert(int pos, Buffer buf)
          This method is used to insert bytes into the Buffer at the specified position.
 void insert(int pos, Buffer buf, int off, int len)
          This method is used to insert bytes into the Buffer at the specified position.
 void insert(int pos, byte[] b)
          This method is used to insert bytes into the Buffer at the specified position.
 void insert(int pos, byte[] b, int off, int len)
          This method is used to insert bytes into the Buffer at the specified position.
 void insert(int pos, int b)
          This method is used to insert bytes into the Buffer at the specified position.
 int length()
          This returns the number of bytes that have been appended to this Buffer object.
 boolean regionMatches(int pos, Buffer buf, int off, int len)
          This is used to examine the bytes that are stored in the Buffer.
 boolean regionMatches(int pos, byte[] b, int off, int len)
          This is used to examine the bytes that are stored in the Buffer.
 void resize(int min)
          This ensure that there is enough space in the Buffer to allow for more chars to be added.
 void setByte(int pos, int b)
          This is used to write bytes into the Buffer at an arbitrary position.
 void setBytes(int pos, Buffer buf)
          This is used to write bytes into the Buffer at an arbitrary position.
 void setBytes(int pos, Buffer buf, int off, int len)
          This is used to write bytes into the Buffer at an arbitrary position.
 void setBytes(int pos, byte[] b, int off, int len)
          This is used to write bytes into the Buffer at an arbitrary position.
 byte[] toArray()
          This is used to create a copy of the bytes that are stored in the Buffer object.
 java.lang.String toString()
          This method is used to acquire the buffered bytes as a string.
 void writeTo(java.io.OutputStream out)
          This is used to emit data from the Buffer out to an OutputStream.
 void writeTo(java.io.OutputStream out, int off, int len)
          This is used to emit data from the Buffer out to an OutputStream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Buffer

public Buffer()
This creates a default Buffer object. The initial capacity of the default Buffer object is set to 16, the capacity will be expanded when the append methods are used and there is not enough space in the Buffer to accomodate the extra bytes.


Buffer

public Buffer(int size)
This creates a Buffer. The initial capacity of this Buffer can be specified by the size parameter, the capacity will be expanded when the append methods are used and there is not enough space in the Buffer to accomodate the extra bytes.

Parameters:
size - the initial capacity of the Buffer

Buffer

public Buffer(byte[] b)
This creates a Buffer with the data given. The capacity will be expanded when the append methods are used and there is not enough space in the Buffer to accomodate the extra bytes.

Parameters:
b - this is the initial data this will have

Buffer

public Buffer(Buffer buf)
This creates a Buffer with the data given. The capacity will be expanded when the append methods are used and there is not enough space in the Buffer to accomodate the extra bytes.

Parameters:
buf - this is the initial data this will have

Buffer

public Buffer(byte[] b,
              int off,
              int len)
This creates a Buffer with the data given. The capacity will be expanded when the append methods are used and there is not enough space in the Buffer to accomodate the extra bytes.

Parameters:
b - this is the initial data this will have
len - this is the number of bytes to be taken
off - this is the offset to take the bytes from

Buffer

public Buffer(Buffer buf,
              int off,
              int len)
This creates a Buffer with the data given. The capacity will be expanded when the append methods are used and there is not enough space in the Buffer to accomodate the extra bytes.

Parameters:
buf - this is the initial data this will have
len - this is the number of bytes to be taken
off - this is the offset to take the bytes from
Method Detail

append

public void append(int b)
This method is used to append bytes to the end of the Buffer. This will expand the capacity of the Buffer if there is not enough space to accomodate the extra bytes.

Parameters:
b - this is the data that is to be append to this Buffer

append

public void append(byte[] b)
This method is used to append bytes to the end of the Buffer. This will expand the capacity of the Buffer if there is not enough space to accomodate the extra bytes.

Parameters:
b - this is the data that is to be append to this Buffer

append

public void append(byte[] b,
                   int off,
                   int len)
This method is used to append bytes to the end of the Buffer. This will expand the capacity of the Buffer if there is not enough space to accomodate the extra bytes.

Parameters:
b - this is the data that is to be append to this Buffer
len - the number of bytes that are to be taken
off - the offset to take the bytes from the array

append

public void append(Buffer buf)
This method is used to append bytes to the end of the Buffer. This will expand the capacity of the Buffer if there is not enough space to accomodate the extra bytes.

Parameters:
buf - the data that is to be append to this Buffer

append

public void append(Buffer buf,
                   int off,
                   int len)
This method is used to append bytes to the end of the Buffer. This will expand the capacity of the Buffer if there is not enough space to accomodate the extra bytes.

Parameters:
buf - this is the data that is to be append to this Buffer
len - the number of bytes that are to be taken
off - the offset to take bytes from the array

insert

public void insert(int pos,
                   int b)
This method is used to insert bytes into the Buffer at the specified position. This will insert the bytes into the Buffer without over writing any bytes in the Buffer. This will simply move the bytes that come before the specified position up the ways and insert the data. This will throw an IndexOutOfBoundsException if the insert is done at a position where there is no bytes, i.e. must be in the bounds.

Parameters:
pos - this is the position within the Buffer to insert data
b - this is the data that is to be inserted into the Buffer

insert

public void insert(int pos,
                   byte[] b)
This method is used to insert bytes into the Buffer at the specified position. This will insert the bytes into the Buffer without over writing any bytes in the Buffer. This will simply move the bytes that come before the specified position up the ways and insert the data. This will throw an IndexOutOfBoundsException if the insert is done at a position where there is no bytes, i.e. must be in the bounds.

Parameters:
pos - this is the position within the Buffer to insert data
b - this is the data that is to be inserted into the Buffer

insert

public void insert(int pos,
                   byte[] b,
                   int off,
                   int len)
This method is used to insert bytes into the Buffer at the specified position. This will insert the bytes into the Buffer without over writing any bytes in the Buffer. This will simply move the bytes that come before the specified position up the ways and insert the data. This will throw an IndexOutOfBoundsException if the insert is done at a position where there is no bytes, i.e. must be in the bounds.

Parameters:
pos - this is the position within the Buffer to insert data
b - this is the data that is to be inserted into the Buffer
len - this is the number of bytes that are to be taken
off - this is the offset to take the bytes from the array

insert

public void insert(int pos,
                   Buffer buf)
This method is used to insert bytes into the Buffer at the specified position. This will insert the bytes into the Buffer without over writing any bytes in the Buffer. This will simply move the bytes that come before the specified position up the ways and insert the data. This will throw an IndexOutOfBoundsException if the insert is done at a position where there is no bytes, i.e. must be in the bounds.

Parameters:
pos - this is the position within the Buffer to insert data
buf - this is the data that is to be inserted into the Buffer

insert

public void insert(int pos,
                   Buffer buf,
                   int off,
                   int len)
This method is used to insert bytes into the Buffer at the specified position. This will insert the bytes into the Buffer without over writing any bytes in the Buffer. This will simply move the bytes that come before the specified position up the ways and insert the data. This will throw an IndexOutOfBoundsException if the insert is done at a position where there is no bytes, i.e. must be in the bounds.

Parameters:
pos - this is the position within the Buffer to insert data
buf - this is the data that is to be inserted into the Buffer
len - this is the number of bytes that are to be taken
off - this is the offset to take the bytes from the array

delete

public void delete(int pos)
This is used to delete a region of data from the Buffer. This will ensure that all the bytes that follow the position of the delete will be copied down the so that the information is removed from the Buffer.

Parameters:
pos - this is the position that the delete is to be performed on

delete

public void delete(int pos,
                   int len)
This is used to delete a region of data from the Buffer. This will ensure that all the bytes that follow the position of the delete will be copied down the so that the information is removed from the Buffer.

Parameters:
pos - this is the position that the delete is to be performed on
len - this is the number of bytes after pos that are to be removed

regionMatches

public boolean regionMatches(int pos,
                             byte[] b,
                             int off,
                             int len)
This is used to examine the bytes that are stored in the Buffer. This does a byte comparison of the data that is stored in the Buffer. The comparison is done from an arbitrary offset within the Buffer data.

Parameters:
pos - this is the position within the Buffer to compare data
b - this is the data that is to be compared to the Buffer
len - this is the number of bytes that are to be compares
off - this is the offset to compare the bytes from the data
Returns:
this returns true if the region given matches the Buffers

regionMatches

public boolean regionMatches(int pos,
                             Buffer buf,
                             int off,
                             int len)
This is used to examine the bytes that are stored in the Buffer. This does a byte comparison of the data that is stored in the Buffer. The comparison is done from an arbitrary offset within the Buffer data.

Parameters:
pos - this is the position within the Buffer to compare data
buf - this is the data that is to be compared to the Buffer
len - this is the number of bytes that are to be compares
off - this is the offset to compare the bytes from the data
Returns:
this returns true if the region given matches the Buffers.

equals

public boolean equals(Buffer buf)
This is used to compare the contents of one Buffer with the contents of another. If the bytes are that same this is true.

Parameters:
buf - this is the data that is to be compared with this
Returns:
this returns true if the Buffers are equal

setByte

public void setByte(int pos,
                    int b)
This is used to write bytes into the Buffer at an arbitrary position. This unlike the insert methods will overwrite the data found at that position. This will throw an IndexOutOfBoundsException if the position that the data is attempting to write to is greater than the Buffer length.

Parameters:
pos - this is the position within the Buffer to write the data
b - this is the data that is to be written into the Buffer

setBytes

public void setBytes(int pos,
                     byte[] b,
                     int off,
                     int len)
This is used to write bytes into the Buffer at an arbitrary position. This unlike the insert methods will overwrite the data found at that position. This will throw an IndexOutOfBoundsException if the position that the data is attempting to write to is greater than the Buffer length.

Parameters:
pos - this is the position within the Buffer to write the data
b - this is the data that is to be written into the Buffer
len - this is the number of bytes that are to be taken
off - this is the offset to take the bytes from the array

setBytes

public void setBytes(int pos,
                     Buffer buf)
This is used to write bytes into the Buffer at an arbitrary position. This unlike the insert methods will overwrite the data found at that position. This will throw an IndexOutOfBoundsException if the position that the data is attempting to write to is greater than the Buffer length.

Parameters:
pos - this is the position within the Buffer to write the data
buf - this is the data that is to be written into the Buffer

setBytes

public void setBytes(int pos,
                     Buffer buf,
                     int off,
                     int len)
This is used to write bytes into the Buffer at an arbitrary position. This unlike the insert methods will overwrite the data found at that position. This will throw an IndexOutOfBoundsException if the position that the data is attempting to write to is greater than the Buffer length.

Parameters:
pos - this is the position within the Buffer to write the data
buf - this is the data that is to be written into the Buffer
len - this is the number of bytes that are to be taken
off - this is the offset to take the bytes from the array

getByte

public byte getByte(int pos)
This is used to read data from the Buffer. This will read data from the Buffer at an arbitrary position. An IndexOutOfBoundsException will be thrown if there is an attempt to read data outside the Buffers bounds.

Specified by:
getByte in interface ByteStore
Parameters:
pos - this is the position within the Buffer to read the data
Returns:
this will return the byte that can be found at position pos

getBytes

public void getBytes(int pos,
                     byte[] b)
This is used to read data from the Buffer. This will read data from the Buffer at an arbitrary position. An IndexOutOfBoundsException will be thrown if there is an attempt to read data outside the Buffer's bounds.

Specified by:
getBytes in interface ByteStore
Parameters:
pos - this is the position within the Buffer to read the data
b - this is the Buffer that the bytes are to be read into

getBytes

public void getBytes(int pos,
                     byte[] b,
                     int off,
                     int len)
This is used to read data from the Buffer. This will read data from the Buffer at an arbitrary position. An IndexOutOfBoundsException will be thrown if there is an attempt to read data outside the Buffer's bounds.

Specified by:
getBytes in interface ByteStore
Parameters:
pos - this is the position within the Buffer to read the data
b - this is the Buffer that the bytes are to be read into
len - this is the number of bytes to be read from the Buffer
off - this is the offset to take the bytes from the Buffer

writeTo

public void writeTo(java.io.OutputStream out)
             throws java.io.IOException
This is used to emit data from the Buffer out to an OutputStream. This will invoke a direct call to write in the OutputStream. This method will not flush the stream and exceptions will propagate.

Parameters:
out - this is the OutputStream that the byte are to write to
Throws:
java.io.IOException - this will be thrown if there is an I/O error

writeTo

public void writeTo(java.io.OutputStream out,
                    int off,
                    int len)
             throws java.io.IOException
This is used to emit data from the Buffer out to an OutputStream. This will invoke a direct call to write in the OutputStream. This method will not flush the stream and exceptions will propagate.

Parameters:
out - this is the OutputStream that the byte are to write to
len - this is the number of bytes to be write from the Buffer
off - this is the offset to take the bytes from the Buffer
Throws:
java.io.IOException - this will be thrown if there is an I/O error

resize

public void resize(int min)
This ensure that there is enough space in the Buffer to allow for more chars to be added. If the Buffer is already larger than min then the Buffer will not be expanded at all.

Parameters:
min - the minimum size needed for the Buffer

getInputStream

public java.io.InputStream getInputStream()
This method is used so that the Buffer can be represented as an input stream. Note however that this does not make a copy of the data but rather provides direct access to the data that is being used. This means that this should not be used concurrently with Buffers methods.

Returns:
this returns an InputStream of the data within this Buffer

toArray

public byte[] toArray()
This is used to create a copy of the bytes that are stored in the Buffer object. This does not return the internal bytes of the Buffer but rather creates a byte array Buffer.length in length and fills the byte array with the data in the Buffer before its returned.

Returns:
this returns a byte array that contains the Buffers contents

clear

public void clear()
This will clear all data from the Buffer. This simply sets the count to be zero, it will not clear the memory occupied by the instance as the internal buffer will remain.


capacity

public int capacity()
This provides the number of bytes that can fit inside this buffer without requiring an expensive resize. To ensure that memory is not wasted this method should be used.

Returns:
the capacity of this buffer before resizing it

length

public int length()
This returns the number of bytes that have been appended to this Buffer object. It indicates the number of bytes that have been stored rather than the capacity of the buffer.

Specified by:
length in interface ByteStore
Returns:
the number bytes in the Buffer object

toString

public java.lang.String toString()
This method is used to acquire the buffered bytes as a string. This is useful if the contents need to be manipulated as a string or transferred into another encoding. If the UTF-8 content encoding is not supported the platform default is used, however this is unlikely as UTF-8 should be supported.

Overrides:
toString in class java.lang.Object
Returns:
this returns a UTF-8 encoding of the buffer contents