Skip to content

Add roaring_bitmap_word_range_to_bitset - #907

Merged
lemire merged 2 commits into
masterfrom
range-to-words
Oct 16, 2026
Merged

lemire merged 2 commits into
masterfrom
range-to-words

Conversation

@lemire

@lemire lemire commented Oct 15, 2026 •

Copy link
Copy Markdown
Member

Adds roaring_bitmap_word_range_to_bitset(r, first_word, n_words, words), which writes the values from 64 * first_word to 64 * (first_word + n_words) (excluded) as a bitset: value 64 * (first_word + k) + i sets bit i of words[k]. All n_words words are written, so the caller does not need to zero them.

Unlike roaring_bitmap_to_bitset, which converts the whole bitmap, the cost depends only on the range: the containers before the range are skipped with a binary search, bitset containers are copied with memcpy, and array and run containers set only the bits in the range (binary search for the first value or run, then clipped ranges).

This is useful when a bitmap stands for a bit string of which an application reads windows (for example, a few bytes at a given offset, or a block of words to scan for the first zero bit), where iterating over the values is much slower on dense data.

Test: test_word_range_to_bitset in toplevel_unit.c checks the output against roaring_bitmap_contains on a bitmap with array, bitset and run containers, including partial containers, chunk boundaries, the end of the 32-bit range, empty ranges and an empty bitmap, and checks that no word outside the output is written. All tests pass with sanitizers and with C23.

@Dr-Emann

Copy link
Copy Markdown
Member

Because range comes beforehand, from the name of the function I wouldn't expect the range to also be in units of words.
A bit wordier, but I think I'd prefer the name roaring_bitmap_word_range_to_bitset (or, taking a range in units of bits, and handling all the edge cases, but optimizing for word aligned ranges, but that's quite a bit more code)

@lemire lemire changed the title Add roaring_bitmap_range_to_words Add roaring_bitmap_word_range_to_bitset Oct 16, 2026
@lemire

lemire commented Oct 16, 2026

Copy link
Copy Markdown
Member Author

Renamed to roaring_bitmap_word_range_to_bitset (and the test to test_word_range_to_bitset). The doc comment now says up front that the range is in units of 64-bit words. I kept the word-aligned range: it is what callers that scan or copy blocks of words need, and a bit range with all its edge cases can be added later if someone needs it.

Writes the values of a range of the bitmap, given in 64-bit words, as a
bitset. Bitset containers are copied, array and run containers set only
the bits in the range, so the cost depends on the range and not on the
size of the bitmap.
…bitset

The new name says that the range is in units of 64-bit words.
@lemire
lemire merged commit 3234081 into master Oct 16, 2026
43 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants