Lua library module "bits"

Author Hans van der Meer

The Lua module bits is a C-module for the manipulation of bitmaps.



  1. The calling sequences below assume the module has the name bits assigned to it from the require.
  2. Calling bitmap functions is in object notation with bits as the variable name.
  3. Be aware of the fact that bits in a bitmap are usually counted from 0 upwards. But as is the custom in Lua, counting starts here beginning at 1. Internally in the C-code the bits are stored at a position one less than the number given.
  4. The iterators generate the bitmap values in the order 1, 2, ... This is the same behaviour as the Lua function ipairs on tables.
  5. The size of the printout is controlled by the printlimit method. By default the limit is set to zero; the other obvious default is printing the whole bitmap, but this can turn out to be disastrous large.

Create bitmap

bits.create(value, number) return bitmap of given size set to value

Set bits

bits:set(value) set all bits to value, return bitmap
bits:set(value, n1[,n2[n3,...]]) set these bits to value, return bitmap

Get bits

bits:get(n) get value of this bit
bits:get(n1[,n2[n3,...]]) get value of these bits
bits:iterator() return iterator for all bits => i,v
bits:iterator(n) return iterator starting at bit n => i,v
bits:iterator(n1, n2) return iterator over range [n1..n2] => i,v
bits:index(value) return iterator => next index with the value
bits:index(value, start) return index of next bit with the value

Compare bits

bits:isequal(b) bits == b return true or false for equality

Boolean operations

bits:notbits() - bits return NOT of the bitmap
bits:orbits(b) bits + b return OR of the bitmaps
bits:andbits(b) bits * b return AND of the bitmaps
bits:xorbits(b) bits % b return XOR of the bitmaps
bits:orbits(n1, n2[, n3,...]) return OR of these bits
bits:andbits(n1, n2[, n3,...]) return AND of these bits
bits:xorbits(n1, n2[, n3,...]) return XOR of these bits

Copy bitmap

bits:copy() return a copy of the bitmap

Query state

bits:printlimit() return current limit
bits:printlimit(n|"all"|"*") set n or all bits printed, return new limit
bits:size(), #bits return the bit capacity
bits:ones() return the number of 1 bits
bits.version() return the version of module