ByteBuilder

java.lang.Object
- com.heirloomcomputing.epli.runtime.ByteBuilder

All Implemented Interfaces:

java.util.Iterator<java.lang.Object>
```
public class ByteBuilder
extends java.lang.Object
implements java.util.Iterator<java.lang.Object>
```
Like StringBuilder, but for byte[]s and works in both directions, append(*) for adding to a buffer and nextbyte*() to retrieve consecutive pieces of the buffer. suitable for conversion of wrappered types to/from byte arrays. also can deal with Elastic PL/I Group objects. it can also be used as an Iterator, but the native next() only works if you have used append() to built up the ByteBuilder wish there was non-abstract Java ByteBuffer that was simply mapped to byte[]

Author:

Heirloom Computing, Inc.

Constructor Summary

Constructors
Constructor and Description
`ByteBuilder()` Create an empty ByteBuilder, ready for append()ing
`ByteBuilder(byte[] buf)` Create a filled ByteBuilder, ready for either appending or next()ing
`ByteBuilder(byte[] buf, int offset, int length)` Create a filled ByteBuilder, ready for either appending or next()ing
`ByteBuilder(int size)` Create an ByteBuilder of a certain size, ready for append()ing
`ByteBuilder(java.lang.Object buf)` Create a filled ByteBuilder, prefilled with a PL/I var

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`append(Area A)` append - add a Area to the end
`void`	`append(Array<?> A)` append - add a Array to the end
`void`	`append(java.math.BigDecimal B)` append - add a BigDecimal to the end
`void`	`append(java.math.BigInteger B)` append - add a BigInteger to the end
`void`	`append(BitN B)` append - add a BitN to the end
`void`	`append(java.lang.Boolean B)` append - add a Boolean to the end
`void`	`append(java.lang.Byte B)` append - add a Byte to the end
`void`	`append(byte[] b)` append - add a byte string to the end
`void`	`append(ByteBuilder b)` append - add a ByteBuilder to this ByteBuilder
`void`	`append(Complex C)` append - add a Complex to the end
`void`	`append(java.lang.Double D)` append - add a Double to the end
`void`	`append(EPLITYPES type, java.lang.Object O)` append - add an Object (which still must be an instanceof a wrappered primitive) to the end
`void`	`append(EPLITYPES type, java.lang.Object O, short len)` append - add an Object (which still must be an instanceof a wrappered primitive) to the end.
`void`	`append(FixedBin FB)` append - add a FixedBin to the end
`void`	`append(java.lang.Float F)` append - add a Float to the end
`void`	`append(Group G)` append - add a Elastic PL/I Group to the end
`void`	`append(java.lang.Integer I)` append - add an Integer to the end
`void`	`append(java.lang.Long L)` append - add an Long to the end
`void`	`append(java.lang.Object O)` append - add an Object (which still must be an instanceof a wrappered primitive) to the end
`void`	`append(java.lang.Object O, short len)` append - add an Object (which still must be an instanceof a wrappered primitive) to the end.
`void`	`append(Offset<?> O)` append - add a Offset to the end
`void`	`append(Picture P)` append - add a Picture to the end
`void`	`append(Pointer<?> P)` append - add a Pointer to the end
`void`	`append(java.lang.Short S)` append - add a Short to the end
`void`	`append(java.lang.String S)` append - add a Varying Char String to the end
`void`	`append(java.lang.String FS, int len)` append - add a Fixed Char String to the end
`void`	`clear()` clear - clear the ByteBuffer of contents
`byte`	`getByte(int offset)` low level individual byte getter
`int`	`getItems()` Get the number of items in this ByteBuilder
`int`	`getSize()` Get the current (used) length of the ByteBuilder byte array buffer
`boolean`	`hasNext()` hasNext() - return whether there are more bytes to be retrieved from the buffer (when used before non-anonymous nextInteger(), nextString(len), etc.
`boolean`	`hasNextItem()` hasNextItem() - return whether there are more items to be retrieved from the buffer (when used before anonymous "nextItem()" as opposed to "next()") note: not an Override of Iterator
`int`	`length()` Get the current (used) length of the ByteBuilder byte array buffer
`static void`	`main(java.lang.String[] args)` unit test Usage: java ByteBuilder INTEGER=22\|SHORT=22\|STRING=hi\|FLOAT=2.3\|DOUBLE=2.3\|LONG=123 ...
`java.lang.Object`	`next()` next() - don't know what type the next one is, somewhat useless but required for Iterators
`Area`	`nextArea()` retrieve the Area
`Array<?>`	`nextArray()` retrieve the Array
`java.math.BigDecimal`	`nextBigDecimal()` retrieve the next BigDecimal requiring the next item is a BigDecimal
`java.math.BigDecimal`	`nextBigDecimal(int m, int scale)` nextBigDecimal - get the next sequence of bytes as an FIXED DEC(n) given its scale
`java.lang.Object`	`nextBigInteger()` retrieve the next BigInteger
`java.math.BigInteger`	`nextBigInteger(int m)` nextBigInteger - get the next sequence of bytes as an FIXED BIN(n) where n > 63 and represented as a BigInteger
`BitN`	`nextBitN(int m)` nextBitN - get the next sequence of bytes as an BIT(m) that corresponds to n bytes in the buffer (n*8=m)
`java.lang.Boolean`	`nextBoolean()` nextBoolean - get the next byte as an Boolean
`java.lang.Byte`	`nextByte()` nextByte - get the byte as an Byte
`byte[]`	`nextBytes(int n)` Return the next sequence of n bytes as byte array
`Complex`	`nextComplex()` nextComplex - get the next sequence of bytes as an Complex that corresponds to n bytes in the buffer (n*8=m)
`java.lang.Double`	`nextDouble()` nextDouble - get the next sequence of bytes as an Double
`FixedBin`	`nextFixedBin()` retrieve the next FixedBin(p,q)
`FixedBin`	`nextFixedBin(int n)` nextFixedBin - get the next sequence of bytes as a FixedBin
`FixedBin`	`nextFixedBin(int n, int p, int q)` nextFixedBin - get the next sequence of bytes as a FixedBin
`java.lang.Float`	`nextFloat()` nextFloat - get the next sequence of bytes as an Float
`Group`	`nextGroup(int n)` nextGroup - get the next sequence of n bytes as a Group
`java.lang.Integer`	`nextInteger()` nextInteger - get the next sequence of bytes as an Integer
`java.lang.Long`	`nextLong()` nextLong - get the next sequence of bytes as an Long
`Offset<?>`	`nextOffset()` retrieve the next Offset
`Offset<?>`	`nextOffset(int n)` cannot return the next sequence of bytes as an Offset because we don't know what ? is
`int`	`nextOrdinal()` retrieve the next enum (ordinal)
`java.lang.Object`	`nextPicture(int n)` Return the next sequence of bytes that correspond to the picture as a Picture, used as a counter to append((Picture) O)
`java.lang.Object`	`nextPicture(java.lang.String pic)` Return the next sequence of bytes that correspond to the given picture specification as a Picture
`Pointer<?>`	`nextPointer()` retrieve the next Pointer
`Pointer<?>`	`nextPointer(int n)` cannot return the next sequence of bytes as an Pointer because we don't know what ? is
`java.lang.Short`	`nextShort()` nextShort - get the next sequence of bytes as an Short
`java.lang.String`	`nextString(int n)` Return the next sequence of n bytes as an String.
`java.lang.String`	`nextString(short n)` Return the next sequence of n bytes as an String.
`void`	`reset()` reset - reset the ByteBuffer allowing it to be read again
`void`	`setByte(byte data, int offset)` low level individual byte setter
`byte[]`	`toBytes()` Return the ByteBuilder as a byte array
`java.lang.String`	`toDebugString()` Provided as a debugging aid
`java.lang.String`	`toString()` Provided as a debugging aid because presumably you should be using StringBuilder instead

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

Methods inherited from interface java.util.Iterator
forEachRemaining, remove

- Constructor Detail
  - ByteBuilder
```
public ByteBuilder()
```
    Create an empty ByteBuilder, ready for append()ing
  - ByteBuilder
```
public ByteBuilder(int size)
```
    Create an ByteBuilder of a certain size, ready for append()ing
  - ByteBuilder
```
public ByteBuilder(byte[] buf)
```
    Create a filled ByteBuilder, ready for either appending or next()ing
    
    Parameters:
    
    buf - - create a ByteBuilder from a byte array
  - ByteBuilder
```
public ByteBuilder(byte[] buf,
                   int offset,
                   int length)
```
    Create a filled ByteBuilder, ready for either appending or next()ing
    
    Parameters:
    
    buf - - create a ByteBuilder from a byte array
  - ByteBuilder
```
public ByteBuilder(java.lang.Object buf)
```
    Create a filled ByteBuilder, prefilled with a PL/I var
    
    Parameters:
    
    buf - - create a ByteBuilder from a PL/I var (primitive wrappered object, FixedBin, etc
- Method Detail
  - toBytes
```
public byte[] toBytes()
```
    Return the ByteBuilder as a byte array
    
    Returns:
    
    - a copy of the ByteBuilder as a sequence of bytes
  - toString
```
public java.lang.String toString()
```
    Provided as a debugging aid because presumably you should be using StringBuilder instead
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a String of the buffer in "dump" format (hex digits followed by ascii chars for each byte)
  - toDebugString
```
public java.lang.String toDebugString()
```
    Provided as a debugging aid
    
    Returns:
    
    same as toString() with < 0x20 replaced as '.'
  - length
```
public int length()
```
    Get the current (used) length of the ByteBuilder byte array buffer
    
    Returns:
    
    the current length of used bytes in the buffer
  - getSize
```
public int getSize()
```
    Get the current (used) length of the ByteBuilder byte array buffer
    
    Returns:
    
    the current length of used bytes in the buffer
  - getItems
```
public int getItems()
```
    Get the number of items in this ByteBuilder
    
    Returns:
    
    the number of items in this ByteBuilder
  - getByte
```
public byte getByte(int offset)
```
    low level individual byte getter
    
    Parameters:
    
    offset - - the offset of the byte within the buffer to get
    
    Returns:
    
    - the byte to get
    
    Throws:
    
    Condition.CONDITION.ERROR - (TOOSMALL) if offset out-of-range
  - setByte
```
public void setByte(byte data,
                    int offset)
```
    low level individual byte setter
    
    Parameters:
    
    data - - the data byte to set
    
    offset - - the offset of the byte within the buffer to set
    
    Throws:
    
    Condition.CONDITION.ERROR - (TOOSMALL) if offset out-of-range
  - append
```
public void append(ByteBuilder b)
```
    append - add a ByteBuilder to this ByteBuilder
    
    Parameters:
    
    b - the ByteBuilder to append
  - append
```
public void append(byte[] b)
```
    append - add a byte string to the end
    
    Parameters:
    
    b - the byte array to append
  - append
```
public void append(java.lang.Long L)
```
    append - add an Long to the end
    
    Parameters:
    
    L - the Long to add
  - append
```
public void append(java.lang.Integer I)
```
    append - add an Integer to the end
    
    Parameters:
    
    I - the Integer to add
  - append
```
public void append(java.lang.Byte B)
```
    append - add a Byte to the end
    
    Parameters:
    
    B - the Short to add
  - append
```
public void append(java.lang.Short S)
```
    append - add a Short to the end
    
    Parameters:
    
    S - the Short to add
  - append
```
public void append(java.lang.String S)
```
    append - add a Varying Char String to the end
    
    Parameters:
    
    S - the String to add
  - append
```
public void append(java.lang.String FS,
                   int len)
```
    append - add a Fixed Char String to the end
    
    Parameters:
    
    FS - the String to add
  - append
```
public void append(java.lang.Float F)
```
    append - add a Float to the end
    
    Parameters:
    
    F - the Float to add
  - append
```
public void append(java.lang.Double D)
```
    append - add a Double to the end
    
    Parameters:
    
    D - the Double to add
  - append
```
public void append(Group G)
```
    append - add a Elastic PL/I Group to the end
    
    Parameters:
    
    G - the Group to add
  - append
```
public void append(java.math.BigDecimal B)
```
    append - add a BigDecimal to the end
    
    Parameters:
    
    B - the BigDecimal to add
  - append
```
public void append(java.math.BigInteger B)
```
    append - add a BigInteger to the end
    
    Parameters:
    
    B - the BigInteger to add
  - append
```
public void append(java.lang.Boolean B)
```
    append - add a Boolean to the end
    
    Parameters:
    
    B - the Boolean to add
  - append
```
public void append(BitN B)
```
    append - add a BitN to the end
    
    Parameters:
    
    B - the BitN to add
  - append
```
public void append(FixedBin FB)
```
    append - add a FixedBin to the end
    
    Parameters:
    
    FB - the FixedBin to add
  - append
```
public void append(Array<?> A)
```
    append - add a Array to the end
    
    Parameters:
    
    A - the Array to add
  - append
```
public void append(Area A)
```
    append - add a Area to the end
    
    Parameters:
    
    A - the Area to add
  - append
```
public void append(Offset<?> O)
```
    append - add a Offset to the end
    
    Parameters:
    
    O - the Offset to add
  - append
```
public void append(Pointer<?> P)
```
    append - add a Pointer to the end
    
    Parameters:
    
    P - the Pointer to add
  - append
```
public void append(Complex C)
```
    append - add a Complex to the end
    
    Parameters:
    
    C - the Complex to add
  - append
```
public void append(Picture P)
```
    append - add a Picture to the end
    
    Parameters:
    
    P - the Picture to add
  - append
```
public void append(java.lang.Object O)
```
    append - add an Object (which still must be an instanceof a wrappered primitive) to the end
    
    Parameters:
    
    O - the Object to add
  - append
```
public void append(EPLITYPES type,
                   java.lang.Object O)
```
    append - add an Object (which still must be an instanceof a wrappered primitive) to the end
    
    Parameters:
    
    type - - EPLITYPES type
    
    O - the Object to add
  - append
```
public void append(java.lang.Object O,
                   short len)
```
    append - add an Object (which still must be an instanceof a wrappered primitive) to the end. same as append(Object) for all Objects other than String. For String, use the len parameter to pad or trim the String to a particular lenbuffer
    
    Parameters:
    
    O - the Object to add
    
    len - the lenbuffer to pad or trim a String object
  - append
```
public void append(EPLITYPES type,
                   java.lang.Object O,
                   short len)
```
    append - add an Object (which still must be an instanceof a wrappered primitive) to the end. same as append(Object) for all Objects other than String. For String, use the len parameter to pad or trim the String to a particular lenbuffer
    
    Parameters:
    
    type - - EPLITYPES type
    
    O - the Object to add
    
    len - the lenbuffer to pad or trim a String object
  - clear
```
public void clear()
```
    clear - clear the ByteBuffer of contents
  - reset
```
public void reset()
```
    reset - reset the ByteBuffer allowing it to be read again
  - nextBoolean
```
public java.lang.Boolean nextBoolean()
```
    nextBoolean - get the next byte as an Boolean
    
    Returns:
    
    the next bytes as Boolean
  - nextByte
```
public java.lang.Byte nextByte()
```
    nextByte - get the byte as an Byte
    
    Returns:
    
    the next bytes as Byte
  - nextShort
```
public java.lang.Short nextShort()
```
    nextShort - get the next sequence of bytes as an Short
    
    Returns:
    
    the next bytes as Short
  - nextInteger
```
public java.lang.Integer nextInteger()
```
    nextInteger - get the next sequence of bytes as an Integer
    
    Returns:
    
    the next bytes as Integer
  - nextLong
```
public java.lang.Long nextLong()
```
    nextLong - get the next sequence of bytes as an Long
    
    Returns:
    
    the next bytes as Integer
  - nextFloat
```
public java.lang.Float nextFloat()
```
    nextFloat - get the next sequence of bytes as an Float
    
    Returns:
    
    the next bytes as Float
  - nextDouble
```
public java.lang.Double nextDouble()
```
    nextDouble - get the next sequence of bytes as an Double
    
    Returns:
    
    the next bytes as Double
  - nextFixedBin
```
public FixedBin nextFixedBin(int n)
```
    nextFixedBin - get the next sequence of bytes as a FixedBin
    
    Parameters:
    
    n - - the number of bytes to convert
    
    Returns:
    
    the next bytes as FixedBin
  - nextFixedBin
```
public FixedBin nextFixedBin(int n,
                             int p,
                             int q)
```
    nextFixedBin - get the next sequence of bytes as a FixedBin
    
    Parameters:
    
    n - - the number of bytes to convert
    
    p - - the number of digits of precision
    
    q - - the number of digits of scale
    
    Returns:
    
    the next bytes as FixedBin
  - nextString
```
public java.lang.String nextString(short n)
```
    Return the next sequence of n bytes as an String. If the buffer is too short, do not throw a TOOSMALL condition but pad the string with blanks because if this is written/read to a LINESEQUENTIAL COBOLFile blanks are trimmed on write.
    
    Parameters:
    
    n - - the number of nextbyte bytes to consider as a string
    
    Returns:
    
    the next bytes as String
  - nextString
```
public java.lang.String nextString(int n)
```
    Return the next sequence of n bytes as an String. If the buffer is too short, do not throw a TOOSMALL condition but pad the string with blanks because if this is written/read to a LINESEQUENTIAL COBOLFile blanks are trimmed on write.
    
    Parameters:
    
    n - - the number of nextbyte bytes to consider as a string
    
    Returns:
    
    the next bytes as String
  - nextPicture
```
public java.lang.Object nextPicture(java.lang.String pic)
```
    Return the next sequence of bytes that correspond to the given picture specification as a Picture
    
    Parameters:
    
    pic - - the picture specification
    
    Returns:
    
    a Picture
  - nextPicture
```
public java.lang.Object nextPicture(int n)
```
    Return the next sequence of bytes that correspond to the picture as a Picture, used as a counter to append((Picture) O)
    
    Parameters:
    
    n - - the length of the picture in bytes
    
    Returns:
    
    a Picture
  - nextBitN
```
public BitN nextBitN(int m)
```
    nextBitN - get the next sequence of bytes as an BIT(m) that corresponds to n bytes in the buffer (n*8=m)
    
    Returns:
    
    the next bytes as BitN
  - nextBigInteger
```
public java.math.BigInteger nextBigInteger(int m)
```
    nextBigInteger - get the next sequence of bytes as an FIXED BIN(n) where n > 63 and represented as a BigInteger
    
    Returns:
    
    the next bytes as Boolean
  - nextBigDecimal
```
public java.math.BigDecimal nextBigDecimal(int m,
                                           int scale)
```
    nextBigDecimal - get the next sequence of bytes as an FIXED DEC(n) given its scale
    
    Parameters:
    
    m - - number of bytes comprising the unscaled (BigInteger) value in the bytebuffer
    
    scale - - integer scale amount
    
    Returns:
    
    the next bytes as Boolean
  - nextComplex
```
public Complex nextComplex()
```
    nextComplex - get the next sequence of bytes as an Complex that corresponds to n bytes in the buffer (n*8=m)
    
    Returns:
    
    the next bytes as Boolean
  - nextOffset
```
public Offset<?> nextOffset(int n)
```
    cannot return the next sequence of bytes as an Offset because we don't know what ? is
  - nextPointer
```
public Pointer<?> nextPointer(int n)
```
    cannot return the next sequence of bytes as an Pointer because we don't know what ? is
  - nextBytes
```
public byte[] nextBytes(int n)
```
    Return the next sequence of n bytes as byte array
    
    Parameters:
    
    n - - the number of nextbyte bytes to consider as a sub-byte array
    
    Returns:
    
    the next bytes as a byte array
  - nextOrdinal
```
public int nextOrdinal()
```
    retrieve the next enum (ordinal)
    
    Returns:
    
    the Enum or enum's ordinal() value
  - nextFixedBin
```
public FixedBin nextFixedBin()
```
    retrieve the next FixedBin(p,q)
    
    Returns:
    
    the FixedBin(p,q) value
  - nextOffset
```
public Offset<?> nextOffset()
```
    retrieve the next Offset
    
    Returns:
    
    the Offset value
  - nextPointer
```
public Pointer<?> nextPointer()
```
    retrieve the next Pointer
    
    Returns:
    
    the Pointer value
  - nextArea
```
public Area nextArea()
```
    retrieve the Area
    
    Returns:
    
    the Area value
  - nextArray
```
public Array<?> nextArray()
```
    retrieve the Array
    
    Returns:
    
    the Array object
  - nextBigDecimal
```
public java.math.BigDecimal nextBigDecimal()
```
    retrieve the next BigDecimal requiring the next item is a BigDecimal
    
    Returns:
    
    the BigDecimal value
  - nextBigInteger
```
public java.lang.Object nextBigInteger()
```
    retrieve the next BigInteger
    
    Returns:
    
    the BigInteger value
  - nextGroup
```
public Group nextGroup(int n)
```
    nextGroup - get the next sequence of n bytes as a Group
    
    Parameters:
    
    n - - the number of nextbyte bytes to consider as a Group
    
    Returns:
    
    the next bytes as Group note: Group is worthless without knowing its containing fields and this Group has only one unknown byte sequence
  - hasNext
```
public boolean hasNext()
```
    hasNext() - return whether there are more bytes to be retrieved from the buffer (when used before non-anonymous nextInteger(), nextString(len), etc. when not relying on self-describing buffer items
    
    Specified by:
    
    hasNext in interface java.util.Iterator<java.lang.Object>
  - hasNextItem
```
public boolean hasNextItem()
```
    hasNextItem() - return whether there are more items to be retrieved from the buffer (when used before anonymous "nextItem()" as opposed to "next()") note: not an Override of Iterator
  - next
```
public java.lang.Object next()
```
    next() - don't know what type the next one is, somewhat useless but required for Iterators
    
    Specified by:
    
    next in interface java.util.Iterator<java.lang.Object>
    
    Returns:
    
    an Object based on what is presumed to be the next sequence of bytes (only works if the appends() were used to build up this ByteBuffer
  - main
```
public static void main(java.lang.String[] args)
```
    unit test Usage: java ByteBuilder INTEGER=22|SHORT=22|STRING=hi|FLOAT=2.3|DOUBLE=2.3|LONG=123 ... will construct a ByteBuilder with the command-line components, then dump them out

Class ByteBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Constructor Detail

ByteBuilder

ByteBuilder

ByteBuilder

ByteBuilder

ByteBuilder

Method Detail

toBytes

toString

toDebugString

length

getSize

getItems

getByte

setByte

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

append

clear

reset

nextBoolean

nextByte

nextShort

nextInteger

nextLong

nextFloat

nextDouble

nextFixedBin

nextFixedBin

nextString

nextString

nextPicture

nextPicture

nextBitN

nextBigInteger

nextBigDecimal

nextComplex

nextOffset

nextPointer

nextBytes

nextOrdinal

nextFixedBin

nextOffset

nextPointer

nextArea

nextArray

nextBigDecimal

nextBigInteger

nextGroup

hasNext

hasNextItem

next