Module bitarray

The data structure Bitarray stores bits (booleans) in an array in a memory-saving manner internally.

One can assign value (0 or 1) to each element as well as extract values from the array.
Github: repo

Functions

new (nbits) Creates a new bit array of n bits.
copyfrom (src) Creates a new bit array, identical to src.

Fields

__version Describes the loaded bitarray library info (version and lua version)

Class Bitarray

Bitarray:set (i, b) Mutates the array.
Set the ith bit of the array.
Bitarray:at (i) Does not mutate the array.
Get the ith bit of the array.
Bitarray:len () Does not mutate the array.
Get the length of the array.
Bitarray:fill (b) Mutates the array.
Set all bits of the array.
Bitarray:flip ([i]) Mutates the array.
If argument i is present, the bit at that index is flipped, if not or i is 0, all the bits are flipped.
Bitarray:resize (n) May mutate the array.
Bitarray:reverse () Mutates the array.
Reverse the contents of the array.
Bitarray:slice ([i[, n]]) Does not mutate the array.
Creates a new array with bits obtained from those at index i to n in the original array, inclusive.
Bitarray:rep (n) Does not mutate the array.
Repeat the array n times and return the new array.
Bitarray:equal (other) Does not mutate the array.
Compares whether two arrays are identical (same value and length).
Bitarray:concat (other) Does not mutate the array.
Concatenate two arrays and return the new array.
Bitarray:bnot () Does not mutate the array.
Flip all bits of the array and return the new array.
Bitarray:band (other) Does not mutate the array.
Perform a bitwise AND and return the new array.
Bitarray:bor (other) Does not mutate the array.
Perform a bitwise OR and return the new array.
Bitarray:bxor (other) Does not mutate the array.
Perform a bitwise XOR and return the new array.
Bitarray:shiftleft (n) Does not mutate the array.
Shift all content left n bits and return the new array.
Bitarray:shiftright (n) Does not mutate the array.
Shift all content right n bits and return the new array.
Bitarray:at_uint8 ([i]) Does not mutate the array.
Converts the contents starting at index i to an uint8 (uchar) integer.
Bitarray:at_uint16 ([i]) Does not mutate the array.
Converts the contents starting at index i to an uint16 integer.
Bitarray:at_uint32 ([i]) Does not mutate the array.
Converts the contents starting at index i to an uint32 integer.
Bitarray:at_uint64 ([i]) Does not mutate the array.
Converts the contents starting at index i to an uint64 integer.
Bitarray:from_uint8 (src[, i]) Mutates the array.
Assign the array from index i from an uint8 (uchar) integer.
Bitarray:from_uint16 (src[, i]) Mutates the array.
Assign the array from index i from an uint16 integer.
Bitarray:from_uint32 (src[, i]) Mutates the array.
Assign the array from index i from an uint32 integer.
Bitarray:from_uint64 (src[, i]) Mutates the array.
Assign the array from index i from an uint64 integer.
Bitarray:from_bitarray (src[, i]) Mutates the array.
Copy the content from bitarray src to the operand.
Bitarray:from_binarystring (src[, i]) Mutates the array.
Copy the content from a binary string to the operand.
Bitarray:tostring () Does not mutate the array.
Returns the string representation for the array.


Functions

new (nbits)
Creates a new bit array of n bits. all fields are initialized to 0.

Parameters:

  • nbits integer number of bits of the array

Returns:

    Bitarray or nil the newly created bitarray if successful
copyfrom (src)
Creates a new bit array, identical to src.

Parameters:

Returns:

    Bitarray or nil the newly created bitarray if successful

Fields

__version
Describes the loaded bitarray library info (version and lua version)

Class Bitarray

Bitarray:set (i, b)
Mutates the array.
Set the ith bit of the array. Any value other than false or nil will be considered a truthy(1) bit.
Operator __newindex is overloaded with this method.

Parameters:

  • i integer the index
  • b any the value to change to

Returns:

    Bitarray the original bit array reference

Usage:

     local a = Bitarray.new(10)
 a:set(4, true)
 a[4] = true -- same
Bitarray:at (i)
Does not mutate the array.
Get the ith bit of the array.
Operator __index is overloaded with this method.

Parameters:

  • i integer the index

Returns:

    boolean true if bit is 1, false if 0

Usage:

     local a = Bitarray.new(10)
 a:at(7) -- false
 a[7]    -- false
Bitarray:len ()
Does not mutate the array.
Get the length of the array.
Operator __len is overloaded with this method.

Returns:

    integer the number of bits of the array

Usage:

     local a = Bitarray.new(10)
 a:len(a) -- 10
 #a       -- 10
Bitarray:fill (b)
Mutates the array.
Set all bits of the array. Any value other than false or nil will be considered a truthy(1) bit.

Parameters:

  • b any the value to change to

Returns:

    Bitarray the original bit array reference

Usage:

     local a = Bitarray.new(10)
 a:fill(true)  -- all bits set to 1
Bitarray:flip ([i])
Mutates the array.
If argument i is present, the bit at that index is flipped, if not or i is 0, all the bits are flipped.

Parameters:

  • i integer the index

Returns:

    Bitarray the original bit array reference

Usage:

     local a = Bitarray.new(10)
 a:flip()    -- all bits set to true
 a:flip(1)   -- sets first bit to true
Bitarray:resize (n)
May mutate the array.
Resize the array to length n. if new size is greater, the new bits are appended to the right and initialized to 0, otherwise additional rightmost bits are lost.

Parameters:

  • n integer >= 1

Returns:

    Bitarray or nil the original bit array reference if successful, otherwise nil
Bitarray:reverse ()
Mutates the array.
Reverse the contents of the array.

Returns:

    Bitarray the original bit array reference
Bitarray:slice ([i[, n]])
Does not mutate the array.
Creates a new array with bits obtained from those at index i to n in the original array, inclusive. Resultant length is n - i + 1.

Parameters:

  • i integer the starting index, default 1
  • n integer the ending index, default the length of the array.

Returns:

    Bitarray or nil the newly created bit array reference if successful

Usage:

     local a = Bitarray.new(8):set(3, true):set(5, true)
 local b = a:slice(1, 4)
 print(a) -- Bitarray[0,0,1,0,1,0,0,0]
 print(b) -- Bitarray[0,0,1,0]
Bitarray:rep (n)
Does not mutate the array.
Repeat the array n times and return the new array.

Parameters:

  • n integer >= 1

Returns:

    Bitarray or nil the newly created bit array reference if successful

Usage:

     local a = Bitarray.new(3):set(3, true)
 print(a:rep(4))  -- Bitarray[0,0,1,0,0,1,0,0,1,0,0,1]
Bitarray:equal (other)
Does not mutate the array.
Compares whether two arrays are identical (same value and length).
Operator __eq is overloaded with this method.

Parameters:

Returns:

    boolean

Usage:

     local a = Bitarray.new(10)
 local b = Bitarray.copyfrom(a)
 a:equal(b)          -- true
 a == b:resize(1)    -- false
Bitarray:concat (other)
Does not mutate the array.
Concatenate two arrays and return the new array.
Operator __concat is overloaded with this method.

Parameters:

Returns:

    Bitarray or nil the newly created bit array reference if successful

Usage:

     local a = Bitarray.new(1)
 local b = Bitarray.new(4):fill(true)
 print(a..b)  -- Bitarray[0,1,1,1,1]
Bitarray:bnot ()
Does not mutate the array.
Flip all bits of the array and return the new array.
Operator __bnot is overloaded with this method. (5.3+)

Returns:

    Bitarray or nil the newly created bit array reference if successful

Usage:

     local a = Bitarray.new(2):set(1, true)
 print(~a)  -- Bitarray[0,1]
Bitarray:band (other)
Does not mutate the array.
Perform a bitwise AND and return the new array. Two arrays have to be of same size.
Operator __band is overloaded with this method. (5.3+)

Parameters:

Returns:

    Bitarray or nil the newly created bit array reference if successful

Usage:

     local a = Bitarray.new(4):set(1, true):set(3, true)
 local b = Bitarray.new(4):set(1, true)
 print(a & b)  -- Bitarray[1,0,0,0]
Bitarray:bor (other)
Does not mutate the array.
Perform a bitwise OR and return the new array. Two arrays have to be of same size.
Operator __bor is overloaded with this method. (5.3+)

Parameters:

Returns:

    Bitarray or nil the newly created bit array reference if successful

See also:

Bitarray:bxor (other)
Does not mutate the array.
Perform a bitwise XOR and return the new array. Two arrays have to be of same size.
Operator __bxor is overloaded with this method. (5.3+)

Parameters:

Returns:

    Bitarray or nil the newly created bit array reference if successful

See also:

Bitarray:shiftleft (n)
Does not mutate the array.
Shift all content left n bits and return the new array. Extra bits are discarded and empty bits are filled with 0.
Operator __shl is overloaded with this method. (5.3+)

Parameters:

  • n integer

Returns:

    Bitarray or nil the newly created bit array reference if successful

Usage:

     local a = Bitarray.new(8):from_uint8(15)
 print(a)      -- Bitarray[0,0,0,0,1,1,1,1]
 print(a << 2) -- Bitarray[0,0,1,1,1,1,0,0]
Bitarray:shiftright (n)
Does not mutate the array.
Shift all content right n bits and return the new array. Extra bits are discarded and empty bits are filled with 0. The shift is unsigned.
Operator __shr is overloaded with this method. (5.3+)

Parameters:

  • n integer

Returns:

    Bitarray or nil the newly created bit array reference if successful

See also:

Bitarray:at_uint8 ([i])
Does not mutate the array.
Converts the contents starting at index i to an uint8 (uchar) integer. The array should be big enough to hold bits required to construct the type. The leftmost bit corresponds to the most significant digit of the number and the last bit corresponds to the least significant digit (big endian).

Parameters:

  • i integer default to 1

Returns:

    integer

Usage:

     local a = Bitarray.new(10):set(2, 1):set(3, 1):set(4, 1):set(5, 1):set(7, 1)
 print(a) -- Bitarray[0,1,1,1,1,0,1,0,0,0]
 a:at_uint8(2)   -- intepreted as 11110100, which is 244
Bitarray:at_uint16 ([i])
Does not mutate the array.
Converts the contents starting at index i to an uint16 integer.

Parameters:

  • i integer

Returns:

    integer

See also:

Bitarray:at_uint32 ([i])
Does not mutate the array.
Converts the contents starting at index i to an uint32 integer.

Parameters:

  • i integer

Returns:

    integer

See also:

Bitarray:at_uint64 ([i])
Does not mutate the array.
Converts the contents starting at index i to an uint64 integer.

Parameters:

  • i integer

Returns:

    integer

See also:

Usage:

     -- lua5.3 added support for displaying and manipulating unsigned integers,
 -- prior to that this function may not work as intended always
 local a = Bitarray.new(64):fill(true)
 string.format('%u', a:at_uint64()) -- 18446744073709551615
Bitarray:from_uint8 (src[, i])
Mutates the array.
Assign the array from index i from an uint8 (uchar) integer. The array should be big enough to store the representation. The leftmost bit corresponds to the most significant digit of the number and the last bit corresponds to the least significant digit (big endian).

Parameters:

  • src integer the source integer to convert from
  • i integer the index in this array where the first bit gets copied from src. default 1

Returns:

    Bitarray the original bit array reference

Usage:

     local a = Bitarray.new(8):from_uint8(253)
 print(a) -- Bitarray[1,1,1,1,1,1,0,1]
 local b = Bitarray.new(16):from_uint8(255, 9)
 print(b) -- Bitarray[0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1]
Bitarray:from_uint16 (src[, i])
Mutates the array.
Assign the array from index i from an uint16 integer. The array should be big enough to store the representation.

Parameters:

  • src integer
  • i integer

Returns:

    Bitarray the original bit array reference

See also:

Bitarray:from_uint32 (src[, i])
Mutates the array.
Assign the array from index i from an uint32 integer. The array should be big enough to store the representation.

Parameters:

  • src integer
  • i integer

Returns:

    Bitarray the original bit array reference

See also:

Bitarray:from_uint64 (src[, i])
Mutates the array.
Assign the array from index i from an uint64 integer. The array should be big enough to store the representation.

Parameters:

  • src integer
  • i integer

Returns:

    Bitarray the original bit array reference

See also:

Bitarray:from_bitarray (src[, i])
Mutates the array.
Copy the content from bitarray src to the operand. The array's ith, i+1th, ... bit will be the bits from src starting from 1st to the last. The array needs to be big enough to hold the data.

Parameters:

  • src Bitarray
  • i integer the index in this array where the first bit gets copied from src. default 1

Returns:

    Bitarray the original bit array reference

Usage:

     local a = Bitarray.new(10)
  :from_bitarray(Bitarray.new(5):fill(true):set(3, false), 6)
 print(a) -- Bitarray[0,0,0,0,0,1,1,0,1,1]
Bitarray:from_binarystring (src[, i])
Mutates the array.
Copy the content from a binary string to the operand. Given the string consisting of only 0 and 1's, the array's ith, i+1th, ... bit will be the false/true values represented by chars in this string. The array needs to be big enough to hold the data.

Parameters:

  • src string
  • i integer the index in this array where the first bit gets copied from src. default 1

Returns:

    Bitarray the original bit array reference

Usage:

     local a = Bitarray.new(12)
  :from_binarystring('001100'):from_binarystring('111111', 7)
 print(a) -- Bitarray[0,0,1,1,0,0,1,1,1,1,1,1]
 -- a:from_binarystring('10x0') error! invalid string
Bitarray:tostring ()
Does not mutate the array.
Returns the string representation for the array.
Metamethod __tostring is overloaded with this method so it can be implicitly called if string is needed. The full array is not displayed if it is too long.

Returns:

    string

Usage:

     local a = Bitarray.new(8):set(8, true)
 print(a)
 -- Bitarray[0,0,0,0,0,0,0,1]
 a:resize(65)
 print(a)
 -- Bitarray[...]
generated by LDoc 1.4.2