ParsableByteArray

@UnstableApi
@CheckReturnValue
class ParsableByteArray

Wraps a byte array, providing a set of methods for parsing data from it. Numerical values are parsed with the assumption that their constituent bytes are in big endian order.

Summary

Public constructors

Creates a new instance that initially has no backing data.

Creates a new instance wrapping data, and sets the limit to data.length.

Creates a new instance with limit bytes and sets the limit.
ParsableByteArray(data: ByteArray!, limit: Int)

Creates a new instance that wraps an existing array.

Public functions
Int

Returns the number of bytes yet to be read.
Int

Returns the capacity of the array, which may be larger than the limit.
Unit
ensureCapacity(requiredCapacity: Int)

Ensures the backing array is at least requiredCapacity long.
Int

Returns the limit.
Char

Peeks at the next char.
Char
peekChar(charset: Charset!)

Peeks at the next char (as decoded by charset)
Int

Peeks at the next byte as an unsigned value.
Unit
readBytes(bitArray: ParsableBitArray!, length: Int)

Reads the next length bytes into bitArray, and resets the position of bitArray to zero.
Unit
readBytes(buffer: ByteBuffer!, length: Int)

Reads the next length bytes into buffer.
Unit
readBytes(buffer: ByteArray!, offset: Int, length: Int)

Reads the next length bytes into buffer at offset.
String?

Reads up to the next delimiter byte (or the limit) as UTF-8 characters.
Double

Reads the next eight bytes as a 64-bit floating point value.
Float

Reads the next four bytes as a 32-bit floating point value.
Int

Reads the next four bytes as a signed value
Int

Reads the next three bytes as a signed value.
String?

Reads a line of text in UTF-8.
String?
readLine(charset: Charset!)

Reads a line of text in charset.
Int

Reads the next four bytes as a signed value in little endian order.
Int

Reads the next three bytes as a signed value in little endian order.
Long

Reads the next eight bytes as a signed value in little endian order.
Short

Reads the next two bytes as a signed value.
Long

Reads the next four bytes as an unsigned value in little endian order.
Int

Reads the next three bytes as an unsigned value in little endian order.
Int

Reads the next four bytes as a little endian unsigned integer into an integer, if the top bit is a zero.
Int

Reads the next two bytes as an unsigned value.
Long

Reads the next eight bytes as a signed value.
String?

Reads up to the next NUL byte (or the limit) as UTF-8 characters.
String!

Reads the next length bytes as UTF-8 characters.
Short

Reads the next two bytes as a signed value.
String!
readString(length: Int)

Reads the next length bytes as UTF-8 characters.
String!
readString(length: Int, charset: Charset!)

Reads the next length bytes as characters in the specified Charset.
Int

Reads a Synchsafe integer.
Int

Reads the next byte as an unsigned value.
Int

Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer.
Long

Reads the next four bytes as an unsigned value.
Int

Reads the next three bytes as an unsigned value.
Int

Reads the next four bytes as an unsigned integer into an integer, if the top bit is a zero.
Int

Reads a little endian integer of variable length.
Long

Reads a little endian long of variable length.
Long

Reads the next eight bytes as an unsigned long into a long, if the top bit is a zero.
Int

Reads the next two bytes as an unsigned value.
Long

Reads a long value encoded by UTF-8 encoding
Charset?

Reads a UTF byte order mark (BOM) and returns the UTF Charset it represents.
Unit
reset(data: ByteArray!)

Updates the instance to wrap data, and resets the position to zero and the limit to data.length.
Unit
reset(limit: Int)

Resets the position to zero and the limit to the specified value.
Unit
reset(data: ByteArray!, limit: Int)

Updates the instance to wrap data, and resets the position to zero.
Unit
setLimit(limit: Int)

Sets the limit.
Unit
skipBytes(bytes: Int)

Moves the reading offset by bytes.

Public properties
ByteArray<Byte>!
Int

Public constructors

ParsableByteArray

ParsableByteArray()

Creates a new instance that initially has no backing data.

ParsableByteArray

ParsableByteArray(data: ByteArray!)

Creates a new instance wrapping data, and sets the limit to data.length.

Parameters
data: ByteArray!

The array to wrap.

ParsableByteArray

ParsableByteArray(limit: Int)

Creates a new instance with limit bytes and sets the limit.

Parameters
limit: Int

The limit to set.

ParsableByteArray

ParsableByteArray(data: ByteArray!, limit: Int)

Creates a new instance that wraps an existing array.

Parameters
data: ByteArray!

The data to wrap.
limit: Int

The limit to set.

Public functions

bytesLeft

fun bytesLeft(): Int

Returns the number of bytes yet to be read.

capacity

fun capacity(): Int

Returns the capacity of the array, which may be larger than the limit.

ensureCapacity

fun ensureCapacity(requiredCapacity: Int): Unit

Ensures the backing array is at least requiredCapacity long.

position, limit, and all data in the underlying array (including that beyond limit) are preserved.

This might replace or wipe the underlying array, potentially invalidating any local references.

limit

fun limit(): Int

Returns the limit.

peekChar

fun peekChar(): Char

Peeks at the next char.

Equivalent to passing UTF_16 or UTF_16BE to peekChar.

peekChar

fun peekChar(charset: Charset!): Char

Peeks at the next char (as decoded by charset)

Throws
java.lang.IllegalArgumentException

if charset is not supported. Only US_ASCII, UTF-8, UTF-16, UTF-16BE, and UTF-16LE are supported.

peekUnsignedByte

fun peekUnsignedByte(): Int

Peeks at the next byte as an unsigned value.

readBytes

fun readBytes(bitArray: ParsableBitArray!, length: Int): Unit

Reads the next length bytes into bitArray, and resets the position of bitArray to zero.

Parameters
bitArray: ParsableBitArray!

The ParsableBitArray into which the bytes should be read.
length: Int

The number of bytes to write.

readBytes

fun readBytes(buffer: ByteBuffer!, length: Int): Unit

Reads the next length bytes into buffer.

Parameters
buffer: ByteBuffer!

The ByteBuffer into which the read data should be written.
length: Int

The number of bytes to read.
See also
put

readBytes

fun readBytes(buffer: ByteArray!, offset: Int, length: Int): Unit

Reads the next length bytes into buffer at offset.

Parameters
buffer: ByteArray!

The array into which the read data should be written.
offset: Int

The offset in buffer at which the read data should be written.
length: Int

The number of bytes to read.
See also
arraycopy

readDelimiterTerminatedString

fun readDelimiterTerminatedString(delimiter: Char): String?

Reads up to the next delimiter byte (or the limit) as UTF-8 characters.

Returns
String?

The string not including any terminating delimiter byte, or null if the end of the data has already been reached.

readDouble

fun readDouble(): Double

Reads the next eight bytes as a 64-bit floating point value.

readFloat

fun readFloat(): Float

Reads the next four bytes as a 32-bit floating point value.

readInt

fun readInt(): Int

Reads the next four bytes as a signed value

readInt24

fun readInt24(): Int

Reads the next three bytes as a signed value.

readLine

fun readLine(): String?

Reads a line of text in UTF-8.

Equivalent to passing UTF_8 to readLine.

readLine

fun readLine(charset: Charset!): String?

Reads a line of text in charset.

A line is considered to be terminated by any one of a carriage return ('\r'), a line feed ('\n'), or a carriage return followed immediately by a line feed ('\r\n'). This method discards leading UTF byte order marks (BOM), if present.

The position is advanced to start of the next line (i.e. any line terminators are skipped).

Parameters
charset: Charset!

The charset used to interpret the bytes as a String.
Returns
String?

The line not including any line-termination characters, or null if the end of the data has already been reached.
Throws
java.lang.IllegalArgumentException

if charset is not supported. Only US_ASCII, UTF-8, UTF-16, UTF-16BE, and UTF-16LE are supported.

readLittleEndianInt

fun readLittleEndianInt(): Int

Reads the next four bytes as a signed value in little endian order.

readLittleEndianInt24

fun readLittleEndianInt24(): Int

Reads the next three bytes as a signed value in little endian order.

readLittleEndianLong

fun readLittleEndianLong(): Long

Reads the next eight bytes as a signed value in little endian order.

readLittleEndianShort

fun readLittleEndianShort(): Short

Reads the next two bytes as a signed value.

readLittleEndianUnsignedInt

fun readLittleEndianUnsignedInt(): Long

Reads the next four bytes as an unsigned value in little endian order.

readLittleEndianUnsignedInt24

fun readLittleEndianUnsignedInt24(): Int

Reads the next three bytes as an unsigned value in little endian order.

readLittleEndianUnsignedIntToInt

fun readLittleEndianUnsignedIntToInt(): Int

Reads the next four bytes as a little endian unsigned integer into an integer, if the top bit is a zero.

Throws
java.lang.IllegalStateException

Thrown if the top bit of the input data is set.

readLittleEndianUnsignedShort

fun readLittleEndianUnsignedShort(): Int

Reads the next two bytes as an unsigned value.

readLong

fun readLong(): Long

Reads the next eight bytes as a signed value.

readNullTerminatedString

fun readNullTerminatedString(): String?

Reads up to the next NUL byte (or the limit) as UTF-8 characters.

Returns
String?

The string not including any terminating NUL byte, or null if the end of the data has already been reached.

readNullTerminatedString

fun readNullTerminatedString(length: Int): String!

Reads the next length bytes as UTF-8 characters. A terminating NUL byte is discarded, if present.

Parameters
length: Int

The number of bytes to read.
Returns
String!

The string, not including any terminating NUL byte.

readShort

fun readShort(): Short

Reads the next two bytes as a signed value.

readString

fun readString(length: Int): String!

Reads the next length bytes as UTF-8 characters.

Parameters
length: Int

The number of bytes to read.
Returns
String!

The string encoded by the bytes.

readString

fun readString(length: Int, charset: Charset!): String!

Reads the next length bytes as characters in the specified Charset.

Parameters
length: Int

The number of bytes to read.
charset: Charset!

The character set of the encoded characters.
Returns
String!

The string encoded by the bytes in the specified character set.

readSynchSafeInt

fun readSynchSafeInt(): Int

Reads a Synchsafe integer.

Synchsafe integers keep the highest bit of every byte zeroed. A 32 bit synchsafe integer can store 28 bits of information.

Returns
Int

The parsed value.

readUnsignedByte

fun readUnsignedByte(): Int

Reads the next byte as an unsigned value.

readUnsignedFixedPoint1616

fun readUnsignedFixedPoint1616(): Int

Reads the next four bytes, returning the integer portion of the fixed point 16.16 integer.

readUnsignedInt

fun readUnsignedInt(): Long

Reads the next four bytes as an unsigned value.

readUnsignedInt24

fun readUnsignedInt24(): Int

Reads the next three bytes as an unsigned value.

readUnsignedIntToInt

fun readUnsignedIntToInt(): Int

Reads the next four bytes as an unsigned integer into an integer, if the top bit is a zero.

Throws
java.lang.IllegalStateException

Thrown if the top bit of the input data is set.

readUnsignedLeb128ToInt

fun readUnsignedLeb128ToInt(): Int

Reads a little endian integer of variable length.

Returns
Int

integer value
Throws
java.lang.IllegalArgumentException

if the read value is greater than MAX_VALUE or less than MIN_VALUE

readUnsignedLeb128ToLong

fun readUnsignedLeb128ToLong(): Long

Reads a little endian long of variable length.

Returns
Long

long value
Throws
java.lang.IllegalStateException

if the byte to be read is over the limit of the parsable byte array

readUnsignedLongToLong

fun readUnsignedLongToLong(): Long

Reads the next eight bytes as an unsigned long into a long, if the top bit is a zero.

Throws
java.lang.IllegalStateException

Thrown if the top bit of the input data is set.

readUnsignedShort

fun readUnsignedShort(): Int

Reads the next two bytes as an unsigned value.

readUtf8EncodedLong

fun readUtf8EncodedLong(): Long

Reads a long value encoded by UTF-8 encoding

Returns
Long

Decoded long value
Throws
java.lang.NumberFormatException

if there is a problem with decoding

readUtfCharsetFromBom

fun readUtfCharsetFromBom(): Charset?

Reads a UTF byte order mark (BOM) and returns the UTF Charset it represents. Returns null without advancing position if no BOM is found.

reset

fun reset(data: ByteArray!): Unit

Updates the instance to wrap data, and resets the position to zero and the limit to data.length.

Parameters
data: ByteArray!

The array to wrap.

reset

fun reset(limit: Int): Unit

Resets the position to zero and the limit to the specified value. This might replace or wipe the underlying array, potentially invalidating any local references.

Parameters
limit: Int

The limit to set.

reset

fun reset(data: ByteArray!, limit: Int): Unit

Updates the instance to wrap data, and resets the position to zero.

Parameters
data: ByteArray!

The array to wrap.
limit: Int

The limit to set.

setLimit

fun setLimit(limit: Int): Unit

Sets the limit.

Parameters
limit: Int

The limit to set.

skipBytes

fun skipBytes(bytes: Int): Unit

Moves the reading offset by bytes.

Parameters
bytes: Int

The number of bytes to skip.
Throws
java.lang.IllegalArgumentException

Thrown if the new position is neither in nor at the end of the array.

Public properties

data

val data: ByteArray<Byte>!

position

var position: Int