spearman / range-set Goto Github PK

I used RangeSet for a project today. Although it was helpful, I was initially very confused how to use it. Some very important information about RangeSet is actually not in the docs.rs docs but rather is in either the github README or in comments to issues.

I think the following things should be made clear at either https://docs.rs/range-set or https://docs.rs/range-set/0.0.9/range_set/struct.RangeSet.html. If you like, I can submit a PR adding these things to the documentation, but first I would need you to confirm my current understanding of them is correct.

1. What does the type mean?

   The example type of a RangeSet given in the docs is RangeSet<[RangeInclusive <u32>; 1]> I could understand RangeSet<u32> or RangeSet<RangeInclusive<u32>>, but what is the purpose of the array?

   I think?: From reading the README I think the idea here is that for a ; N] array, as an optimization, if the set consists of no more than N elements the elements will be stored entirely within the object ("on the stack") with no additional allocation. Over N it still works, but starts using the heap.

   Still don't get: Is it legal to use other range types, such as `RangeSet<[Range ]; 1]>?

2. How do you iterate over ranges, rather than values?

   I think?: Per this issue the answer appears to be to say s.as_ref().iter() instead of s.iter().

3. What are the purpose of spilled() and shrink_to_fit()?

   I think?: These are again about the "on stack" optimization, and they are explained in the smallvec documentation.

   Still don't get: Under what circumstances would shrink_to_fit() become relevant? I guess if you add a bunch of ranges forcing a spill and then remove some, the ranges might still be unnecessarily spilled until you shrink()?

4. Is it possible to immutably query the intersection of two range_sets?

   I think?: You can get the intersection using insert_range() or remove_range(), but there is no way to do this without modifying the range_set.

Thanks.

I want to create a custom format for my range set, such as 1:5,7,13:21. I can see how to get an iterator over individual elements, but I don't see how to iterate over ranges.

Add set operations. Possible interface based on methods from standard library BTreeSet:

• contains (element) (#10)
• difference
• intersection
• is_disjoint
• is_subset (#10)
• is_superset (#10)
• symmetric_difference
• union

I think this is related to adding T::one() to the range bounds. Conceivably, the start and/or end of a range could be T::MAX, so you shouldn't assume you can add to them without overflow.

let mut rs = range_set![];
rs.insert_range(0..=u32::MAX); // works
rs.insert_range(0..=0); // panics

Also:

let mut rs = range_set![];
rs.insert_range(0..=0); // works
rs.insert_range(0..=u32::MAX); // panics

T::MAX-1 works fine:

let mut rs = range_set![];
rs.insert_range(0..=0);
rs.insert_range(0..=(u32::MAX-1)); // works
rs.insert_range(0..=(u32::MAX-1)); // works

This came up while I was solving Day 6 part 2 of Advent of Code 2023. I fixed it by bumping from u32 to u64, but that's an inelegant workaround. Thanks for the great library though!

Minimum failing example -

#[cfg(test)]
mod tests {
    use range_set::RangeSet;
    use smallvec::SmallVec;
    use std::ops::RangeInclusive;

    #[test]
    fn range_set() {
        let mut range_set: RangeSet<[RangeInclusive<u32>; 2]> = RangeSet::new();
        range_set.insert_range(3..=3);
        range_set.insert_range(5..=5);
        range_set.insert_range(9..=9);
        range_set.insert_range(1..=7);
    }
}

Test output:

index out of bounds: the len is 3 but the index is 3

The following fails with no rules expected this token in macro call pointing to the :: as the problem:

let rs = range_set![0..=u32::MAX]; // won't compile

Every std::ops::Range* struct implements std::ops::RangeBounds, which holds the endpoints of the range. The endpoints are std::ops::Bound<t>s:

pub enum Bound<T> {
    Included(T),
    Excluded(T),
    Unbounded,
}

Every possible kind of interval can be represented with this machinery: open, closed, half-open, unbounded on either or both ends, even degenerate intervals (singletons and null sets).

An argument against supporting anything other than inclusive ranges is, every numeric type is finite (including floats), and thus the topology of the type is discrete. In other words, for, say, floats, the half-open set [a, b) is precisely the same set as [a, b'] where b' is the largest representable float smaller than b.

My counterargument is that we use these sets to approximate continuous intervals and want them to have the semantics of the usual continuous topology on the reals. In other words, we wish to interpret [a, b) to include all of the numbers between b' and b, despite b being potentially approximate.