slice::get_clamped

[lolbinarycat]

Proposal

Problem statement

It is often useful to clamp a calculated index to be within the bounds of a slice or array.

Motivating examples or use cases

Take up to the first few elements of a list: x.get_clamped(..5).

Get the second element in a list, or the first element if there are no elements: x.get_clamped(2).

Solution sketch

impl<T> [T] {
    pub fn get_clamped<I>(&self, index: I) -> Option<&I::Output>
    where
        I: SliceIndex<Self>;
    pub fn get_clamped_mut<I>(&mut self, index: I) -> Option<&mut I::Output>
    where
        I: SliceIndex<Self>
}

This would require adding a clamp method to SliceIndex, but that should be fine since its a sealed trait.

These functions would only return None if the slice was empty.

Alternatives

• Allow get_clamped to be called with isize and ranges of isize, so it can handle the wraparound case too (although using Saturating for calulations would probably be more robust, as isize would still be susceptible to overflow in extreme cases)
• This can be written using clamp (or min) and get, but doing so requires listing the name of the slice variable twice, and if you're working with mutable slices, the length would need to be stored in a temporary due to aliasing rules. This is all made worse if you're taking an existing range as a parameter, as you would need to deconstruct then reconstruct that range.

Links and related work

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):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[joshtriplett]

It is often useful

We'd like to see some detailed motivation for this, because we're not seeing likely use cases that can't be trivially replaced with something else.

[Amanieu]

Another alternative is to use Option::or:

// get a single element
slice.get(5).or(slice.last())

// get a slice, clamps to entire slice is len < 5
slice.get(..5).unwrap_or(slice)

[lolbinarycat]

@Amanieu this has the same issue as using max: it requires naming the slice twice, which often means breaking up a long method chain, or repeating a long variable name.

If that's not a compelling enough advantage, that's fine, but I want to make it clear.

[pitaj]

In the interest of not just adding more and more methods to slice, what if instead you added a wrapper type:

pub struct Clamp<Idx>(pub index: Idx);

impl<T, Idx: SliceIndex<T>> SliceIndex<T> for Clamp<Idx> {
    ...
}

// Usage: 
s.get(Clamp(5))
s.get(Clamp(..10))

[lolbinarycat]

In the interest of not just adding more and more methods to slice, what if instead you added a wrapper type

This is an interesting idea, as you could also presumably use this as sl[Clamp(idx)] if you knew a slice was non-empty, but were unsure how many elements it had.