bitpack
Library that packs & unpacks bits in integers and bytes.
Bit positions are 0-indexed and counted from the least significant bit, so position 0 is the lowest bit (0x01) and position 7 is the highest bit of a byte (0x80), same as bit.extractpack.
Field functions (get, set, toggle, readUInt, readInt, write) work on any integer up to 32 bits, not only on bytes, because they are made of 32-bit shifts: readUInt( x, position, bit_count ) shifts the field to the top of 32 bits (bits above it fall off), then shifts it down to bit 0 (bits below it fall off).
So fields that cross byte boundaries are read and written by joining bytes into an integer with bytepack first:
lua Copy
-- [15] flag_a [14] flag_b [13..0] int14
local x = bytepack.readUInt16BE ( uint8_1, uint8_2 )
local flag_a = bitpack.get ( x, 15 )
local flag_b = bitpack.get ( x, 14 )
local value = bitpack.readInt ( x, 0 , 14 )
x = bitpack.write ( x, 0 , 14 , value - 1 )
uint8_1, uint8_2 = bytepack.writeUInt16BE ( x )Integers are taken modulo 2 ^ 32, a field must fit in them (position + bit_count <= 32), and results with bit 31 set are negative (signed 32-bit), except readUInt.
Byte functions (reverse, count, findFirst, findLast, rotate, swapNibbles, pack, unpack, toString, fromString) work on the lowest 8 bits only.
Bit sequences are tables of booleans, stored LSB-first by default (bits[ 1 ] is bit 0 of the first byte), or MSB-first when msb_first is true (bits[ 1 ] is bit 7 of the first byte, the order bits are usually written in).
Functions bitpack.countCounts set bits in the byte (population count). bitpack.findFirstFinds the position of the lowest set bit in the byte. bitpack.findLastFinds the position of the highest set bit in the byte. bitpack.fromStringReads the byte from a string of 0s and 1s, from the highest bit to the lowest. bitpack.fromTablePacks the sequence of bits (booleans) into the sequence of bytes, unused bits of the last byte are 0. bitpack.getChecks if the bit at the given position of the integer is set. bitpack.packPacks up to 8 booleans into the byte, from the lowest bit to the highest, nil is false. bitpack.readIntReads signed (two's complement) integer from the bit field of the integer. bitpack.readUIntReads unsigned integer from the bit field of the integer. bitpack.reverseReverses the order of bits in the byte. bitpack.rotateRotates bits of the byte, bits shifted out of one end come back on the other. bitpack.setSets the bit at the given position of the integer. bitpack.swapNibblesSwaps the lower and upper 4 bits (nibbles) of the byte. bitpack.toggleFlips the bit at the given position of the integer. bitpack.toStringConverts the byte to a string of 0s and 1s, from the highest bit to the lowest. bitpack.toTableUnpacks the sequence of bytes into the sequence of bits (booleans). bitpack.unpackUnpacks the byte as 8 booleans, from the lowest bit to the highest. bitpack.writeWrites unsigned or signed (two's complement) integer into the bit field of the integer, bits outside of the field are l…
function bitpack.count (byte : integer ): integer Counts set bits in the byte (population count).
lua Copy
count ( 0b01101100 ) --> 4 Parameters
Name Type Description byteinteger The byte.
Returns
Type Name Description integer countThe number of 1 bits (0 - 8).
function bitpack.findFirst (byte : integer ): integer | nil Finds the position of the lowest set bit in the byte.
lua Copy
findFirst ( 0b01101100 ) --> 2
findFirst ( 0 ) --> nil Parameters
Name Type Description byteinteger The byte.
Returns
Type Name Description integer | nil positionThe bit position (0 - 7), or nil if the byte is 0.
function bitpack.findLast (byte : integer ): integer | nil Finds the position of the highest set bit in the byte.
lua Copy
findLast ( 0b01101100 ) --> 6
findLast ( 0 ) --> nil Parameters
Name Type Description byteinteger The byte.
Returns
Type Name Description integer | nil positionThe bit position (0 - 7), or nil if the byte is 0.
function bitpack.fromString (str : string ): integer | nil Reads the byte from a string of 0s and 1s, from the highest bit to the lowest.
lua Copy
fromString ( "00000101" ) --> 5
fromString ( "101" ) --> 5
fromString ( "2" ) --> nil Parameters
Name Type Description strstring The string of 0s and 1s, up to 8 characters.
Returns
Type Name Description integer | nil byteThe byte, or nil if the string is empty, too long or has other characters.
function bitpack.fromTable (bits : boolean[] , bit_count? : integer , msb_first? : boolean ): integer[] , integer Packs the sequence of bits (booleans) into the sequence of bytes, unused bits of the last byte are 0.
Parameters
Name Type Description bitsboolean[] The sequence of bits. bit_countoptional integer The number of bits. msb_firstoptional boolean true if the highest bit of each byte is stored first, false by default.
Returns
Type Name Description integer[] bytesThe sequence of bytes. integer byte_countThe number of bytes.
function bitpack.get (x : integer , position : integer ): boolean Checks if the bit at the given position of the integer is set.
lua Copy
get ( 0b00000100, 2 ) --> true
get ( 0x8000 , 15 ) --> true Parameters
Name Type Description xinteger The integer (up to 32 bits). positioninteger The bit position (0 - 31).
Returns
Type Name Description boolean is_settrue if the bit is 1, false if it is 0.
function bitpack.pack (bit0? : boolean , bit1? : boolean , bit2? : boolean , bit3? : boolean , bit4? : boolean , bit5? : boolean , bit6? : boolean , bit7? : boolean ): integer Packs up to 8 booleans into the byte, from the lowest bit to the highest, nil is false.
lua Copy
pack ( true , false , true ) --> 0b00000101 Parameters
Name Type Description bit0optional boolean bit1optional boolean bit2optional boolean bit3optional boolean bit4optional boolean bit5optional boolean bit6optional boolean bit7optional boolean
Returns
Type Name Description integer byteThe byte.
function bitpack.readInt (x : integer , position? : integer , bit_count? : integer ): integer Reads signed (two's complement) integer from the bit field of the integer.
lua Copy
readInt ( 0b01101100, 2 , 4 ) --> -5
readInt ( 0xBB2E , 0 , 14 ) --> -1234 Parameters
Name Type Description xinteger The integer (up to 32 bits). positionoptional integer The position of the lowest bit of the field (0 - 31), 0 by default. bit_countoptional integer The size of the field in bits (1 - 32), 1 by default.
Returns
Type Name Description integer valueThe signed integer.
function bitpack.readUInt (x : integer , position? : integer , bit_count? : integer ): integer Reads unsigned integer from the bit field of the integer.
lua Copy
readUInt ( 0b01101100, 2 , 4 ) --> 0b1011 ( 11 )
readUInt ( 0xBB2E , 0 , 14 ) --> 15150 Parameters
Name Type Description xinteger The integer (up to 32 bits). positionoptional integer The position of the lowest bit of the field (0 - 31), 0 by default. bit_countoptional integer The size of the field in bits (1 - 32), 1 by default.
Returns
Type Name Description integer valueThe unsigned integer.
function bitpack.reverse (byte : integer ): integer Reverses the order of bits in the byte.
lua Copy
reverse ( 0b00000110 ) --> 0b01100000 Parameters
Name Type Description byteinteger The byte.
Returns
Type Name Description integer byteThe reversed byte.
function bitpack.rotate (byte : integer , shift : integer ): integer Rotates bits of the byte, bits shifted out of one end come back on the other.
lua Copy
rotate ( 0b10000001, 1 ) --> 0b00000011
rotate ( 0b10000001, -1 ) --> 0b11000000 Parameters
Name Type Description byteinteger The byte. shiftinteger The number of bits to rotate by, positive to the left (towards the highest bit), negative to the right.
Returns
Type Name Description integer byteThe rotated byte.
function bitpack.set (x : integer , position : integer , value? : ( boolean | 0 | 1 )?): integer Sets the bit at the given position of the integer.
lua Copy
set ( 0b00000000, 2 , true ) --> 0b00000100
set ( 0b11111111, 0 , false ) --> 0b11111110 Parameters
Name Type Description xinteger The integer (up to 32 bits). positioninteger The bit position (0 - 31). valueoptional ( boolean | 0 | 1 )?The new value of the bit, true by default.
Returns
Type Name Description integer xThe changed integer.
function bitpack.swapNibbles (byte : integer ): integer Swaps the lower and upper 4 bits (nibbles) of the byte.
lua Copy
swapNibbles ( 0xA5 ) --> 0x5A Parameters
Name Type Description byteinteger The byte.
Returns
Type Name Description integer byteThe swapped byte.
function bitpack.toggle (x : integer , position : integer ): integer Flips the bit at the given position of the integer.
lua Copy
toggle ( 0b00000101, 2 ) --> 0b00000001 Parameters
Name Type Description xinteger The integer (up to 32 bits). positioninteger The bit position (0 - 31).
Returns
Type Name Description integer xThe changed integer.
function bitpack.toString (byte : integer , bit_count? : integer ): string Converts the byte to a string of 0s and 1s, from the highest bit to the lowest.
lua Copy
toString ( 5 ) --> "00000101"
toString ( 5 , 4 ) --> "0101" Parameters
Name Type Description byteinteger The byte. bit_countoptional integer The number of the lowest bits to convert (1 - 8), 8 by default.
Returns
Type Name Description string strThe string of 0s and 1s.
function bitpack.toTable (bytes : integer[] , byte_count? : integer , msb_first? : boolean ): boolean[] , integer Unpacks the sequence of bytes into the sequence of bits (booleans).
Parameters
Name Type Description bytesinteger[] The sequence of bytes. byte_countoptional integer The number of bytes. msb_firstoptional boolean true to store the highest bit of each byte first, false by default.
Returns
Type Name Description boolean[] bitsThe sequence of bits. integer bit_countThe number of bits.
function bitpack.unpack (byte : integer ): boolean , boolean , boolean , boolean , boolean , boolean , boolean , boolean Unpacks the byte as 8 booleans, from the lowest bit to the highest.
lua Copy
unpack ( 0b00000101 ) --> true, false, true, false, false, false, false, false Parameters
Name Type Description byteinteger The byte.
Returns
Type Name Description boolean bit0boolean bit1boolean bit2boolean bit3boolean bit4boolean bit5boolean bit6boolean bit7
function bitpack.write (x : integer , position : integer , bit_count : integer , value : integer ): integer Writes unsigned or signed (two's complement) integer into the bit field of the integer, bits outside of the field are left unchanged.
Only the lowest bit_count bits of the value are written, for negative values these bits already are their two's complement, so the same field can be read back with readUInt or readInt.
lua Copy
write ( 0b00000011, 2 , 4 , 11 ) --> 0b00101111
write ( 0b00000011, 2 , 4 , -5 ) --> 0b00101111
write ( 0x8000 , 0 , 14 , -1234 ) --> 0xBB2E Parameters
Name Type Description xinteger The integer (up to 32 bits). positioninteger The position of the lowest bit of the field (0 - 31). bit_countinteger The size of the field in bits (1 - 32). valueinteger The unsigned or signed integer.
Returns
Type Name Description integer xThe changed integer.