2.1.1.1Class BitBuf

Flexible memory buffer optimized for bit-precise binary mangling

Class BitBuf from \
                 ByteBuf( )

The BitBuf is basically a ByteBuf, but with special read/write/seek functions whose bit-width can be changed. This is especially useful if a series of booleans, or integers whose maximum value is known, should be stored in a buffer, and memory usage must be as efficient as possible (e.g. to save bytes in network packets).

Endianness is always native, and attempting to change it has no effect, thus, to prevent unexpected behavior, calling setEndian() raises an error.

Note: The BitBuf reads and writes booleans always as one single bit.

Note: Unlike the ByteBuf, the []-accessor takes the index of a bit, and returns a boolean value.

Methods
bitCountSets or gets the bit count used in writeBits() and readBits()
bitsForIntStatic. Returns the amount of bits required to store an integer of the given value
readBitsReads integers with a fixed bit width
readableBitsReturns the amount of bits left that can be read
rposBitsReturns the read position, in bits
sizeBitsReturns the buffer size, in bits
wposBitsReturns the write position, in bits
writeBitsWrites integers with a fixed bit width
Properties inherited from class ByteBuf
BIG_ENDIAN
LITTLE_ENDIAN
NATIVE_ENDIAN
REVERSE_ENDIAN

Methods

bitCount

Sets or gets the bit count used in writeBits() and readBits()

BitBuf.bitCount( [bits] )
bits The amount of bits to use
ReturnThe BitBuf itself if bits was set, otherwise the amount of bits used in the bit-precise read/write functions.

Default is 8, if not explicitly set. A bit count of 0 will not write anything, and read operations will always return 0. Values > 64 are not recommended to use as they make no sense.


    bb = BitBuf()
    bb.bitCount(3).writeBits(7,4,3).bitCount(5).writeBits(30,20,10) // write with variable bit sizes

bitsForInt

Static. Returns the amount of bits required to store an integer of the given value

BitBuf.bitsForInt( n )
n Integer to check
ReturnThe amount of bits required to store an integer of the given value

Calculates how many bits are required to hold the value of the passed integer without losing data.

Note: A negative number can be 1 greater then its corresponding positive number, and yield the same result (-8 needs 3 bits, where +8 needs 4, for example)

readBits

Reads integers with a fixed bit width

BitBuf.readBits( [neg] )
neg An arbitrary amount of integers
ReturnAn integer value.

Reads one integer of bitCount() bits from the buffer. The returned integer is always positive, except if bitCount() is 64 and a negative number was written. If is true, this method will set all upper missing bits to make the number negative, to restore a previously written negative number.


    bb = BitBuf().bitCount(3).writeBits(7,8,9)
    x = bb.readBits()
    y = bb.readBits()
    z = bb.readBits()
    // result: x == 7, y == 0, z == 1  (only the lowest 3 bits were written!)

Note: Unlike r8()..r64(), the boolean parameter for this method *forces* a negative number.

readableBits

Returns the amount of bits left that can be read

BitBuf.readableBits()
ReturnThe remaining bits until the end of the BitBuf is reached

This function returns the remaining bits precisely, which can be calculated as (readable() * 8) + X, where X is in [0...7].

rposBits

Returns the read position, in bits

BitBuf.rposBits()
ReturnThe read position in bits if used as getter, otherwise the buffer itself

This function returns or sets the BitBuf read position precisely, which can be calculated as (rpos() * 8) + X, where X is in [0...7].

sizeBits

Returns the buffer size, in bits

BitBuf.sizeBits()
ReturnThe buffer size, in bits

This function returns or sets the BitBuf size precisely, which can be calculated as (size() * 8) + X, where X is in [0...7].

wposBits

Returns the write position, in bits

BitBuf.wposBits()
ReturnThe write position in bits if used as getter, otherwise the buffer itself

This function returns the BitBuf write position precisely, which can be calculated as (wpos() * 8) + X, where X is in [0...7].

writeBits

Writes integers with a fixed bit width

BitBuf.writeBits( [ints] )
ints An arbitrary amount of integers
ReturnThe BitBuf itself.

This method writes the lowest n bits of the supplied integers, where n = bitCount(). Be sure to choose enough bits, otherwise the integers will be truncated. To get the required amount of bits for an integer, use BitBuf.bitsForInt().

For numbers < 0, the sign is skipped and the number will be written as: (bitCount() + 1) - (abs(N) % bitCount()), where N is our negative number. To restore a negative number, use readBits(true).

Note: bitCount() >= 64 is the only mode that supports writing negative numbers *without* having to use readBits(true).


    bb = BitBuf()
    bb.bitCount(3).writeBits(7,4,3).bitCount(5).writeBits(30,20,10) // write with variable bit sizes
Made with http://www.falconpl.org