fixing issue 22.

Author: lemire

iter.go

@@ -27,3 +27,16 @@ func Backward(b *Bitmap) func(func(uint32) bool) {
 		}
 	}
 }
+
+// Unset creates an iterator that yields values in the range [min, max] that are NOT contained in the bitmap.
+// The iterator becomes invalid if the bitmap is modified (e.g., with Add or Remove).
+func Unset(b *Bitmap, min, max uint32) func(func(uint32) bool) {
+	return func(yield func(uint32) bool) {
+		it := b.UnsetIterator(min, max)
+		for it.HasNext() {
+			if !yield(it.Next()) {
+				return
+			}
+		}
+	}
+}

iter_test.go

@@ -119,3 +119,160 @@ func TestValues(t *testing.T) {
 
 	assert.Equal(t, testSize, n)
 }
+
+func TestUnset(t *testing.T) {
+	t.Run("empty bitmap", func(t *testing.T) {
+		b := New()
+		it := Unset(b, 5, 10)
+
+		expected := []uint32{5, 6, 7, 8, 9, 10}
+		actual := make([]uint32, 0)
+
+		it(func(val uint32) bool {
+			actual = append(actual, val)
+			return true
+		})
+
+		assert.Equal(t, expected, actual)
+	})
+
+	t.Run("bitmap with some values set", func(t *testing.T) {
+		b := New()
+		b.AddInt(3)
+		b.AddInt(7)
+		b.AddInt(12)
+
+		it := Unset(b, 5, 10)
+
+		expected := []uint32{5, 6, 8, 9, 10}
+		actual := make([]uint32, 0)
+
+		it(func(val uint32) bool {
+			actual = append(actual, val)
+			return true
+		})
+
+		assert.Equal(t, expected, actual)
+	})
+
+	t.Run("range completely outside bitmap", func(t *testing.T) {
+		b := New()
+		b.AddInt(1)
+		b.AddInt(2)
+		b.AddInt(3)
+
+		it := Unset(b, 10, 15)
+
+		expected := []uint32{10, 11, 12, 13, 14, 15}
+		actual := make([]uint32, 0)
+
+		it(func(val uint32) bool {
+			actual = append(actual, val)
+			return true
+		})
+
+		assert.Equal(t, expected, actual)
+	})
+
+	t.Run("range includes set and unset values", func(t *testing.T) {
+		b := New()
+		b.AddInt(5)
+		b.AddInt(8)
+		b.AddInt(9)
+
+		it := Unset(b, 3, 12)
+
+		expected := []uint32{3, 4, 6, 7, 10, 11, 12}
+		actual := make([]uint32, 0)
+
+		it(func(val uint32) bool {
+			actual = append(actual, val)
+			return true
+		})
+
+		assert.Equal(t, expected, actual)
+	})
+
+	t.Run("min greater than max", func(t *testing.T) {
+		b := New()
+		it := Unset(b, 10, 5)
+
+		count := 0
+		it(func(val uint32) bool {
+			count++
+			return true
+		})
+
+		assert.Equal(t, 0, count)
+	})
+
+	t.Run("single value range - unset", func(t *testing.T) {
+		b := New()
+		b.AddInt(5)
+
+		it := Unset(b, 3, 3)
+
+		expected := []uint32{3}
+		actual := make([]uint32, 0)
+
+		it(func(val uint32) bool {
+			actual = append(actual, val)
+			return true
+		})
+
+		assert.Equal(t, expected, actual)
+	})
+
+	t.Run("single value range - set", func(t *testing.T) {
+		b := New()
+		b.AddInt(5)
+
+		it := Unset(b, 5, 5)
+
+		count := 0
+		it(func(val uint32) bool {
+			count++
+			return true
+		})
+
+		assert.Equal(t, 0, count)
+	})
+
+	t.Run("early termination", func(t *testing.T) {
+		b := New()
+
+		it := Unset(b, 1, 10)
+
+		actual := make([]uint32, 0)
+		it(func(val uint32) bool {
+			actual = append(actual, val)
+			return len(actual) < 3 // Stop after 3 values
+		})
+
+		expected := []uint32{1, 2, 3}
+		assert.Equal(t, expected, actual)
+	})
+
+	t.Run("large range with sparse bitmap", func(t *testing.T) {
+		b := New()
+		b.AddInt(100)
+		b.AddInt(500)
+		b.AddInt(1000)
+
+		it := Unset(b, 50, 150)
+
+		actual := make([]uint32, 0)
+		it(func(val uint32) bool {
+			actual = append(actual, val)
+			return true
+		})
+
+		// Should include all values from 50-150 except 100
+		assert.Equal(t, 100, len(actual)) // 150-50+1 - 1 = 101 - 1 = 100
+		assert.Contains(t, actual, uint32(50))
+		assert.Contains(t, actual, uint32(99))
+		assert.NotContains(t, actual, uint32(100))
+		assert.Contains(t, actual, uint32(101))
+		assert.Contains(t, actual, uint32(150))
+	})
+}

roaring.go

@@ -742,6 +742,70 @@ func (ii *manyIntIterator) Initialize(a *Bitmap) {
 	ii.init()
 }
 
+type unsetIterator struct {
+	min, max uint32
+	current  uint32
+	it       IntPeekable
+	hasNext  bool
+}
+
+// Initialize configures the unset iterator to iterate over values in [min, max] that are not in the bitmap
+func (ui *unsetIterator) Initialize(b *Bitmap, min, max uint32) {
+	ui.min = min
+	ui.max = max
+	ui.current = min
+	ui.it = b.Iterator()
+	ui.hasNext = min <= max
+
+	// Advance to first value >= min
+	ui.it.AdvanceIfNeeded(min)
+	ui.updateHasNext()
+}
+
+func (ui *unsetIterator) HasNext() bool {
+	return ui.hasNext
+}
+
+func (ui *unsetIterator) Next() uint32 {
+	if !ui.hasNext {
+		panic("Next() called when HasNext() returns false")
+	}
+
+	result := ui.current
+	ui.current++
+	ui.updateHasNext()
+	return result
+}
+
+func (ui *unsetIterator) updateHasNext() {
+	for ui.current <= ui.max {
+		if !ui.it.HasNext() {
+			// No more set bits, we have values to yield
+			ui.hasNext = true
+			return
+		}
+
+		nextSet := ui.it.PeekNext()
+		if nextSet > ui.max {
+			// Next set bit is beyond our range, we have values to yield
+			ui.hasNext = true
+			return
+		}
+
+		if ui.current < nextSet {
+			// We have unset values before the next set bit
+			ui.hasNext = true
+			return
+		}
+
+		// Skip the set bit
+		ui.it.Next()
+		ui.current = nextSet + 1
+	}
+
+	ui.hasNext = false
+}
+
 // String creates a string representation of the Bitmap
 func (rb *Bitmap) String() string {
 	// inspired by https://github.com/fzandona/goroar/
@@ -824,6 +888,14 @@ func (rb *Bitmap) ManyIterator() ManyIntIterable {
 	return p
 }
 
+// UnsetIterator creates a new IntIterable to iterate over values in the range [min, max] that are NOT contained in the bitmap.
+// The iterator becomes invalid if the bitmap is modified (e.g., with Add or Remove).
+func (rb *Bitmap) UnsetIterator(min, max uint32) IntIterable {
+	p := new(unsetIterator)
+	p.Initialize(rb, min, max)
+	return p
+}
+
 // Clone creates a copy of the Bitmap
 func (rb *Bitmap) Clone() *Bitmap {
 	ptr := new(Bitmap)