Lua library module "bits"

Author: Hans van der Meer
The Lua module bits is a C-module for the manipulation of bitmaps.

API

Remarks

  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 b and bb as the variable names.
  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.new(value, number) return bitmap of given size set to value
return list, create and new are synomyms

Set bits

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

Get bits

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

Compare bits

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

Boolean operations

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

Copy bitmap

b:copy() return a copy of the bitmap

Query state

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