Add efficient range iteration: Ranges, UnsetRanges, NextSet, NextClear

Add Bitmap.NextSet and Bitmap.NextClear methods that return (uint32, bool),
equivalent to NextValue/NextAbsentValue but designed for use in loops.

Add Ranges() iter.Seq2 that yields contiguous [start, end) pairs of present
values in O(number of ranges), not O(number of set bits). Uses type-specific
container logic: run containers yield stored intervals directly, bitmap
containers scan uint64 words with TrailingZeros/TrailingOnes, and array
containers walk sorted values linearly. Cross-container ranges are merged.

Add UnsetRanges(min, max) as the complement, yielding gaps within [min, max].

Author: ValentaTomas

iter.go

@@ -42,3 +42,153 @@ func Unset(b *Bitmap, min, max uint32) iter.Seq[uint32] {
 		}
 	}
 }
+
+// Ranges returns an iterator over contiguous ranges of values present in the
+// bitmap. Each pair (start, endExclusive) represents a maximal half-open range
+// [start, endExclusive) where every value is present.
+// endExclusive is uint64 to correctly represent ranges that include MaxUint32.
+//
+// This iterates in O(number of contiguous ranges), not O(number of set bits).
+// Ranges that span container boundaries are merged automatically.
+//
+// See also Values for iterating individual values, and UnsetRanges for
+// iterating contiguous ranges of absent values.
+func Ranges(b *Bitmap) iter.Seq2[uint32, uint64] {
+	return func(yield func(uint32, uint64) bool) {
+		ra := &b.highlowcontainer
+		keys := ra.keys
+		containers := ra.containers
+		n := len(keys)
+
+		var pendingStart, pendingEnd uint64
+		hasPending := false
+
+		emit := func(rStart, rEnd uint64) bool {
+			if hasPending && rStart <= pendingEnd {
+				if rEnd > pendingEnd {
+					pendingEnd = rEnd
+				}
+				return true
+			}
+			if hasPending {
+				if !yield(uint32(pendingStart), pendingEnd) {
+					return false
+				}
+			}
+			pendingStart = rStart
+			pendingEnd = rEnd
+			hasPending = true
+			return true
+		}
+
+		for idx := 0; idx < n; idx++ {
+			hs := uint64(keys[idx]) << 16
+			c := containers[idx]
+
+			switch t := c.(type) {
+			case *runContainer16:
+				for _, iv := range t.iv {
+					if !emit(hs+uint64(iv.start), hs+uint64(iv.start)+uint64(iv.length)+1) {
+						return
+					}
+				}
+
+			case *bitmapContainer:
+				bm := t.bitmap
+				length := uint(len(bm))
+				pos := uint(0)
+
+				for pos < length {
+					if bm[pos] == 0 {
+						pos++
+						continue
+					}
+
+					w := bm[pos]
+					lo := uint(countTrailingZeros(w))
+					bitStart := pos*64 + lo
+
+					ones := uint(countTrailingOnes(w >> lo))
+					if lo+ones < 64 {
+						if !emit(hs|uint64(bitStart), hs|uint64(bitStart+ones)) {
+							return
+						}
+						pos = (bitStart + ones) / 64
+					} else {
+						pos++
+						for pos < length && bm[pos] == 0xFFFFFFFFFFFFFFFF {
+							pos++
+						}
+						var bitEnd uint
+						if pos < length {
+							bitEnd = pos*64 + uint(countTrailingOnes(bm[pos]))
+						} else {
+							bitEnd = length * 64
+						}
+						if !emit(hs|uint64(bitStart), hs|uint64(bitEnd)) {
+							return
+						}
+					}
+				}
+
+			case *arrayContainer:
+				content := t.content
+				i := 0
+				for i < len(content) {
+					start := uint64(content[i])
+					end := start + 1
+					i++
+					for i < len(content) && uint64(content[i]) == end {
+						end++
+						i++
+					}
+					if !emit(hs|start, hs|end) {
+						return
+					}
+				}
+			}
+		}
+
+		if hasPending {
+			yield(uint32(pendingStart), pendingEnd)
+		}
+	}
+}
+
+// UnsetRanges returns an iterator over contiguous ranges of values NOT in the
+// bitmap, within the closed range [min, max]. Each pair (start, endExclusive)
+// represents a maximal half-open range [start, endExclusive) where no value is
+// present in the bitmap. endExclusive is uint64 to correctly represent ranges
+// that include MaxUint32.
+//
+// This iterates in O(number of contiguous ranges), not O(number of unset bits).
+// It works by iterating the set ranges and yielding the gaps between them.
+//
+// See also Unset for iterating individual absent values.
+func UnsetRanges(b *Bitmap, min, max uint32) iter.Seq2[uint32, uint64] {
+	limit := uint64(max) + 1
+	return func(yield func(uint32, uint64) bool) {
+		pos := uint64(min)
+		for start, end := range Ranges(b) {
+			if uint64(start) >= limit {
+				break
+			}
+			if end <= pos {
+				continue
+			}
+			if uint64(start) > pos {
+				gapEnd := uint64(start)
+				if gapEnd > limit {
+					gapEnd = limit
+				}
+				if !yield(uint32(pos), gapEnd) {
+					return
+				}
+			}
+			pos = end
+		}
+		if pos < limit {
+			yield(uint32(pos), limit)
+		}
+	}
+}