roaring 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1031 @@
1
+ // !!! DO NOT EDIT - THIS IS AN AUTO-GENERATED FILE !!!
2
+ // Created by amalgamation.sh on Wed 20 Jul 2022 16:25:25 EDT
3
+
4
+ /*
5
+ * The CRoaring project is under a dual license (Apache/MIT).
6
+ * Users of the library may choose one or the other license.
7
+ */
8
+ /*
9
+ * Copyright 2016-2022 The CRoaring authors
10
+ *
11
+ * Licensed under the Apache License, Version 2.0 (the "License");
12
+ * you may not use this file except in compliance with the License.
13
+ * You may obtain a copy of the License at
14
+ *
15
+ * http://www.apache.org/licenses/LICENSE-2.0
16
+ *
17
+ * Unless required by applicable law or agreed to in writing, software
18
+ * distributed under the License is distributed on an "AS IS" BASIS,
19
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20
+ * See the License for the specific language governing permissions and
21
+ * limitations under the License.
22
+ *
23
+ * SPDX-License-Identifier: Apache-2.0
24
+ */
25
+ /*
26
+ * MIT License
27
+ *
28
+ * Copyright 2016-2022 The CRoaring authors
29
+ *
30
+ * Permission is hereby granted, free of charge, to any
31
+ * person obtaining a copy of this software and associated
32
+ * documentation files (the "Software"), to deal in the
33
+ * Software without restriction, including without
34
+ * limitation the rights to use, copy, modify, merge,
35
+ * publish, distribute, sublicense, and/or sell copies of
36
+ * the Software, and to permit persons to whom the Software
37
+ * is furnished to do so, subject to the following
38
+ * conditions:
39
+ *
40
+ * The above copyright notice and this permission notice
41
+ * shall be included in all copies or substantial portions
42
+ * of the Software.
43
+ *
44
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
45
+ * ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
46
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
47
+ * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
48
+ * SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
49
+ * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
50
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
51
+ * IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
52
+ * DEALINGS IN THE SOFTWARE
53
+ *
54
+ * SPDX-License-Identifier: MIT
55
+ */
56
+
57
+ /* begin file include/roaring/roaring_version.h */
58
+ // /include/roaring/roaring_version.h automatically generated by release.py, do not change by hand
59
+ #ifndef ROARING_INCLUDE_ROARING_VERSION
60
+ #define ROARING_INCLUDE_ROARING_VERSION
61
+ #define ROARING_VERSION "0.6.0"
62
+ enum {
63
+ ROARING_VERSION_MAJOR = 0,
64
+ ROARING_VERSION_MINOR = 6,
65
+ ROARING_VERSION_REVISION = 0
66
+ };
67
+ #endif // ROARING_INCLUDE_ROARING_VERSION
68
+ /* end file include/roaring/roaring_version.h */
69
+ /* begin file include/roaring/roaring_types.h */
70
+ /*
71
+ Typedefs used by various components
72
+ */
73
+
74
+ #ifndef ROARING_TYPES_H
75
+ #define ROARING_TYPES_H
76
+
77
+ #include <stdbool.h>
78
+ #include <stdint.h>
79
+
80
+ #ifdef __cplusplus
81
+ extern "C" { namespace roaring { namespace api {
82
+ #endif
83
+
84
+
85
+ /**
86
+ * When building .c files as C++, there's added compile-time checking if the
87
+ * container types are derived from a `container_t` base class. So long as
88
+ * such a base class is empty, the struct will behave compatibly with C structs
89
+ * despite the derivation. This is due to the Empty Base Class Optimization:
90
+ *
91
+ * https://en.cppreference.com/w/cpp/language/ebo
92
+ *
93
+ * But since C isn't namespaced, taking `container_t` globally might collide
94
+ * with other projects. So roaring.h uses ROARING_CONTAINER_T, while internal
95
+ * code #undefs that after declaring `typedef ROARING_CONTAINER_T container_t;`
96
+ */
97
+ #if defined(__cplusplus)
98
+ extern "C++" {
99
+ struct container_s {};
100
+ }
101
+ #define ROARING_CONTAINER_T ::roaring::api::container_s
102
+ #else
103
+ #define ROARING_CONTAINER_T void // no compile-time checking
104
+ #endif
105
+
106
+ #define ROARING_FLAG_COW UINT8_C(0x1)
107
+ #define ROARING_FLAG_FROZEN UINT8_C(0x2)
108
+
109
+ /**
110
+ * Roaring arrays are array-based key-value pairs having containers as values
111
+ * and 16-bit integer keys. A roaring bitmap might be implemented as such.
112
+ */
113
+
114
+ // parallel arrays. Element sizes quite different.
115
+ // Alternative is array
116
+ // of structs. Which would have better
117
+ // cache performance through binary searches?
118
+
119
+ typedef struct roaring_array_s {
120
+ int32_t size;
121
+ int32_t allocation_size;
122
+ ROARING_CONTAINER_T **containers; // Use container_t in non-API files!
123
+ uint16_t *keys;
124
+ uint8_t *typecodes;
125
+ uint8_t flags;
126
+ } roaring_array_t;
127
+
128
+
129
+ typedef bool (*roaring_iterator)(uint32_t value, void *param);
130
+ typedef bool (*roaring_iterator64)(uint64_t value, void *param);
131
+
132
+ /**
133
+ * (For advanced users.)
134
+ * The roaring_statistics_t can be used to collect detailed statistics about
135
+ * the composition of a roaring bitmap.
136
+ */
137
+ typedef struct roaring_statistics_s {
138
+ uint32_t n_containers; /* number of containers */
139
+
140
+ uint32_t n_array_containers; /* number of array containers */
141
+ uint32_t n_run_containers; /* number of run containers */
142
+ uint32_t n_bitset_containers; /* number of bitmap containers */
143
+
144
+ uint32_t
145
+ n_values_array_containers; /* number of values in array containers */
146
+ uint32_t n_values_run_containers; /* number of values in run containers */
147
+ uint32_t
148
+ n_values_bitset_containers; /* number of values in bitmap containers */
149
+
150
+ uint32_t n_bytes_array_containers; /* number of allocated bytes in array
151
+ containers */
152
+ uint32_t n_bytes_run_containers; /* number of allocated bytes in run
153
+ containers */
154
+ uint32_t n_bytes_bitset_containers; /* number of allocated bytes in bitmap
155
+ containers */
156
+
157
+ uint32_t
158
+ max_value; /* the maximal value, undefined if cardinality is zero */
159
+ uint32_t
160
+ min_value; /* the minimal value, undefined if cardinality is zero */
161
+ uint64_t sum_value; /* the sum of all values (could be used to compute
162
+ average) */
163
+
164
+ uint64_t cardinality; /* total number of values stored in the bitmap */
165
+
166
+ // and n_values_arrays, n_values_rle, n_values_bitmap
167
+ } roaring_statistics_t;
168
+
169
+ #ifdef __cplusplus
170
+ } } } // extern "C" { namespace roaring { namespace api {
171
+ #endif
172
+
173
+ #endif /* ROARING_TYPES_H */
174
+ /* end file include/roaring/roaring_types.h */
175
+ /* begin file include/roaring/roaring.h */
176
+ /*
177
+ * An implementation of Roaring Bitmaps in C.
178
+ */
179
+
180
+ #ifndef ROARING_H
181
+ #define ROARING_H
182
+
183
+ #include <stdbool.h>
184
+ #include <stdint.h>
185
+ #include <stddef.h> // for `size_t`
186
+
187
+
188
+ #ifdef __cplusplus
189
+ extern "C" { namespace roaring { namespace api {
190
+ #endif
191
+
192
+ typedef struct roaring_bitmap_s {
193
+ roaring_array_t high_low_container;
194
+ } roaring_bitmap_t;
195
+
196
+ /**
197
+ * Dynamically allocates a new bitmap (initially empty).
198
+ * Returns NULL if the allocation fails.
199
+ * Capacity is a performance hint for how many "containers" the data will need.
200
+ * Client is responsible for calling `roaring_bitmap_free()`.
201
+ */
202
+ roaring_bitmap_t *roaring_bitmap_create_with_capacity(uint32_t cap);
203
+
204
+ /**
205
+ * Dynamically allocates a new bitmap (initially empty).
206
+ * Returns NULL if the allocation fails.
207
+ * Client is responsible for calling `roaring_bitmap_free()`.
208
+ */
209
+ static inline roaring_bitmap_t *roaring_bitmap_create(void)
210
+ { return roaring_bitmap_create_with_capacity(0); }
211
+
212
+ /**
213
+ * Initialize a roaring bitmap structure in memory controlled by client.
214
+ * Capacity is a performance hint for how many "containers" the data will need.
215
+ * Can return false if auxiliary allocations fail when capacity greater than 0.
216
+ */
217
+ bool roaring_bitmap_init_with_capacity(roaring_bitmap_t *r, uint32_t cap);
218
+
219
+ /**
220
+ * Initialize a roaring bitmap structure in memory controlled by client.
221
+ * The bitmap will be in a "clear" state, with no auxiliary allocations.
222
+ * Since this performs no allocations, the function will not fail.
223
+ */
224
+ static inline void roaring_bitmap_init_cleared(roaring_bitmap_t *r)
225
+ { roaring_bitmap_init_with_capacity(r, 0); }
226
+
227
+ /**
228
+ * Add all the values between min (included) and max (excluded) that are at a
229
+ * distance k*step from min.
230
+ */
231
+ roaring_bitmap_t *roaring_bitmap_from_range(uint64_t min, uint64_t max,
232
+ uint32_t step);
233
+
234
+ /**
235
+ * Creates a new bitmap from a pointer of uint32_t integers
236
+ */
237
+ roaring_bitmap_t *roaring_bitmap_of_ptr(size_t n_args, const uint32_t *vals);
238
+
239
+ /*
240
+ * Whether you want to use copy-on-write.
241
+ * Saves memory and avoids copies, but needs more care in a threaded context.
242
+ * Most users should ignore this flag.
243
+ *
244
+ * Note: If you do turn this flag to 'true', enabling COW, then ensure that you
245
+ * do so for all of your bitmaps, since interactions between bitmaps with and
246
+ * without COW is unsafe.
247
+ */
248
+ static inline bool roaring_bitmap_get_copy_on_write(const roaring_bitmap_t* r) {
249
+ return r->high_low_container.flags & ROARING_FLAG_COW;
250
+ }
251
+ static inline void roaring_bitmap_set_copy_on_write(roaring_bitmap_t* r,
252
+ bool cow) {
253
+ if (cow) {
254
+ r->high_low_container.flags |= ROARING_FLAG_COW;
255
+ } else {
256
+ r->high_low_container.flags &= ~ROARING_FLAG_COW;
257
+ }
258
+ }
259
+
260
+ roaring_bitmap_t *roaring_bitmap_add_offset(const roaring_bitmap_t *bm,
261
+ int64_t offset);
262
+ /**
263
+ * Describe the inner structure of the bitmap.
264
+ */
265
+ void roaring_bitmap_printf_describe(const roaring_bitmap_t *r);
266
+
267
+ /**
268
+ * Creates a new bitmap from a list of uint32_t integers
269
+ */
270
+ roaring_bitmap_t *roaring_bitmap_of(size_t n, ...);
271
+
272
+ /**
273
+ * Copies a bitmap (this does memory allocation).
274
+ * The caller is responsible for memory management.
275
+ */
276
+ roaring_bitmap_t *roaring_bitmap_copy(const roaring_bitmap_t *r);
277
+
278
+ /**
279
+ * Copies a bitmap from src to dest. It is assumed that the pointer dest
280
+ * is to an already allocated bitmap. The content of the dest bitmap is
281
+ * freed/deleted.
282
+ *
283
+ * It might be preferable and simpler to call roaring_bitmap_copy except
284
+ * that roaring_bitmap_overwrite can save on memory allocations.
285
+ */
286
+ bool roaring_bitmap_overwrite(roaring_bitmap_t *dest,
287
+ const roaring_bitmap_t *src);
288
+
289
+ /**
290
+ * Print the content of the bitmap.
291
+ */
292
+ void roaring_bitmap_printf(const roaring_bitmap_t *r);
293
+
294
+ /**
295
+ * Computes the intersection between two bitmaps and returns new bitmap. The
296
+ * caller is responsible for memory management.
297
+ */
298
+ roaring_bitmap_t *roaring_bitmap_and(const roaring_bitmap_t *r1,
299
+ const roaring_bitmap_t *r2);
300
+
301
+ /**
302
+ * Computes the size of the intersection between two bitmaps.
303
+ */
304
+ uint64_t roaring_bitmap_and_cardinality(const roaring_bitmap_t *r1,
305
+ const roaring_bitmap_t *r2);
306
+
307
+ /**
308
+ * Check whether two bitmaps intersect.
309
+ */
310
+ bool roaring_bitmap_intersect(const roaring_bitmap_t *r1,
311
+ const roaring_bitmap_t *r2);
312
+
313
+ /**
314
+ * Check whether a bitmap and a closed range intersect.
315
+ */
316
+ bool roaring_bitmap_intersect_with_range(const roaring_bitmap_t *bm,
317
+ uint64_t x, uint64_t y);
318
+
319
+ /**
320
+ * Computes the Jaccard index between two bitmaps. (Also known as the Tanimoto
321
+ * distance, or the Jaccard similarity coefficient)
322
+ *
323
+ * The Jaccard index is undefined if both bitmaps are empty.
324
+ */
325
+ double roaring_bitmap_jaccard_index(const roaring_bitmap_t *r1,
326
+ const roaring_bitmap_t *r2);
327
+
328
+ /**
329
+ * Computes the size of the union between two bitmaps.
330
+ */
331
+ uint64_t roaring_bitmap_or_cardinality(const roaring_bitmap_t *r1,
332
+ const roaring_bitmap_t *r2);
333
+
334
+ /**
335
+ * Computes the size of the difference (andnot) between two bitmaps.
336
+ */
337
+ uint64_t roaring_bitmap_andnot_cardinality(const roaring_bitmap_t *r1,
338
+ const roaring_bitmap_t *r2);
339
+
340
+ /**
341
+ * Computes the size of the symmetric difference (xor) between two bitmaps.
342
+ */
343
+ uint64_t roaring_bitmap_xor_cardinality(const roaring_bitmap_t *r1,
344
+ const roaring_bitmap_t *r2);
345
+
346
+ /**
347
+ * Inplace version of `roaring_bitmap_and()`, modifies r1
348
+ * r1 == r2 is allowed
349
+ */
350
+ void roaring_bitmap_and_inplace(roaring_bitmap_t *r1,
351
+ const roaring_bitmap_t *r2);
352
+
353
+ /**
354
+ * Computes the union between two bitmaps and returns new bitmap. The caller is
355
+ * responsible for memory management.
356
+ */
357
+ roaring_bitmap_t *roaring_bitmap_or(const roaring_bitmap_t *r1,
358
+ const roaring_bitmap_t *r2);
359
+
360
+ /**
361
+ * Inplace version of `roaring_bitmap_or(), modifies r1.
362
+ * TODO: decide whether r1 == r2 ok
363
+ */
364
+ void roaring_bitmap_or_inplace(roaring_bitmap_t *r1,
365
+ const roaring_bitmap_t *r2);
366
+
367
+ /**
368
+ * Compute the union of 'number' bitmaps.
369
+ * Caller is responsible for freeing the result.
370
+ * See also `roaring_bitmap_or_many_heap()`
371
+ */
372
+ roaring_bitmap_t *roaring_bitmap_or_many(size_t number,
373
+ const roaring_bitmap_t **rs);
374
+
375
+ /**
376
+ * Compute the union of 'number' bitmaps using a heap. This can sometimes be
377
+ * faster than `roaring_bitmap_or_many() which uses a naive algorithm.
378
+ * Caller is responsible for freeing the result.
379
+ */
380
+ roaring_bitmap_t *roaring_bitmap_or_many_heap(uint32_t number,
381
+ const roaring_bitmap_t **rs);
382
+
383
+ /**
384
+ * Computes the symmetric difference (xor) between two bitmaps
385
+ * and returns new bitmap. The caller is responsible for memory management.
386
+ */
387
+ roaring_bitmap_t *roaring_bitmap_xor(const roaring_bitmap_t *r1,
388
+ const roaring_bitmap_t *r2);
389
+
390
+ /**
391
+ * Inplace version of roaring_bitmap_xor, modifies r1, r1 != r2.
392
+ */
393
+ void roaring_bitmap_xor_inplace(roaring_bitmap_t *r1,
394
+ const roaring_bitmap_t *r2);
395
+
396
+ /**
397
+ * Compute the xor of 'number' bitmaps.
398
+ * Caller is responsible for freeing the result.
399
+ */
400
+ roaring_bitmap_t *roaring_bitmap_xor_many(size_t number,
401
+ const roaring_bitmap_t **rs);
402
+
403
+ /**
404
+ * Computes the difference (andnot) between two bitmaps and returns new bitmap.
405
+ * Caller is responsible for freeing the result.
406
+ */
407
+ roaring_bitmap_t *roaring_bitmap_andnot(const roaring_bitmap_t *r1,
408
+ const roaring_bitmap_t *r2);
409
+
410
+ /**
411
+ * Inplace version of roaring_bitmap_andnot, modifies r1, r1 != r2.
412
+ */
413
+ void roaring_bitmap_andnot_inplace(roaring_bitmap_t *r1,
414
+ const roaring_bitmap_t *r2);
415
+
416
+ /**
417
+ * TODO: consider implementing:
418
+ *
419
+ * "Compute the xor of 'number' bitmaps using a heap. This can sometimes be
420
+ * faster than roaring_bitmap_xor_many which uses a naive algorithm. Caller is
421
+ * responsible for freeing the result.""
422
+ *
423
+ * roaring_bitmap_t *roaring_bitmap_xor_many_heap(uint32_t number,
424
+ * const roaring_bitmap_t **rs);
425
+ */
426
+
427
+ /**
428
+ * Frees the memory.
429
+ */
430
+ void roaring_bitmap_free(const roaring_bitmap_t *r);
431
+
432
+ /**
433
+ * Add value n_args from pointer vals, faster than repeatedly calling
434
+ * `roaring_bitmap_add()`
435
+ */
436
+ void roaring_bitmap_add_many(roaring_bitmap_t *r, size_t n_args,
437
+ const uint32_t *vals);
438
+
439
+ /**
440
+ * Add value x
441
+ */
442
+ void roaring_bitmap_add(roaring_bitmap_t *r, uint32_t x);
443
+
444
+ /**
445
+ * Add value x
446
+ * Returns true if a new value was added, false if the value already existed.
447
+ */
448
+ bool roaring_bitmap_add_checked(roaring_bitmap_t *r, uint32_t x);
449
+
450
+ /**
451
+ * Add all values in range [min, max]
452
+ */
453
+ void roaring_bitmap_add_range_closed(roaring_bitmap_t *r,
454
+ uint32_t min, uint32_t max);
455
+
456
+ /**
457
+ * Add all values in range [min, max)
458
+ */
459
+ static inline void roaring_bitmap_add_range(roaring_bitmap_t *r,
460
+ uint64_t min, uint64_t max) {
461
+ if(max == min) return;
462
+ roaring_bitmap_add_range_closed(r, (uint32_t)min, (uint32_t)(max - 1));
463
+ }
464
+
465
+ /**
466
+ * Remove value x
467
+ */
468
+ void roaring_bitmap_remove(roaring_bitmap_t *r, uint32_t x);
469
+
470
+ /**
471
+ * Remove all values in range [min, max]
472
+ */
473
+ void roaring_bitmap_remove_range_closed(roaring_bitmap_t *r,
474
+ uint32_t min, uint32_t max);
475
+
476
+ /**
477
+ * Remove all values in range [min, max)
478
+ */
479
+ static inline void roaring_bitmap_remove_range(roaring_bitmap_t *r,
480
+ uint64_t min, uint64_t max) {
481
+ if(max == min) return;
482
+ roaring_bitmap_remove_range_closed(r, (uint32_t)min, (uint32_t)(max - 1));
483
+ }
484
+
485
+ /**
486
+ * Remove multiple values
487
+ */
488
+ void roaring_bitmap_remove_many(roaring_bitmap_t *r, size_t n_args,
489
+ const uint32_t *vals);
490
+
491
+ /**
492
+ * Remove value x
493
+ * Returns true if a new value was removed, false if the value was not existing.
494
+ */
495
+ bool roaring_bitmap_remove_checked(roaring_bitmap_t *r, uint32_t x);
496
+
497
+ /**
498
+ * Check if value is present
499
+ */
500
+ bool roaring_bitmap_contains(const roaring_bitmap_t *r, uint32_t val);
501
+
502
+ /**
503
+ * Check whether a range of values from range_start (included)
504
+ * to range_end (excluded) is present
505
+ */
506
+ bool roaring_bitmap_contains_range(const roaring_bitmap_t *r,
507
+ uint64_t range_start,
508
+ uint64_t range_end);
509
+
510
+ /**
511
+ * Get the cardinality of the bitmap (number of elements).
512
+ */
513
+ uint64_t roaring_bitmap_get_cardinality(const roaring_bitmap_t *r);
514
+
515
+ /**
516
+ * Returns the number of elements in the range [range_start, range_end).
517
+ */
518
+ uint64_t roaring_bitmap_range_cardinality(const roaring_bitmap_t *r,
519
+ uint64_t range_start,
520
+ uint64_t range_end);
521
+
522
+ /**
523
+ * Returns true if the bitmap is empty (cardinality is zero).
524
+ */
525
+ bool roaring_bitmap_is_empty(const roaring_bitmap_t *r);
526
+
527
+
528
+ /**
529
+ * Empties the bitmap. It will have no auxiliary allocations (so if the bitmap
530
+ * was initialized in client memory via roaring_bitmap_init(), then a call to
531
+ * roaring_bitmap_clear() would be enough to "free" it)
532
+ */
533
+ void roaring_bitmap_clear(roaring_bitmap_t *r);
534
+
535
+ /**
536
+ * Convert the bitmap to a sorted array, output in `ans`.
537
+ *
538
+ * Caller is responsible to ensure that there is enough memory allocated, e.g.
539
+ *
540
+ * ans = malloc(roaring_bitmap_get_cardinality(bitmap) * sizeof(uint32_t));
541
+ */
542
+ void roaring_bitmap_to_uint32_array(const roaring_bitmap_t *r, uint32_t *ans);
543
+
544
+
545
+ /**
546
+ * Convert the bitmap to a sorted array from `offset` by `limit`, output in `ans`.
547
+ *
548
+ * Caller is responsible to ensure that there is enough memory allocated, e.g.
549
+ *
550
+ * ans = malloc(roaring_bitmap_get_cardinality(limit) * sizeof(uint32_t));
551
+ *
552
+ * Return false in case of failure (e.g., insufficient memory)
553
+ */
554
+ bool roaring_bitmap_range_uint32_array(const roaring_bitmap_t *r,
555
+ size_t offset, size_t limit,
556
+ uint32_t *ans);
557
+
558
+ /**
559
+ * Remove run-length encoding even when it is more space efficient.
560
+ * Return whether a change was applied.
561
+ */
562
+ bool roaring_bitmap_remove_run_compression(roaring_bitmap_t *r);
563
+
564
+ /**
565
+ * Convert array and bitmap containers to run containers when it is more
566
+ * efficient; also convert from run containers when more space efficient.
567
+ *
568
+ * Returns true if the result has at least one run container.
569
+ * Additional savings might be possible by calling `shrinkToFit()`.
570
+ */
571
+ bool roaring_bitmap_run_optimize(roaring_bitmap_t *r);
572
+
573
+ /**
574
+ * If needed, reallocate memory to shrink the memory usage.
575
+ * Returns the number of bytes saved.
576
+ */
577
+ size_t roaring_bitmap_shrink_to_fit(roaring_bitmap_t *r);
578
+
579
+ /**
580
+ * Write the bitmap to an output pointer, this output buffer should refer to
581
+ * at least `roaring_bitmap_size_in_bytes(r)` allocated bytes.
582
+ *
583
+ * See `roaring_bitmap_portable_serialize()` if you want a format that's
584
+ * compatible with Java and Go implementations. This format can sometimes be
585
+ * more space efficient than the portable form, e.g. when the data is sparse.
586
+ *
587
+ * Returns how many bytes written, should be `roaring_bitmap_size_in_bytes(r)`.
588
+ */
589
+ size_t roaring_bitmap_serialize(const roaring_bitmap_t *r, char *buf);
590
+
591
+ /**
592
+ * Use with `roaring_bitmap_serialize()`.
593
+ *
594
+ * (See `roaring_bitmap_portable_deserialize()` if you want a format that's
595
+ * compatible with Java and Go implementations)
596
+ */
597
+ roaring_bitmap_t *roaring_bitmap_deserialize(const void *buf);
598
+
599
+ /**
600
+ * How many bytes are required to serialize this bitmap (NOT compatible
601
+ * with Java and Go versions)
602
+ */
603
+ size_t roaring_bitmap_size_in_bytes(const roaring_bitmap_t *r);
604
+
605
+ /**
606
+ * Read bitmap from a serialized buffer.
607
+ * In case of failure, NULL is returned.
608
+ *
609
+ * This function is unsafe in the sense that if there is no valid serialized
610
+ * bitmap at the pointer, then many bytes could be read, possibly causing a
611
+ * buffer overflow. See also roaring_bitmap_portable_deserialize_safe().
612
+ *
613
+ * This is meant to be compatible with the Java and Go versions:
614
+ * https://github.com/RoaringBitmap/RoaringFormatSpec
615
+ */
616
+ roaring_bitmap_t *roaring_bitmap_portable_deserialize(const char *buf);
617
+
618
+ /**
619
+ * Read bitmap from a serialized buffer safely (reading up to maxbytes).
620
+ * In case of failure, NULL is returned.
621
+ *
622
+ * This is meant to be compatible with the Java and Go versions:
623
+ * https://github.com/RoaringBitmap/RoaringFormatSpec
624
+ */
625
+ roaring_bitmap_t *roaring_bitmap_portable_deserialize_safe(const char *buf,
626
+ size_t maxbytes);
627
+
628
+ /**
629
+ * Check how many bytes would be read (up to maxbytes) at this pointer if there
630
+ * is a bitmap, returns zero if there is no valid bitmap.
631
+ *
632
+ * This is meant to be compatible with the Java and Go versions:
633
+ * https://github.com/RoaringBitmap/RoaringFormatSpec
634
+ */
635
+ size_t roaring_bitmap_portable_deserialize_size(const char *buf,
636
+ size_t maxbytes);
637
+
638
+ /**
639
+ * How many bytes are required to serialize this bitmap.
640
+ *
641
+ * This is meant to be compatible with the Java and Go versions:
642
+ * https://github.com/RoaringBitmap/RoaringFormatSpec
643
+ */
644
+ size_t roaring_bitmap_portable_size_in_bytes(const roaring_bitmap_t *r);
645
+
646
+ /**
647
+ * Write a bitmap to a char buffer. The output buffer should refer to at least
648
+ * `roaring_bitmap_portable_size_in_bytes(r)` bytes of allocated memory.
649
+ *
650
+ * Returns how many bytes were written which should match
651
+ * `roaring_bitmap_portable_size_in_bytes(r)`.
652
+ *
653
+ * This is meant to be compatible with the Java and Go versions:
654
+ * https://github.com/RoaringBitmap/RoaringFormatSpec
655
+ */
656
+ size_t roaring_bitmap_portable_serialize(const roaring_bitmap_t *r, char *buf);
657
+
658
+ /*
659
+ * "Frozen" serialization format imitates memory layout of roaring_bitmap_t.
660
+ * Deserialized bitmap is a constant view of the underlying buffer.
661
+ * This significantly reduces amount of allocations and copying required during
662
+ * deserialization.
663
+ * It can be used with memory mapped files.
664
+ * Example can be found in benchmarks/frozen_benchmark.c
665
+ *
666
+ * [#####] const roaring_bitmap_t *
667
+ * | | |
668
+ * +----+ | +-+
669
+ * | | |
670
+ * [#####################################] underlying buffer
671
+ *
672
+ * Note that because frozen serialization format imitates C memory layout
673
+ * of roaring_bitmap_t, it is not fixed. It is different on big/little endian
674
+ * platforms and can be changed in future.
675
+ */
676
+
677
+ /**
678
+ * Returns number of bytes required to serialize bitmap using frozen format.
679
+ */
680
+ size_t roaring_bitmap_frozen_size_in_bytes(const roaring_bitmap_t *r);
681
+
682
+ /**
683
+ * Serializes bitmap using frozen format.
684
+ * Buffer size must be at least roaring_bitmap_frozen_size_in_bytes().
685
+ */
686
+ void roaring_bitmap_frozen_serialize(const roaring_bitmap_t *r, char *buf);
687
+
688
+ /**
689
+ * Creates constant bitmap that is a view of a given buffer.
690
+ * Buffer data should have been written by `roaring_bitmap_frozen_serialize()`
691
+ * Its beginning must also be aligned by 32 bytes.
692
+ * Length must be equal exactly to `roaring_bitmap_frozen_size_in_bytes()`.
693
+ * In case of failure, NULL is returned.
694
+ *
695
+ * Bitmap returned by this function can be used in all readonly contexts.
696
+ * Bitmap must be freed as usual, by calling roaring_bitmap_free().
697
+ * Underlying buffer must not be freed or modified while it backs any bitmaps.
698
+ */
699
+ const roaring_bitmap_t *roaring_bitmap_frozen_view(const char *buf,
700
+ size_t length);
701
+
702
+ /**
703
+ * Iterate over the bitmap elements. The function iterator is called once for
704
+ * all the values with ptr (can be NULL) as the second parameter of each call.
705
+ *
706
+ * `roaring_iterator` is simply a pointer to a function that returns bool
707
+ * (true means that the iteration should continue while false means that it
708
+ * should stop), and takes (uint32_t,void*) as inputs.
709
+ *
710
+ * Returns true if the roaring_iterator returned true throughout (so that all
711
+ * data points were necessarily visited).
712
+ *
713
+ * Iteration is ordered: from the smallest to the largest elements.
714
+ */
715
+ bool roaring_iterate(const roaring_bitmap_t *r, roaring_iterator iterator,
716
+ void *ptr);
717
+
718
+ bool roaring_iterate64(const roaring_bitmap_t *r, roaring_iterator64 iterator,
719
+ uint64_t high_bits, void *ptr);
720
+
721
+ /**
722
+ * Return true if the two bitmaps contain the same elements.
723
+ */
724
+ bool roaring_bitmap_equals(const roaring_bitmap_t *r1,
725
+ const roaring_bitmap_t *r2);
726
+
727
+ /**
728
+ * Return true if all the elements of r1 are also in r2.
729
+ */
730
+ bool roaring_bitmap_is_subset(const roaring_bitmap_t *r1,
731
+ const roaring_bitmap_t *r2);
732
+
733
+ /**
734
+ * Return true if all the elements of r1 are also in r2, and r2 is strictly
735
+ * greater than r1.
736
+ */
737
+ bool roaring_bitmap_is_strict_subset(const roaring_bitmap_t *r1,
738
+ const roaring_bitmap_t *r2);
739
+
740
+ /**
741
+ * (For expert users who seek high performance.)
742
+ *
743
+ * Computes the union between two bitmaps and returns new bitmap. The caller is
744
+ * responsible for memory management.
745
+ *
746
+ * The lazy version defers some computations such as the maintenance of the
747
+ * cardinality counts. Thus you must call `roaring_bitmap_repair_after_lazy()`
748
+ * after executing "lazy" computations.
749
+ *
750
+ * It is safe to repeatedly call roaring_bitmap_lazy_or_inplace on the result.
751
+ *
752
+ * `bitsetconversion` is a flag which determines whether container-container
753
+ * operations force a bitset conversion.
754
+ */
755
+ roaring_bitmap_t *roaring_bitmap_lazy_or(const roaring_bitmap_t *r1,
756
+ const roaring_bitmap_t *r2,
757
+ const bool bitsetconversion);
758
+
759
+ /**
760
+ * (For expert users who seek high performance.)
761
+ *
762
+ * Inplace version of roaring_bitmap_lazy_or, modifies r1.
763
+ *
764
+ * `bitsetconversion` is a flag which determines whether container-container
765
+ * operations force a bitset conversion.
766
+ */
767
+ void roaring_bitmap_lazy_or_inplace(roaring_bitmap_t *r1,
768
+ const roaring_bitmap_t *r2,
769
+ const bool bitsetconversion);
770
+
771
+ /**
772
+ * (For expert users who seek high performance.)
773
+ *
774
+ * Execute maintenance on a bitmap created from `roaring_bitmap_lazy_or()`
775
+ * or modified with `roaring_bitmap_lazy_or_inplace()`.
776
+ */
777
+ void roaring_bitmap_repair_after_lazy(roaring_bitmap_t *r1);
778
+
779
+ /**
780
+ * Computes the symmetric difference between two bitmaps and returns new bitmap.
781
+ * The caller is responsible for memory management.
782
+ *
783
+ * The lazy version defers some computations such as the maintenance of the
784
+ * cardinality counts. Thus you must call `roaring_bitmap_repair_after_lazy()`
785
+ * after executing "lazy" computations.
786
+ *
787
+ * It is safe to repeatedly call `roaring_bitmap_lazy_xor_inplace()` on
788
+ * the result.
789
+ */
790
+ roaring_bitmap_t *roaring_bitmap_lazy_xor(const roaring_bitmap_t *r1,
791
+ const roaring_bitmap_t *r2);
792
+
793
+ /**
794
+ * (For expert users who seek high performance.)
795
+ *
796
+ * Inplace version of roaring_bitmap_lazy_xor, modifies r1. r1 != r2
797
+ */
798
+ void roaring_bitmap_lazy_xor_inplace(roaring_bitmap_t *r1,
799
+ const roaring_bitmap_t *r2);
800
+
801
+ /**
802
+ * Compute the negation of the bitmap in the interval [range_start, range_end).
803
+ * The number of negated values is range_end - range_start.
804
+ * Areas outside the range are passed through unchanged.
805
+ */
806
+ roaring_bitmap_t *roaring_bitmap_flip(const roaring_bitmap_t *r1,
807
+ uint64_t range_start, uint64_t range_end);
808
+
809
+ /**
810
+ * compute (in place) the negation of the roaring bitmap within a specified
811
+ * interval: [range_start, range_end). The number of negated values is
812
+ * range_end - range_start.
813
+ * Areas outside the range are passed through unchanged.
814
+ */
815
+ void roaring_bitmap_flip_inplace(roaring_bitmap_t *r1, uint64_t range_start,
816
+ uint64_t range_end);
817
+
818
+ /**
819
+ * Selects the element at index 'rank' where the smallest element is at index 0.
820
+ * If the size of the roaring bitmap is strictly greater than rank, then this
821
+ * function returns true and sets element to the element of given rank.
822
+ * Otherwise, it returns false.
823
+ */
824
+ bool roaring_bitmap_select(const roaring_bitmap_t *r, uint32_t rank,
825
+ uint32_t *element);
826
+
827
+ /**
828
+ * roaring_bitmap_rank returns the number of integers that are smaller or equal
829
+ * to x. Thus if x is the first element, this function will return 1. If
830
+ * x is smaller than the smallest element, this function will return 0.
831
+ *
832
+ * The indexing convention differs between roaring_bitmap_select and
833
+ * roaring_bitmap_rank: roaring_bitmap_select refers to the smallest value
834
+ * as having index 0, whereas roaring_bitmap_rank returns 1 when ranking
835
+ * the smallest value.
836
+ */
837
+ uint64_t roaring_bitmap_rank(const roaring_bitmap_t *r, uint32_t x);
838
+
839
+ /**
840
+ * Returns the smallest value in the set, or UINT32_MAX if the set is empty.
841
+ */
842
+ uint32_t roaring_bitmap_minimum(const roaring_bitmap_t *r);
843
+
844
+ /**
845
+ * Returns the greatest value in the set, or 0 if the set is empty.
846
+ */
847
+ uint32_t roaring_bitmap_maximum(const roaring_bitmap_t *r);
848
+
849
+ /**
850
+ * (For advanced users.)
851
+ *
852
+ * Collect statistics about the bitmap, see roaring_types.h for
853
+ * a description of roaring_statistics_t
854
+ */
855
+ void roaring_bitmap_statistics(const roaring_bitmap_t *r,
856
+ roaring_statistics_t *stat);
857
+
858
+ /*********************
859
+ * What follows is code use to iterate through values in a roaring bitmap
860
+
861
+ roaring_bitmap_t *r =...
862
+ roaring_uint32_iterator_t i;
863
+ roaring_create_iterator(r, &i);
864
+ while(i.has_value) {
865
+ printf("value = %d\n", i.current_value);
866
+ roaring_advance_uint32_iterator(&i);
867
+ }
868
+
869
+ Obviously, if you modify the underlying bitmap, the iterator
870
+ becomes invalid. So don't.
871
+ */
872
+
873
+ typedef struct roaring_uint32_iterator_s {
874
+ const roaring_bitmap_t *parent; // owner
875
+ int32_t container_index; // point to the current container index
876
+ int32_t in_container_index; // for bitset and array container, this is out
877
+ // index
878
+ int32_t run_index; // for run container, this points at the run
879
+
880
+ uint32_t current_value;
881
+ bool has_value;
882
+
883
+ const ROARING_CONTAINER_T
884
+ *container; // should be:
885
+ // parent->high_low_container.containers[container_index];
886
+ uint8_t typecode; // should be:
887
+ // parent->high_low_container.typecodes[container_index];
888
+ uint32_t highbits; // should be:
889
+ // parent->high_low_container.keys[container_index]) <<
890
+ // 16;
891
+
892
+ } roaring_uint32_iterator_t;
893
+
894
+ /**
895
+ * Initialize an iterator object that can be used to iterate through the
896
+ * values. If there is a value, then this iterator points to the first value
897
+ * and `it->has_value` is true. The value is in `it->current_value`.
898
+ */
899
+ void roaring_init_iterator(const roaring_bitmap_t *r,
900
+ roaring_uint32_iterator_t *newit);
901
+
902
+ /**
903
+ * Initialize an iterator object that can be used to iterate through the
904
+ * values. If there is a value, then this iterator points to the last value
905
+ * and `it->has_value` is true. The value is in `it->current_value`.
906
+ */
907
+ void roaring_init_iterator_last(const roaring_bitmap_t *r,
908
+ roaring_uint32_iterator_t *newit);
909
+
910
+ /**
911
+ * Create an iterator object that can be used to iterate through the values.
912
+ * Caller is responsible for calling `roaring_free_iterator()`.
913
+ *
914
+ * The iterator is initialized (this function calls `roaring_init_iterator()`)
915
+ * If there is a value, then this iterator points to the first value and
916
+ * `it->has_value` is true. The value is in `it->current_value`.
917
+ */
918
+ roaring_uint32_iterator_t *roaring_create_iterator(const roaring_bitmap_t *r);
919
+
920
+ /**
921
+ * Advance the iterator. If there is a new value, then `it->has_value` is true.
922
+ * The new value is in `it->current_value`. Values are traversed in increasing
923
+ * orders. For convenience, returns `it->has_value`.
924
+ */
925
+ bool roaring_advance_uint32_iterator(roaring_uint32_iterator_t *it);
926
+
927
+ /**
928
+ * Decrement the iterator. If there's a new value, then `it->has_value` is true.
929
+ * The new value is in `it->current_value`. Values are traversed in decreasing
930
+ * order. For convenience, returns `it->has_value`.
931
+ */
932
+ bool roaring_previous_uint32_iterator(roaring_uint32_iterator_t *it);
933
+
934
+ /**
935
+ * Move the iterator to the first value >= `val`. If there is a such a value,
936
+ * then `it->has_value` is true. The new value is in `it->current_value`.
937
+ * For convenience, returns `it->has_value`.
938
+ */
939
+ bool roaring_move_uint32_iterator_equalorlarger(roaring_uint32_iterator_t *it,
940
+ uint32_t val);
941
+
942
+ /**
943
+ * Creates a copy of an iterator.
944
+ * Caller must free it.
945
+ */
946
+ roaring_uint32_iterator_t *roaring_copy_uint32_iterator(
947
+ const roaring_uint32_iterator_t *it);
948
+
949
+ /**
950
+ * Free memory following `roaring_create_iterator()`
951
+ */
952
+ void roaring_free_uint32_iterator(roaring_uint32_iterator_t *it);
953
+
954
+ /*
955
+ * Reads next ${count} values from iterator into user-supplied ${buf}.
956
+ * Returns the number of read elements.
957
+ * This number can be smaller than ${count}, which means that iterator is drained.
958
+ *
959
+ * This function satisfies semantics of iteration and can be used together with
960
+ * other iterator functions.
961
+ * - first value is copied from ${it}->current_value
962
+ * - after function returns, iterator is positioned at the next element
963
+ */
964
+ uint32_t roaring_read_uint32_iterator(roaring_uint32_iterator_t *it,
965
+ uint32_t* buf, uint32_t count);
966
+
967
+ #ifdef __cplusplus
968
+ } } } // extern "C" { namespace roaring { namespace api {
969
+ #endif
970
+
971
+ #endif /* ROARING_H */
972
+
973
+ #ifdef __cplusplus
974
+ /**
975
+ * Best practices for C++ headers is to avoid polluting global scope.
976
+ * But for C compatibility when just `roaring.h` is included building as
977
+ * C++, default to global access for the C public API.
978
+ *
979
+ * BUT when `roaring.hh` is included instead, it sets this flag. That way
980
+ * explicit namespacing must be used to get the C functions.
981
+ *
982
+ * This is outside the include guard so that if you include BOTH headers,
983
+ * the order won't matter; you still get the global definitions.
984
+ */
985
+ #if !defined(ROARING_API_NOT_IN_GLOBAL_NAMESPACE)
986
+ using namespace ::roaring::api;
987
+ #endif
988
+ #endif
989
+
990
+ /* end file include/roaring/roaring.h */
991
+ /* begin file include/roaring/memory.h */
992
+ #ifndef INCLUDE_ROARING_MEMORY_H_
993
+ #define INCLUDE_ROARING_MEMORY_H_
994
+
995
+ #ifdef __cplusplus
996
+ extern "C" {
997
+ #endif
998
+
999
+ #include <stddef.h> // for size_t
1000
+
1001
+ typedef void* (*roaring_malloc_p)(size_t);
1002
+ typedef void* (*roaring_realloc_p)(void*, size_t);
1003
+ typedef void* (*roaring_calloc_p)(size_t, size_t);
1004
+ typedef void (*roaring_free_p)(void*);
1005
+ typedef void* (*roaring_aligned_malloc_p)(size_t, size_t);
1006
+ typedef void (*roaring_aligned_free_p)(void*);
1007
+
1008
+ typedef struct roaring_memory_s {
1009
+ roaring_malloc_p malloc;
1010
+ roaring_realloc_p realloc;
1011
+ roaring_calloc_p calloc;
1012
+ roaring_free_p free;
1013
+ roaring_aligned_malloc_p aligned_malloc;
1014
+ roaring_aligned_free_p aligned_free;
1015
+ } roaring_memory_t;
1016
+
1017
+ void roaring_init_memory_hook(roaring_memory_t memory_hook);
1018
+
1019
+ void* roaring_malloc(size_t);
1020
+ void* roaring_realloc(void*, size_t);
1021
+ void* roaring_calloc(size_t, size_t);
1022
+ void roaring_free(void*);
1023
+ void* roaring_aligned_malloc(size_t, size_t);
1024
+ void roaring_aligned_free(void*);
1025
+
1026
+ #ifdef __cplusplus
1027
+ }
1028
+ #endif
1029
+
1030
+ #endif // INCLUDE_ROARING_MEMORY_H_
1031
+ /* end file include/roaring/memory.h */