initial commit

nagios4/bitmap.h

@@ -0,0 +1,156 @@
+#ifndef LIBNAGIOS_bitmap_h__
+#define LIBNAGIOS_bitmap_h__
+
+/**
+ * @file bitmap.h
+ * @brief Bit map API
+ *
+ * The bitmap api is useful for running set operations on objects
+ * indexed by unsigned integers.
+ * @{
+ */
+struct bitmap;
+typedef struct bitmap bitmap;
+
+/**
+ * Resize a bitmap
+ * If the bitmap is made smaller, data will silently be lost.
+ *
+ * @param bm The bitmap to resize
+ * @param size The new desired size of the bitmap
+ * @return 0 on success, -1 on errors.
+ */
+extern int bitmap_resize(bitmap *bm, unsigned long size);
+
+/**
+ * Create a bitmaptor of size 'size'
+ * @param size Desired storage capacity
+ * @return A bitmap pointer on success, NULL on errors
+ */
+extern bitmap *bitmap_create(unsigned long size);
+
+/**
+ * Destroy a bitmaptor by freeing all the memory it uses
+ * @param bm The bitmaptor to destroy
+ */
+extern void bitmap_destroy(bitmap *bm);
+
+/**
+ * Copy a bitmaptor
+ * @param bm The bitmaptor to copy
+ * @return Pointer to an identical bitmap on success, NULL on errors
+ */
+extern bitmap *bitmap_copy(const bitmap *bm);
+
+/**
+ * Set a bit in the map
+ * @param bm The bitmaptor to operate on
+ * @param pos Position of the bit to set
+ * @return 0 on success, -1 on errors
+ */
+extern int bitmap_set(bitmap *bm, unsigned long pos);
+
+/**
+ * Check if a particular bit is set in the map
+ * @param bm The bitmaptor to check
+ * @param pos Position of the bit to check
+ * @return 1 if set, otherwise 0
+ */
+extern int bitmap_isset(const bitmap *bm, unsigned long pos);
+
+/**
+ * Unset a particular bit in the map
+ * @param bm The bitmaptor to operate on
+ * @param pos Position of the bit to unset
+ */
+extern int bitmap_unset(bitmap *bm, unsigned long pos);
+
+/**
+ * Obtain cardinality (max number of elements) of the bitmaptor
+ * @param bm The bitmaptor to check
+ * @return The cardinality of the bitmaptor
+ */
+extern unsigned long bitmap_cardinality(const bitmap *bm);
+#define bitmap_size bitmap_cardinality
+
+/**
+ * Count set bits in map. Completed in O(n/8) time.
+ * @param bm The bitmaptor to count bits in
+ * @return The number of set bits
+ */
+extern unsigned long bitmap_count_set_bits(const bitmap *bm);
+
+/**
+ * Count unset bits in map. Completed in O(n/8) time.
+ * @param bm The bitmaptor to count bits in
+ * @return The number of set bits
+ */
+extern unsigned long bitmap_count_unset_bits(const bitmap *bm);
+
+/**
+ * Unset all bits in a bitmap
+ * @param bm The bitmap to clear
+ */
+extern void bitmap_clear(bitmap *bm);
+
+/**
+ * Calculate intersection of two bitmaps
+ * The intersection is defined as all bits that are members of
+ * both A and B. It's equivalent to bitwise AND.
+ * This function completes in O(n/sizeof(long)) operations.
+ * @param a The first bitmaptor
+ * @param b The second bitmaptor
+ * @return NULL on errors; A newly created bitmaptor on success.
+ */
+extern bitmap *bitmap_intersect(const bitmap *a, const bitmap *b);
+
+/**
+ * Calculate union of two bitmaps
+ * The union is defined as all bits that are members of
+ * A or B or both A and B. It's equivalent to bitwise OR.
+ * This function completes in O(n/sizeof(long)) operations.
+ * @param a The first bitmaptor
+ * @param b The second bitmaptor
+ * @return NULL on errors; A newly created bitmaptor on success.
+ */
+extern bitmap *bitmap_union(const bitmap *a, const bitmap *b);
+
+/**
+ * Calculate union of two bitmaps and store result in one of them
+ * @param res The first bitmap
+ * @param addme The bitmap to unite to the first bitmap
+ * @return NULL on errors, res on success
+ */
+extern bitmap *bitmap_unite(bitmap *res, const bitmap *addme);
+
+/**
+ * Calculate set difference between two bitmaps
+ * The set difference of A / B is defined as all members of A
+ * that isn't members of B. Note that parameter ordering matters
+ * for this function.
+ * This function completes in O(n/sizeof(long)) operations.
+ * @param a The first bitmaptor (numerator)
+ * @param b The first bitmaptor (denominator)
+ * @return NULL on errors; A newly created bitmaptor on success.
+ */
+extern bitmap *bitmap_diff(const bitmap *a, const bitmap *b);
+
+/**
+ * Calculate symmetric difference between two bitmaps
+ * The symmetric difference between A and B is the set that
+ * contains all elements in either set but not in both.
+ * This function completes in O(n/sizeof(long)) operations.
+ * @param a The first bitmaptor
+ * @param b The second bitmaptor
+ */
+extern bitmap *bitmap_symdiff(const bitmap *a, const bitmap *b);
+
+/**
+ * Compare two bitmaps for equality
+ * @param a The first bitmaptor
+ * @param b The other bitmaptor
+ * @return Similar to memcmp(), with tiebreaks determined by cardinality
+ */
+extern int bitmap_cmp(const bitmap *a, const bitmap *b);
+/** @} */
+#endif /* LIBNAGIOS_bitmap_h__ */