feat: Implement GetElementsInRange for IntSet

Adds a new public method `GetElementsInRange(int firstElement, int lastElement)`
to the `IntSet` class. This method allows you to enumerate integers from the set
that fall within the specified range `[min(first, last), max(first, last)]`.

The enumeration direction (ascending or descending) is determined by the
order of `firstElement` and `lastElement`.

Key changes include:
- New private helper methods for bidirectional traversal of the internal
  Card/byte structure (`TraverseRootCardsDirectional`,
  `TraverseCardLevelDirectional`, `TraverseByteLevelDirectional`,
  `ProcessBytesDirectional`).
- The existing `GetEnumerator()` was updated to use the new ascending
  directional traversal logic, ensuring consistency.
- Efficient pruning logic is implemented at each level of traversal within
  `GetElementsInRange` to skip blocks of numbers that are outside the
  target range, using a new `GetBlockRange` helper.
- Extensive unit tests have been added to `IntSetTests.cs` to cover
  various scenarios, including empty sets, ascending/descending ranges,
  edge cases, gaps in data, negative numbers, and int.MinValue/MaxValue.

Author: google-labs-jules[bot]

src/IntSet.Tests/IntSetTests.cs

@@ -1,6 +1,7 @@
 
 using System;
 using System.Collections;
+using System.Collections.Generic;
 using System.Linq;
 using Xunit;
 
@@ -450,5 +451,159 @@ public void CopyTo_MatchExactSpace_CopiesAll()
             set.CopyTo(dst, 2);
             Assert.Equal(new[] { 0, 0, 1, 2, 3 }, dst);
         }
+
+        #region GetElementsInRange Tests
+
+        [Fact]
+        public void GetElementsInRange_EmptySet()
+        {
+            var set = new Kibnet.IntSet();
+            Assert.Equal(new List<int>(), set.GetElementsInRange(1, 10).ToList());
+            Assert.Equal(new List<int>(), set.GetElementsInRange(10, 1).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_PopulatedSet_Ascending()
+        {
+            var set = new Kibnet.IntSet(new[] { 1, 5, 10, 15, 20, 25 });
+            Assert.Equal(new List<int> { 1, 5, 10, 15, 20, 25 }, set.GetElementsInRange(1, 25).ToList());
+            Assert.Equal(new List<int> { 10, 15, 20 }, set.GetElementsInRange(10, 20).ToList());
+            Assert.Equal(new List<int> { 1, 5 }, set.GetElementsInRange(0, 5).ToList());
+            Assert.Equal(new List<int> { 20, 25 }, set.GetElementsInRange(20, 30).ToList());
+            Assert.Equal(new List<int>(), set.GetElementsInRange(11, 14).ToList());
+            Assert.Equal(new List<int> { 1, 5, 10, 15, 20, 25 }, set.GetElementsInRange(0, 30).ToList());
+            Assert.Equal(new List<int> { 5, 10, 15 }, set.GetElementsInRange(5, 15).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_PopulatedSet_Descending()
+        {
+            var set = new Kibnet.IntSet(new[] { 1, 5, 10, 15, 20, 25 });
+            Assert.Equal(new List<int> { 25, 20, 15, 10, 5, 1 }, set.GetElementsInRange(25, 1).ToList());
+            Assert.Equal(new List<int> { 20, 15, 10 }, set.GetElementsInRange(20, 10).ToList());
+            Assert.Equal(new List<int> { 25, 20 }, set.GetElementsInRange(30, 20).ToList());
+            Assert.Equal(new List<int> { 5, 1 }, set.GetElementsInRange(5, 0).ToList());
+            Assert.Equal(new List<int>(), set.GetElementsInRange(14, 11).ToList());
+            Assert.Equal(new List<int> { 25, 20, 15, 10, 5, 1 }, set.GetElementsInRange(30, 0).ToList());
+            Assert.Equal(new List<int> { 15, 10, 5 }, set.GetElementsInRange(15, 5).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_PopulatedSet_SingleElementRange()
+        {
+            var set = new Kibnet.IntSet(new[] { 1, 5, 10, 15, 20 });
+            Assert.Equal(new List<int> { 10 }, set.GetElementsInRange(10, 10).ToList());
+            Assert.Equal(new List<int>(), set.GetElementsInRange(11, 11).ToList());
+            Assert.Equal(new List<int> { 1 }, set.GetElementsInRange(1, 1).ToList());
+            Assert.Equal(new List<int> { 20 }, set.GetElementsInRange(20, 20).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_ComplexScenarios_Gaps()
+        {
+            var set = new Kibnet.IntSet(new[] { 1, 2, 3, 10, 11, 12, 20, 21, 22 });
+            Assert.Equal(new List<int> { 3, 10, 11 }, set.GetElementsInRange(3, 11).ToList());
+            Assert.Equal(new List<int> { 11, 10, 3 }, set.GetElementsInRange(11, 3).ToList());
+            Assert.Equal(new List<int> { 3, 10 }, set.GetElementsInRange(3, 10).ToList()); // Test case name was 'Asc across gap'
+            Assert.Equal(new List<int> { 10, 3 }, set.GetElementsInRange(10, 3).ToList()); // Test case name was 'Desc across gap'
+        }
+
+        [Fact]
+        public void GetElementsInRange_ComplexScenarios_NegativeNumbers()
+        {
+            var negSet = new Kibnet.IntSet(new[] { -10, -5, 0, 5, 10 });
+            Assert.Equal(new List<int> { -5, 0, 5 }, negSet.GetElementsInRange(-5, 5).ToList());
+            Assert.Equal(new List<int> { 5, 0, -5 }, negSet.GetElementsInRange(5, -5).ToList());
+            Assert.Equal(new List<int> { -10, -5 }, negSet.GetElementsInRange(-15, -5).ToList());
+            Assert.Equal(new List<int> { -5, -10 }, negSet.GetElementsInRange(-5, -15).ToList());
+            Assert.Equal(new List<int> { -10 }, negSet.GetElementsInRange(-10, -10).ToList());
+            Assert.Equal(new List<int> { 0 }, negSet.GetElementsInRange(0, 0).ToList());
+             Assert.Equal(new List<int> { 10 }, negSet.GetElementsInRange(10, 10).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_FullRange_MinMaxInt()
+        {
+            var set = new Kibnet.IntSet(new[] { int.MinValue, 0, int.MaxValue });
+            Assert.Equal(new List<int> { int.MinValue, 0, int.MaxValue }, set.GetElementsInRange(int.MinValue, int.MaxValue).ToList());
+            Assert.Equal(new List<int> { int.MaxValue, 0, int.MinValue }, set.GetElementsInRange(int.MaxValue, int.MinValue).ToList());
+        }
+        
+        [Fact]
+        public void GetElementsInRange_LargeNumbers()
+        {
+            var set = new Kibnet.IntSet(new[] { 1000000, 2000000, 3000000, int.MaxValue - 5, int.MaxValue });
+            Assert.Equal(new List<int> { 1000000, 2000000 }, set.GetElementsInRange(1000000, 2500000).ToList());
+            Assert.Equal(new List<int> { 2000000, 1000000 }, set.GetElementsInRange(2500000, 1000000).ToList());
+            Assert.Equal(new List<int> { int.MaxValue - 5, int.MaxValue }, set.GetElementsInRange(int.MaxValue - 10, int.MaxValue).ToList());
+            Assert.Equal(new List<int> { int.MaxValue, int.MaxValue -5 }, set.GetElementsInRange(int.MaxValue, int.MaxValue - 10).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_RangeOutsidePopulatedData()
+        {
+            var set = new Kibnet.IntSet(new[] { 10, 20, 30 });
+            Assert.Equal(new List<int>(), set.GetElementsInRange(1, 5).ToList()); // Range before
+            Assert.Equal(new List<int>(), set.GetElementsInRange(5, 1).ToList());
+            Assert.Equal(new List<int>(), set.GetElementsInRange(35, 40).ToList()); // Range after
+            Assert.Equal(new List<int>(), set.GetElementsInRange(40, 35).ToList());
+            Assert.Equal(new List<int>(), set.GetElementsInRange(22, 28).ToList()); // Range between elements
+            Assert.Equal(new List<int>(), set.GetElementsInRange(28, 22).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_SingleElementInSet_MatchingRange()
+        {
+            var set = new Kibnet.IntSet(new[] { 42 });
+            Assert.Equal(new List<int> { 42 }, set.GetElementsInRange(42, 42).ToList());
+            Assert.Equal(new List<int> { 42 }, set.GetElementsInRange(40, 45).ToList());
+            Assert.Equal(new List<int> { 42 }, set.GetElementsInRange(45, 40).ToList());
+        }
+
+        [Fact]
+        public void GetElementsInRange_SingleElementInSet_NonMatchingRange()
+        {
+            var set = new Kibnet.IntSet(new[] { 42 });
+            Assert.Equal(new List<int>(), set.GetElementsInRange(10, 20).ToList());
+            Assert.Equal(new List<int>(), set.GetElementsInRange(50, 60).ToList());
+        }
+        
+        // Test with a set that forces traversal through multiple levels of cards
+        [Fact]
+        public void GetElementsInRange_DeepTraversal()
+        {
+            // These numbers are chosen to likely span different i0, i1, i2, i3 blocks
+            var data = new List<int> { 0, 1, 2, 
+                                       (1 << 8) + 5, (1 << 8) + 10, // Different i3
+                                       (1 << 14) + 7, (1 << 14) + 15, // Different i2
+                                       (1 << 20) + 3, (1 << 20) + 9,  // Different i1
+                                       (1 << 26) + 100, (1 << 26) + 200, // Different i0
+                                       int.MaxValue - 10, int.MaxValue -1, int.MaxValue};
+            var set = new Kibnet.IntSet(data);
+
+            var expectedAsc = data.Where(x => x >= ((1 << 8) + 5) && x <= ((1 << 26) + 100)).OrderBy(x => x).ToList();
+            Assert.Equal(expectedAsc, set.GetElementsInRange((1 << 8) + 5, (1 << 26) + 100).ToList());
+
+            var expectedDesc = data.Where(x => x >= ((1 << 14) + 7) && x <= ((1 << 20) + 9)).OrderByDescending(x => x).ToList();
+            Assert.Equal(expectedDesc, set.GetElementsInRange((1 << 20) + 9, (1 << 14) + 7).ToList());
+            
+            // Range including int.MaxValue
+            Assert.Equal(new List<int> { (1 << 26) + 200, int.MaxValue - 10, int.MaxValue -1, int.MaxValue }, set.GetElementsInRange((1 << 26) + 150, int.MaxValue).ToList());
+            Assert.Equal(new List<int> { int.MaxValue, int.MaxValue -1, int.MaxValue - 10, (1 << 26) + 200 }, set.GetElementsInRange(int.MaxValue, (1 << 26) + 150).ToList());
+
+            // Range including int.MinValue (if 0 is considered MinValue for positive range)
+            // If IntSet can store negative numbers, this test would be more relevant with actual int.MinValue
+             var dataWithNeg = new List<int>(data);
+             dataWithNeg.Add(int.MinValue);
+             dataWithNeg.Add(int.MinValue+1);
+             var setWithNeg = new Kibnet.IntSet(dataWithNeg);
+             dataWithNeg.Sort(); // For expected list
+
+            Assert.Equal(dataWithNeg.Where(x => x >= int.MinValue && x <= 2).ToList(), setWithNeg.GetElementsInRange(int.MinValue, 2).ToList());
+            Assert.Equal(dataWithNeg.Where(x => x >= int.MinValue && x <= 2).OrderByDescending(x=>x).ToList(), setWithNeg.GetElementsInRange(2, int.MinValue).ToList());
+
+        }
+
+        #endregion
     }
 }