Expose the ability to efficently get the next contigious range of set bits

[Dr-Emann]

Is your feature request related to a problem? Please describe.

Same as RoaringBitmap/roaring-rs#274.

Describe the solution you'd like
Basically the same as RoaringBitmap/roaring-rs#338 - A method to consume a contiguous range of values on an iterator, probably in forward or backwards direction.

It may be worth providing the ability to read a batch of ranges rather than only a single range.

Maybe something like:

typedef struct roaring_uint32_range_inclusive_s {
    uint32_t min;
    uint32_t max;
} roaring_uint32_range_inclusive_t;

/**
 * Reads next ${count} ranges from iterator into user-supplied ${buf}.
 * A range is defined as a maximal interval of consecutive values.
 * For example, the set {1,2,3,5,6} contains two ranges: [1..3] and [5..6].
 * Each range is represented as a struct {min,max}, both inclusive.
 *
 * Returns the number of read ranges.
 * This number can be smaller than ${count}, which means that the iterator is
 * drained.
 *
 * This function satisfies the semantics of iteration and can be used together with
 * other iterator functions.
 *  - first range will start with ${it}->current_value
 *  - after the function returns, the iterator is positioned at the next element
 *    after the end of the last returned range.
 */
uint32_t roaring_uint32_iterator_read_ranges(roaring_uint32_iterator_t *it,
                                             roaring_uint32_range_inclusive_t *buf, uint32_t count);

Describe alternatives you've considered
Currently, the best option is probably using roaring_uint32_iterator_read, and manually keeping track of contiguous values.

Additional context
Yep

Are you willing to contribute code or documentation toward this new feature?
It is a community-driven project.

[lemire]

This is done in the Go and Java implementation with an iterator that fills a buffer, instead of iterating value by value.

type ManyIntIterable interface {
	// NextMany fills buf up with values, returns how many values were returned
	NextMany(buf []uint32) int
	// NextMany64 fills up buf with 64 bit values, uses hs as a mask (OR), returns how many values were returned
	NextMany64(hs uint64, buf []uint64) int
}

https://github.com/RoaringBitmap/roaring/blob/97741272a7e113d59a1a9a82a51f0fba0128f143/roaring.go#L659

There are good chances that if we just point an AI at the Go implementation and ask for a C port, it might do 80% of the work, as the hard work has already been done in Go.

[Dr-Emann]

That functionality is already available in roaring_uint32_iterator_read, this is to expose contiguous ranges, almost like SEEK_DATA/SEEK_HOLE

[lemire]

My bad. I will hide the comment. I was disappointed that we did not support this in CRoaring. Glad that we do!

[lemire]

Ok. Now I understand. Yes, this feature makes sense.