Bitmaps are used to implement bounded sets. Each bit in the bitmap may be on or off representing presence or absence of a value in the set. Typically bitmaps are used to record sets of privileges.

A bitmap ref is a variable that may temporarily reference another bitmap. These are useful for manipulating specific bitmaps within bitmap arrays or bitmap hashes. All bitmap operations except for init_bitmap(bitmap_name text, range_name text) may take the name of a bitmap ref instead of a bitmap.

Bitmap refs may not be shared, and the reference is only accessible within the transaction that created it. These restrictions exist to eliminate the possibility of references to deleted objects or to objects from other sessions.

The following functions comprise the Veil bitmaps API:

init_bitmap(bitmap_name text, range_name text)

function veil.init_bitmap(bitmap_name text, range_name text) returns bool

This is used to create or resize a bitmap. The first parameter provides the name of the bitmap, the second is the name of a range variable that will govern the size of the bitmap. It is implemented by C function veil_init_bitmap().

clear_bitmap(bitmap_name text)

function veil.clear_bitmap(bitmap_name text) returns bool

This is used to clear (set to zero) all bits in the bitmap. It is implemented by C function veil_clear_bitmap().

bitmap_setbit(bitmap_name text, bit_number int4)

function veil.bitmap_setbit(bitmap_name text, bit_number int4) returns bool

This is used to set a specified bit, given by bit_number in the bitmap identified by bitmap_name. It is implemented by C function veil_bitmap_setbit().

bitmap_clearbit(bitmap_name text, bit_number int4)

function veil.bitmap_clearbit(bitmap_name text, bit_number int4) returns bool

This is used to clear (set to zero) a specified bit in a bitmap. It is implemented by C function veil_bitmap_clearbit().

bitmap_testbit(bitmap_name text, bit_number int4)

function veil.bitmap_testbit(bitmap_name text, bit_number int4) returns bool

This is used to test a specified bit in a bitmap. It returns true if the bit is set, false otherwise. It is implemented by C function veil_bitmap_testbit().

bitmap_union(result_name text, bm2_name text)

function veil.bitmap_union(result_name text, bm2_name text) returns bool

Form the union of two bitmaps with the result going into the first. Implemented by C function veil_bitmap_union().

bitmap_intersect(result_name text, bm2_name text)

function veil.bitmap_intersect(result_name text, bm2_name text) returns bool

Form the intersection of two bitmaps with the result going into the first. Implemented by C function veil_bitmap_intersect().

bitmap_bits(bitmap_name text)

function veil.bitmap_bits(bitmap_name text) returns setof int4

This is used to list all bits set within a bitmap. It is primarily for interactive use during development and debugging of Veil-based systems. It is implemented by C function veil_bitmap_bits().

bitmap_range(bitmap_name text)

function veil.bitmap_range(bitmap_name text) returns veil.range_t

This returns the range, as a veil_range_t, of a bitmap. It is primarily intended for interactive use. It is implemented by C function veil_bitmap_range().

Next: Bitmap Arrays