Nagios  4.4.7
Dev docs for Nagios core and neb-module hackers
bitmap.h
Go to the documentation of this file.
1 #ifndef LIBNAGIOS_bitmap_h__
2 #define LIBNAGIOS_bitmap_h__
3 
4 /**
5  * @file bitmap.h
6  * @brief Bit map API
7  *
8  * The bitmap api is useful for running set operations on objects
9  * indexed by unsigned integers.
10  * @{
11  */
12 struct bitmap;
13 typedef struct bitmap bitmap;
14 
15 /**
16  * Resize a bitmap
17  * If the bitmap is made smaller, data will silently be lost.
18  *
19  * @param bm The bitmap to resize
20  * @param size The new desired size of the bitmap
21  * @return 0 on success, -1 on errors.
22  */
23 extern int bitmap_resize(bitmap *bm, unsigned long size);
24 
25 /**
26  * Create a bitmaptor of size 'size'
27  * @param size Desired storage capacity
28  * @return A bitmap pointer on success, NULL on errors
29  */
30 extern bitmap *bitmap_create(unsigned long size);
31 
32 /**
33  * Destroy a bitmaptor by freeing all the memory it uses
34  * @param bm The bitmaptor to destroy
35  */
36 extern void bitmap_destroy(bitmap *bm);
37 
38 /**
39  * Copy a bitmaptor
40  * @param bm The bitmaptor to copy
41  * @return Pointer to an identical bitmap on success, NULL on errors
42  */
43 extern bitmap *bitmap_copy(const bitmap *bm);
44 
45 /**
46  * Set a bit in the map
47  * @param bm The bitmaptor to operate on
48  * @param pos Position of the bit to set
49  * @return 0 on success, -1 on errors
50  */
51 extern int bitmap_set(bitmap *bm, unsigned long pos);
52 
53 /**
54  * Check if a particular bit is set in the map
55  * @param bm The bitmaptor to check
56  * @param pos Position of the bit to check
57  * @return 1 if set, otherwise 0
58  */
59 extern int bitmap_isset(const bitmap *bm, unsigned long pos);
60 
61 /**
62  * Unset a particular bit in the map
63  * @param bm The bitmaptor to operate on
64  * @param pos Position of the bit to unset
65  */
66 extern int bitmap_unset(bitmap *bm, unsigned long pos);
67 
68 /**
69  * Obtain cardinality (max number of elements) of the bitmaptor
70  * @param bm The bitmaptor to check
71  * @return The cardinality of the bitmaptor
72  */
73 extern unsigned long bitmap_cardinality(const bitmap *bm);
74 #define bitmap_size bitmap_cardinality
75 
76 /**
77  * Count set bits in map. Completed in O(n/8) time.
78  * @param bm The bitmaptor to count bits in
79  * @return The number of set bits
80  */
81 extern unsigned long bitmap_count_set_bits(const bitmap *bm);
82 
83 /**
84  * Count unset bits in map. Completed in O(n/8) time.
85  * @param bm The bitmaptor to count bits in
86  * @return The number of set bits
87  */
88 extern unsigned long bitmap_count_unset_bits(const bitmap *bm);
89 
90 /**
91  * Unset all bits in a bitmap
92  * @param bm The bitmap to clear
93  */
94 extern void bitmap_clear(bitmap *bm);
95 
96 /**
97  * Calculate intersection of two bitmaps
98  * The intersection is defined as all bits that are members of
99  * both A and B. It's equivalent to bitwise AND.
100  * This function completes in O(n/sizeof(long)) operations.
101  * @param a The first bitmaptor
102  * @param b The second bitmaptor
103  * @return NULL on errors; A newly created bitmaptor on success.
104  */
105 extern bitmap *bitmap_intersect(const bitmap *a, const bitmap *b);
106 
107 /**
108  * Calculate union of two bitmaps
109  * The union is defined as all bits that are members of
110  * A or B or both A and B. It's equivalent to bitwise OR.
111  * This function completes in O(n/sizeof(long)) operations.
112  * @param a The first bitmaptor
113  * @param b The second bitmaptor
114  * @return NULL on errors; A newly created bitmaptor on success.
115  */
116 extern bitmap *bitmap_union(const bitmap *a, const bitmap *b);
117 
118 /**
119  * Calculate union of two bitmaps and store result in one of them
120  * @param res The first bitmap
121  * @param addme The bitmap to unite to the first bitmap
122  * @return NULL on errors, res on success
123  */
124 extern bitmap *bitmap_unite(bitmap *res, const bitmap *addme);
125 
126 /**
127  * Calculate set difference between two bitmaps
128  * The set difference of A / B is defined as all members of A
129  * that isn't members of B. Note that parameter ordering matters
130  * for this function.
131  * This function completes in O(n/sizeof(long)) operations.
132  * @param a The first bitmaptor (numerator)
133  * @param b The first bitmaptor (denominator)
134  * @return NULL on errors; A newly created bitmaptor on success.
135  */
136 extern bitmap *bitmap_diff(const bitmap *a, const bitmap *b);
137 
138 /**
139  * Calculate symmetric difference between two bitmaps
140  * The symmetric difference between A and B is the set that
141  * contains all elements in either set but not in both.
142  * This function completes in O(n/sizeof(long)) operations.
143  * @param a The first bitmaptor
144  * @param b The second bitmaptor
145  */
146 extern bitmap *bitmap_symdiff(const bitmap *a, const bitmap *b);
147 
148 /**
149  * Compare two bitmaps for equality
150  * @param a The first bitmaptor
151  * @param b The other bitmaptor
152  * @return Similar to memcmp(), with tiebreaks determined by cardinality
153  */
154 extern int bitmap_cmp(const bitmap *a, const bitmap *b);
155 /** @} */
156 #endif /* LIBNAGIOS_bitmap_h__ */
bitmap * bitmap_symdiff(const bitmap *a, const bitmap *b)
Calculate symmetric difference between two bitmaps The symmetric difference between A and B is the se...
void bitmap_clear(bitmap *bm)
Unset all bits in a bitmap.
unsigned long bitmap_count_unset_bits(const bitmap *bm)
Count unset bits in map.
int bitmap_unset(bitmap *bm, unsigned long pos)
Unset a particular bit in the map.
int bitmap_resize(bitmap *bm, unsigned long size)
Resize a bitmap If the bitmap is made smaller, data will silently be lost.
bitmap * bitmap_copy(const bitmap *bm)
Copy a bitmaptor.
bitmap * bitmap_create(unsigned long size)
Create a bitmaptor of size 'size'.
int bitmap_set(bitmap *bm, unsigned long pos)
Set a bit in the map.
bitmap * bitmap_union(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 ...
unsigned long bitmap_count_set_bits(const bitmap *bm)
Count set bits in map.
int bitmap_isset(const bitmap *bm, unsigned long pos)
Check if a particular bit is set in the map.
bitmap * bitmap_diff(const bitmap *a, const bitmap *b)
Calculate set difference between two bitmaps The set difference of A / B is defined as all members of...
void bitmap_destroy(bitmap *bm)
Destroy a bitmaptor by freeing all the memory it uses.
bitmap * bitmap_intersect(const bitmap *a, const bitmap *b)
Calculate intersection of two bitmaps The intersection is defined as all bits that are members of bot...
int bitmap_cmp(const bitmap *a, const bitmap *b)
Compare two bitmaps for equality.
unsigned long bitmap_cardinality(const bitmap *bm)
Obtain cardinality (max number of elements) of the bitmaptor.
bitmap * bitmap_unite(bitmap *res, const bitmap *addme)
Calculate union of two bitmaps and store result in one of them.