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 | |
| bitCount | Sets or gets the bit count used in writeBits() and readBits() |
| bitsForInt | Static. Returns the amount of bits required to store an integer of the given value |
| readBits | Reads integers with a fixed bit width |
| readableBits | Returns the amount of bits left that can be read |
| rposBits | Returns the read position, in bits |
| sizeBits | Returns the buffer size, in bits |
| wposBits | Returns the write position, in bits |
| writeBits | Writes integers with a fixed bit width |
| Properties inherited from class ByteBuf | |
| BIG_ENDIAN | |
| LITTLE_ENDIAN | |
| NATIVE_ENDIAN | |
| REVERSE_ENDIAN | |
Sets or gets the bit count used in writeBits() and readBits()
BitBuf.bitCount( [bits] )
| bits | The amount of bits to use |
| Return | The 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
Static. Returns the amount of bits required to store an integer of the given value
BitBuf.bitsForInt( n )
| n | Integer to check |
| Return | The 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)
Reads integers with a fixed bit width
BitBuf.readBits( [neg] )
| neg | An arbitrary amount of integers |
| Return | An 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.
Returns the amount of bits left that can be read
BitBuf.readableBits()
| Return | The 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].
Returns the read position, in bits
BitBuf.rposBits()
| Return | The 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].
Returns the buffer size, in bits
BitBuf.sizeBits()
| Return | The 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].
Returns the write position, in bits
BitBuf.wposBits()
| Return | The 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].
Writes integers with a fixed bit width
BitBuf.writeBits( [ints] )
| ints | An arbitrary amount of integers |
| Return | The 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