## calypso.util
Class ByteBuf

    java.lang.Object
      |
      +--calypso.util.ByteBuf

public final class ByteBuf
extends java.lang.Object

This class is similar to java/lang/StringBuffer with the following changes:

- Stores bytes, not chars
- None of the methods are synchronized
- There is no sharing of the character array
- Converting to a String requires a copy of the character data
- Alloc and Recycle are provided to speed up allocation
- A bunch of useful operations are provided (comparisons, etc.)

Constructor Summary
`ByteBuf()` Constructs an empty String buffer.
`ByteBuf(byte[] bytes, int offset, int length)`
`ByteBuf(int length)` Constructs an empty byte buffer with the specified initial length.
`ByteBuf(java.lang.String str)` Constructs a byte buffer with the specified initial value.

Method Summary
`static ByteBuf` | `Alloc()` Constructs an empty String buffer, reusing one from the recycler.
`ByteBuf` | `append(boolean b)` Appends a boolean to the end of this buffer.
`ByteBuf` | `append(byte b)` Appends a byte to the end of this buffer.
`ByteBuf` | `append(byte[] str)` Appends an array of bytes to the end of this buffer.
`ByteBuf` | `append(byte[] str, int offset, int len)` Appends a part of an array of characters to the end of this buffer.
`ByteBuf` | `append(ByteBuf buf)`
`ByteBuf` | `append(double d)` Appends a double to the end of this buffer.
`ByteBuf` | `append(float f)` Appends a float to the end of this buffer.
`ByteBuf` | `append(int i)` Appends an integer to the end of this buffer.
`ByteBuf` | `append(long l)` Appends a long to the end of this buffer.
`ByteBuf` | `append(java.lang.Object obj)` Appends an object to the end of this buffer.
`ByteBuf` | `append(java.lang.String str)` Appends a String to the end of this buffer.
`byte` | `byteAt(int index)` Returns the byte at the specified index.
`int` | `capacity()` Returns the current capacity of the String buffer.
`static void` | `EmptyRecycler()` Empty the recycler discarding any cached ByteBuf objects
`void` | `ensureCapacity(int minimumCapacity)` Ensures that the capacity of the buffer is at least equal to the specified minimum.
`boolean` | `equals(ByteBuf anotherString)` Compares this ByteBuf to another ByteBuf.
`boolean` | `equals(java.lang.Object aObject)`
`boolean` | `equals(java.lang.String anotherString)` Compares this ByteBuf to another String.
`boolean` | `equalsIgnoreCase(ByteBuf anotherString)` Compares this ByteBuf to another ByteBuf.
`void` | `fullDump(java.io.PrintStream out)` Write to the given output stream a detailed description of each byte in this buffer.
`void` | `fullDump(java.io.PrintStream out, int start, int end)` Write to the given output stream a detailed description of the given bytes in this buffer.
`void` | `getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin)` Copies the characters of the specified substring (determined by srcBegin and srcEnd) into the character array, starting at the array's dstBegin location.
`int` | `indexOf(int ch)`
`int` | `indexOf(int ch, int fromIndex)`
`ByteBuf` | `insert(int offset, boolean b)` Inserts a boolean into the String buffer.
`ByteBuf` | `insert(int offset, byte b)` Inserts a byte into the String buffer.
`ByteBuf` | `insert(int offset, byte[] str)` Inserts an array of bytes into the String buffer.
`ByteBuf` | `insert(int offset, double d)` Inserts a double into the String buffer.
`ByteBuf` | `insert(int offset, float f)` Inserts a float into the String buffer.
`ByteBuf` | `insert(int offset, int i)` Inserts an integer into the String buffer.
`ByteBuf` | `insert(int offset, long l)` Inserts a long into the String buffer.
`ByteBuf` | `insert(int offset, java.lang.Object obj)` Inserts an object into the String buffer.
`ByteBuf` | `insert(int offset, java.lang.String str)` Inserts a String into the String buffer.
`int` | `length()` Returns the length (character count) of the buffer.
`java.io.InputStream` | `makeInputStream()` Creates a new InputStream whose content is this ByteBuf.
`int` | `read(java.io.InputStream file, int max_bytes)` Invokes InputStream.read(), appending the bytes to this Bytebuf.
`int` | `read(java.io.RandomAccessFile file, int max_bytes)` Invokes RandomAccessFile.read(), appending the bytes to this Bytebuf.
`static void` | `Recycle(ByteBuf aBuf)` Release a ByteBuf to the recycler.
`boolean` | `regionMatches(boolean ignoreCase, int toffset, byte[] other, int ooffset, int len)` Tests if two byte regions are equal.
`boolean` | `regionMatches(boolean ignoreCase, int toffset, ByteBuf other, int ooffset, int len)`
`boolean` | `regionMatches(boolean ignoreCase, int toffset, java.lang.String other, int ooffset, int len)` Tests if two byte regions are equal.
`boolean` | `regionMatches(int toffset, byte[] other, int ooffset, int len)` Tests if two byte regions are equal.
`boolean` | `regionMatches(int toffset, ByteBuf other, int ooffset, int len)`
`boolean` | `regionMatches(int toffset, java.lang.String other, int ooffset, int len)` Tests if two byte regions are equal.
`void` | `remove(int fromIndex)`
`void` | `remove(int fromIndex, int toIndex)` Remove characters from the ByteBuf starting at fromIndex and up to but not including toIndex.
`ByteBuf` | `reverse()` Reverse the order of the characters in the String buffer.
`void` | `setByteAt(int index, byte b)` Changes the byte at the specified index to be ch.
`void` | `setLength(int newLength)` Sets the length of the String.
`byte[]` | `toBytes()`
`int` | `toInteger()`
`java.lang.String` | `toString()` Converts to a String representing the data in the buffer.
`ByteBuf` | `trim()`
`void` | `write(java.io.OutputStream out)` Writes the contents to the given output stream.
`void` | `write(java.io.RandomAccessFile out)` Writes the contents to the given RandomAccessFile.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### ByteBuf

    public ByteBuf()

  Constructs an empty String buffer.

### ByteBuf

    public ByteBuf(int length)

  Constructs an empty byte buffer with the specified initial length.
  Parameters:
    `length` - the initial length

### ByteBuf

    public ByteBuf(java.lang.String str)

  Constructs a byte buffer with the specified initial value.
  Parameters:
    `str` - the initial value of the buffer

### ByteBuf

    public ByteBuf(byte[] bytes,
                   int offset,
                   int length)

Method Detail

### Alloc

    public static ByteBuf Alloc()

  Constructs an empty String buffer, reusing one from the recycler.

### Recycle

    public static void Recycle(ByteBuf aBuf)

  Release a ByteBuf to the recycler. It is up to the caller to ensure that buffer is no longer being used otherwise unpredicatable program behavior will result.

### EmptyRecycler

    public static void EmptyRecycler()

  Empty the recycler discarding any cached ByteBuf objects

### length

    public int length()

  Returns the length (character count) of the buffer.

### capacity

    public int capacity()

  Returns the current capacity of the String buffer. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur.

### ensureCapacity

    public void ensureCapacity(int minimumCapacity)

  Ensures that the capacity of the buffer is at least equal to the specified minimum.
  Parameters:
    `minimumCapacity` - the minimum desired capacity

### setLength

    public void setLength(int newLength)

  Sets the length of the String. If the length is reduced, characters are lost. If the length is extended, the values of the new characters are set to 0.
  Parameters:
    `newLength` - the new length of the buffer
  Throws:
    StringIndexOutOfBoundsException - If the length is invalid.

### byteAt

    public byte byteAt(int index)

  Returns the byte at the specified index. An index ranges from 0..length()-1.
  Parameters:
    `index` - the index of the desired character
  Throws:
    StringIndexOutOfBoundsException - If the index is invalid.

### getBytes

    public void getBytes(int srcBegin,
                         int srcEnd,
                         byte[] dst,
                         int dstBegin)

  Copies the characters of the specified substring (determined by srcBegin and srcEnd) into the character array, starting at the array's dstBegin location. Both srcBegin and srcEnd must be legal indexes into the buffer.
  Parameters:
    `srcBegin` - begin copy at this offset in the String
    `srcEnd` - stop copying at this offset in the String
    `dst` - the array to copy the data into
    `dstBegin` - offset into dst
  Throws:
    StringIndexOutOfBoundsException - If there is an invalid index into the buffer.

### setByteAt

    public void setByteAt(int index,
                          byte b)

  Changes the byte at the specified index to be ch.
  Parameters:
    `index` - the index of the character
    `ch` - the new character
  Throws:
    StringIndexOutOfBoundsException - If the index is invalid.

### append

    public ByteBuf append(java.lang.Object obj)

  Appends an object to the end of this buffer.
  Parameters:
    `obj` - the object to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(java.lang.String str)

  Appends a String to the end of this buffer. This just appends one byte per char; it strips off the upper 8 bits. If you want the localized method of converting chars to bytes, use append(String.getBytes()).
  Parameters:
    `str` - the String to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(byte[] str)

  Appends an array of bytes to the end of this buffer.
  Parameters:
    `str` - the characters to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(byte[] str,
                          int offset,
                          int len)

  Appends a part of an array of characters to the end of this buffer.
  Parameters:
    `str` - the characters to be appended
    `offset` - where to start
    `len` - the number of characters to add
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(ByteBuf buf)

### append

    public ByteBuf append(boolean b)

  Appends a boolean to the end of this buffer.
  Parameters:
    `b` - the boolean to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(byte b)

  Appends a byte to the end of this buffer.
  Parameters:
    `ch` - the character to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(int i)

  Appends an integer to the end of this buffer.
  Parameters:
    `i` - the integer to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(long l)

  Appends a long to the end of this buffer.
  Parameters:
    `l` - the long to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(float f)

  Appends a float to the end of this buffer.
  Parameters:
    `f` - the float to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### append

    public ByteBuf append(double d)

  Appends a double to the end of this buffer.
  Parameters:
    `d` - the double to be appended
  Returns:
    the ByteBuf itself, NOT a new one.

### insert

    public ByteBuf insert(int offset,
                          java.lang.Object obj)

  Inserts an object into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `obj` - the object to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public ByteBuf insert(int offset,
                          java.lang.String str)

  Inserts a String into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `str` - the String to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public ByteBuf insert(int offset,
                          byte[] str)

  Inserts an array of bytes into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `str` - the characters to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public ByteBuf insert(int offset,
                          boolean b)

  Inserts a boolean into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `b` - the boolean to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public ByteBuf insert(int offset,
                          byte b)

  Inserts a byte into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `ch` - the character to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset invalid.

### insert

    public ByteBuf insert(int offset,
                          int i)

  Inserts an integer into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `i` - the integer to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public ByteBuf insert(int offset,
                          long l)

  Inserts a long into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `l` - the long to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public ByteBuf insert(int offset,
                          float f)

  Inserts a float into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `f` - the float to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### insert

    public ByteBuf insert(int offset,
                          double d)

  Inserts a double into the String buffer.
  Parameters:
    `offset` - the offset at which to insert
    `d` - the double to insert
  Returns:
    the ByteBuf itself, NOT a new one.
  Throws:
    StringIndexOutOfBoundsException - If the offset is invalid.

### reverse

    public ByteBuf reverse()

  Reverse the order of the characters in the String buffer.

### toString

    public java.lang.String toString()

  Converts to a String representing the data in the buffer.
  Overrides:
    toString in class java.lang.Object

### toBytes

    public byte[] toBytes()

### equalsIgnoreCase

    public boolean equalsIgnoreCase(ByteBuf anotherString)

  Compares this ByteBuf to another ByteBuf. Returns true if the other ByteBuf is equal to this ByteBuf; that is, has the same length and the same characters in the same sequence. Upper case characters are folded to lower case before they are compared.
  Parameters:
    `anotherString` - the String to compare this String against
  Returns:
    true if the Strings are equal, ignoring case; false otherwise.

### equals

    public boolean equals(java.lang.Object aObject)

  Overrides:
    equals in class java.lang.Object

### equals

    public boolean equals(ByteBuf anotherString)

  Compares this ByteBuf to another ByteBuf. Returns true if the other ByteBuf is equal to this ByteBuf; that is, has the same length and the same characters in the same sequence.
  Parameters:
    `anotherString` - the String to compare this String against
  Returns:
    true if the Strings are equal, ignoring case; false otherwise.

### equals

    public boolean equals(java.lang.String anotherString)

  Compares this ByteBuf to another String. Returns true if the other String is equal to this ByteBuf; that is, has the same length and the same characters in the same sequence. (No localization is done; if the string doesn't contain 8-bit chars, it won't be equal to this ByteBuf.)
  Parameters:
    `anotherString` - the String to compare this String against
  Returns:
    true if the Strings are equal, ignoring case; false otherwise.

### regionMatches

    public boolean regionMatches(int toffset,
                                 byte[] other,
                                 int ooffset,
                                 int len)

  Tests if two byte regions are equal.

  If `toffset` or `ooffset` is negative, or if `toffset`+`length` is greater than the length of this ByteBuf, or if `ooffset`+`length` is greater than the length of the argument, then this method returns `false`.

  Parameters:
    `toffset` - the starting offset of the subregion in this ByteBuf.
    `other` - the other bytes.
    `ooffset` - the starting offset of the subregion in the argument.
    `len` - the number of bytes to compare.
  Returns:
    `true` if the specified subregion of this ByteBuf exactly matches the specified subregion of the argument; `false` otherwise.

### regionMatches

    public boolean regionMatches(boolean ignoreCase,
                                 int toffset,
                                 byte[] other,
                                 int ooffset,
                                 int len)

  Tests if two byte regions are equal.

  If `toffset` or `ooffset` is negative, or if `toffset`+`length` is greater than the length of this ByteBuf, or if `ooffset`+`length` is greater than the length of the argument, then this method returns `false`.

  Parameters:
    `ignoreCase` - if `true`, ignore case when comparing bytes (treating them as characters).
    `toffset` - the starting offset of the subregion in this ByteBuf.
    `other` - the other bytes.
    `ooffset` - the starting offset of the subregion in the argument.
    `len` - the number of bytes to compare.
  Returns:
    `true` if the specified subregion of this ByteBuf matches the specified subregion of the argument; `false` otherwise. Whether the matching is exact or case insensitive depends on the `ignoreCase` argument.

### regionMatches

    public boolean regionMatches(int toffset,
                                 ByteBuf other,
                                 int ooffset,
                                 int len)

### regionMatches

    public boolean regionMatches(boolean ignoreCase,
                                 int toffset,
                                 ByteBuf other,
                                 int ooffset,
                                 int len)

### regionMatches

    public boolean regionMatches(int toffset,
                                 java.lang.String other,
                                 int ooffset,
                                 int len)

  Tests if two byte regions are equal.

  If `toffset` or `ooffset` is negative, or if `toffset`+`length` is greater than the length of this ByteBuf, or if `ooffset`+`length` is greater than the length of the argument, then this method returns `false`.

  Parameters:
    `toffset` - the starting offset of the subregion in this ByteBuf.
    `other` - the other String.
    `ooffset` - the starting offset of the subregion in the argument.
    `len` - the number of bytes/characters to compare.
  Returns:
    `true` if the specified subregion of this ByteBuf exactly matches the specified subregion of the String argument; `false` otherwise.

### regionMatches

    public boolean regionMatches(boolean ignoreCase,
                                 int toffset,
                                 java.lang.String other,
                                 int ooffset,
                                 int len)

  Tests if two byte regions are equal.

  If `toffset` or `ooffset` is negative, or if `toffset`+`length` is greater than the length of this ByteBuf, or if `ooffset`+`length` is greater than the length of the argument, then this method returns `false`.

  Parameters:
    `ignoreCase` - if `true`, ignore case when comparing bytes (treating them as characters).
    `toffset` - the starting offset of the subregion in this ByteBuf.
    `other` - the other String.
    `ooffset` - the starting offset of the subregion in the String argument.
    `len` - the number of bytes to compare.
  Returns:
    `true` if the specified subregion of this ByteBuf matches the specified subregion of the String argument; `false` otherwise. Whether the matching is exact or case insensitive depends on the `ignoreCase` argument.

### indexOf

    public int indexOf(int ch)

### indexOf

    public int indexOf(int ch,
                       int fromIndex)

### remove

    public void remove(int fromIndex)

### remove

    public void remove(int fromIndex,
                       int toIndex)

  Remove characters from the ByteBuf starting at fromIndex and up to but not including toIndex. If toIndex is beyond the length of the ByteBuf then it is automatically clamped to the end of the ByteBuf. If fromIndex is out of range a StringIndexOutOfBoundsException is thrown.

### toInteger

    public int toInteger()
                  throws java.lang.NumberFormatException

### trim

    public ByteBuf trim()

### fullDump

    public void fullDump(java.io.PrintStream out)

  Write to the given output stream a detailed description of each byte in this buffer.

### fullDump

    public void fullDump(java.io.PrintStream out,
                         int start,
                         int end)

  Write to the given output stream a detailed description of the given bytes in this buffer.

### read

    public int read(java.io.InputStream file,
                    int max_bytes)
             throws java.io.IOException

  Invokes InputStream.read(), appending the bytes to this Bytebuf.
  Returns:
    the number of bytes read, or -1 if eof.

### read

    public int read(java.io.RandomAccessFile file,
                    int max_bytes)
             throws java.io.IOException

  Invokes RandomAccessFile.read(), appending the bytes to this Bytebuf. (A RandomAccessFile is not an InputStream, because Java is a crock.)
  Returns:
    the number of bytes read, or -1 if eof.

### write

    public void write(java.io.OutputStream out)
               throws java.io.IOException

  Writes the contents to the given output stream.

### write

    public void write(java.io.RandomAccessFile out)
               throws java.io.IOException

  Writes the contents to the given RandomAccessFile.

### makeInputStream

    public java.io.InputStream makeInputStream()

  Creates a new InputStream whose content is this ByteBuf. Note that changing the ByteBuf can affect the stream; the data is not copied.