Add a form of “descending ranges”

[usaoc]

This PR addresses the lack of range-like sequences in descending order, as previously discussed on Discord. In summary:

• <.. and <..= ranges with a starting point are now {Sequence,List}Range;
• “Descending ranges” (that are not ranges) are added, and ListRange.descending produces (listable) descending ranges.

Methods that produce sequences are as follows:

(rge :: SequenceRange).to_sequence()             // `rge` by itself is specially inlined
(rge :: SequenceRange).step_by(step :: PosInt)   // specially inlined

(rge :: DescendingRange).to_sequence()           // `rge` by itself is specially inlined
(rge :: DescendingRange).step_by(step :: NegInt) // specially inlined

Descending ranges are of the following forms, each corresponding to a sequence range form:

start >=.. end  // .from_to
start >=..= end // .from_to_inclusive
start >=..      // .from
start >.. end   // .from_exclusive_to
start >..= end  // .from_exclusive_to_inclusive
start >..       // .from_exclusive

Descending ranges satisfy DescendingRange, which is not a subclass of Range. They only serve as expressions, not as bindings. Among them, listable ones also satisfy DescendingListRange, which offers a .to_list implementation.

Moreover, (rge :: ListRange).descending() also produces a descending range (more precisely DescendingListRange), and optimization in implicit .to_sequence and dot .step_by cooperate with it. This means that (0..5).descending().step_by(-2) as a sequence is specially inlined.

[samth]

This is precisely the operator names that @dgcosta2 used here https://github.com/dgcosta2/matrix/blob/main/operators.rhm so that seems like a good sign.

[mflatt]

This looks great!

In your summary above, you annotated SequenceRange.step_by as specially inlined, and the improved documentation says the same thing. But aren't SequenceRange.step_by and SequenceRange.to_sequence both specially inlined (including prior to this commit)? Or am I missing something about they way they interact?

Having all ofSequenceRange.step_by, SequenceRange.to_sequence, and SequenceRange.ascending to do the same thing seems like a lot, but I guess the reason for so many aliases is connected to this part that I'm missing about for optimization.

[mflatt]

I see that SequenceRange.step_by and SequenceRange.to_sequence do currently behave differently. I do not know (or have forgotten) why they need to, though.

[usaoc]

Explicit invocations of .to_sequence methods have never been specially treated, since Sequenceable objects (lists, arrays, maps, sets, ranges, etc.) by themselves are already specialized. This aligns with the behavior of a class with both implements Sequenceable and a sequence clause. For SequenceRange.step_by, I only implemented optimization of rge.step_by(step) (in this specific form), because this seems to be the most common form you would write. There isn’t any deep reason why more forms aren’t optimized.

Having both SequenceRange.to_sequence, SequenceRange.ascending, and SequenceRange.step_by does seem a bit bloated to me. I only implemented SequenceRange.ascending because it was suggested on Discord, but probably it isn’t needed since SequenceRange.step_by already does its job. Maybe SequenceRange.to_sequence should be kept 0-ary as well.

I wasn’t very sure about the design of ListRange.descending either. I thought about making it return a DescendingRange instead, and we then wouldn’t need a ~step argument since you can just use DescendingRange.step_by on it. This would also make a hypothetical DescendingListRange slightly more useful, because then you could write something like [& (0..5).descending()] (or maybe it’s still not very useful?). Moreover, this would justify actually specializing rge.descending() calls, which I hesitated about when it would produce a sequence.

[mflatt]

Explicit invocations of .to_sequence methods have never been specially treated [...] aligns with the behavior of a class with both implements Sequenceable and a sequence clause.

Ah, right — I think that's how I had understood it previously, and forgot. We should write something like this in the documentation .to_sequence. Along those lines, I agree about keeping SequenceRange.to_sequence 0-ary.

I also like the ideas of having ListRange.descending produce a DescendingRange, relying on step_by for stepping, removing SequenceRange.ascending, and (maybe longer term) DescendingListRange.

[usaoc]

Updated to incorporate the suggestions, including DescendingListRange.

[mflatt]

This is really great work — thanks! LGTM