ACP: TwoSidedRange trait · Issue #365 · rust-lang/libs-team (original) (raw)

Proposal

Problem statement

RangeBounds exists as a useful generic abstraction that lets users write functions that take any range type. However, is not uncommon that users want to only accept ranges with both start and end bounds (Range and RangeInclusive). If they choose to use RangeBounds for this, they have to resort to runtime panics. Or they have to write their own trait only implemented for the given ranges.

Motivating examples or use cases

The rand crate has a SampleRange trait implemented only for Range and RangeInclusive.

If TwoSidedRange existed, they could use that instead.

TODO: Other examples

Solution sketch

pub trait TwoSidedRange: RangeBounds { // Should this unconditionally clone to match end_*? /// Returns the incisive starting bound of the range fn start_inclusive(&self) -> &T;

/// `None` if range is empty, otherwise returns the inclusive end bound 
fn end_inclusive(&self) -> Option<T>;

/// `None` if end bound would overflow `T`, otherwise returns the exclusive end bound
// Maybe return `Result` instead?
fn end_exclusive(&self) -> Option<T>;

/// Returns the number of steps covered by the range
fn width(&self) -> Option<usize>;

}

impl<T: Step> TwoSidedRange for Range { ... } impl<T: Step> TwoSidedRange for RangeInclusive { ... }

Alternatives

The design of width (airways returning usize) is not ideal, we could instead return the next larger unsigned integer or something instead, but that would require a special trait.

The functions could live on rangebounds instead for better visibility.

Could instead have two traits: StartBoundRange and EndBoundRange and then TwoSidedRange would be expressed with StartBoundRange + EndBoundRange but providing fn width would be tough.

width is similar to ExactSizeIterator::len but implemented fallibly, whereas .len() can silently return incorrect results on platforms where usize is 16 bits.

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

Second, if there's a concrete solution: