Tracking Issue for split_at_checked

[mina86]

Feature gate: #![feature(split_at_checked)].

This is a tracking issue for the addition of split_at_checked and split_at_mut_checked methods to [T] and str types which are non-panicking versions of split_at and split_at_mut methods. Rather than panicking when spit index is out of range (like split_at does), the methods return None.

Public API

impl<T> [T] {
    pub fn split_at_checked(&self, mid: usize) -> Option<(&[T], &[T])>;
    pub fn split_at_mut_checked(&self, mid: usize) -> Option<(&[T], &[T])>;
}

impl str {
    pub fn split_at_checked(&self, mid: usize) -> Option<(&str, &str)>;
    pub fn split_at_mut_checked(&mut self, mid: usize) -> Option<(&str, &str)>;
}

Steps / History

• ACP: ACP: Introduce checked_split_at{,_mut} methods libs-team#308
• Implementation: core: introduce split_at{,_mut}_checked #118578
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

Name of the methods. Some possibilities (suggested in ACP discussion):

1. split_at_checked and split_at_mut_checked — follows naming of split_at_unchecked and split_at_mut_unchecked. Using suffix makes the names sort nicely together.
2. checked_split_at and checked_split_at_mut — follows naming convention of arithmetic types (e.g. checked_add). Those new functions serve similar purpose as checked arithmetic operations.
3. try_split_at and try_split_at_mut — follows naming of various fallible methods such as try_from, try_new, try_for_each etc. Shortest of the three suggestions.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[tgross35]

I wonder if the str method should return a Result since they have two failure modes - invalid char boundary and OOB of the string.

[mina86]

Personally I’d rather not complicate the interface and have the methods on slice and on str return the same kind of value. No strong feelings though.

[faern]

Thanks for pushing for this feature ❤️ I really want this to land! Panic free handling of byte slices has been in a pretty bad state a long time. I came here just now because I was trying out the new split_first_chunk just to realize I could not make the code improvements I have been wanting a long time without also having panic free slice splitting with a runtime mid. split_first_chunk and split_at_checked do the same thing really, but one of them have the splitting index as a const generic.

I just tried slice::split_first_chunk and it does wonders to my code. Both in terms of code simplicity/readability but also to amount of potentially panic locations.

@mina86 You can check the implementation PR step in your initial comment. That's merged 🥳

[UserIsntAvailable]

@m-ou-se Can we get a fcp for this? slice::split_at_{mut}_unchecked is getting stabilized on 1.79.0 and I think is going to be kinda akward to not also provide the safe non-panic option as well on the same release.

Thanks in advance.

---

Name of the methods. Some possibilities

For consistency with the existing methods on slice and str, it probably should be called split_at_{mut}_checked.

I wonder if the str method should return a Result since they have two failure modes - invalid char boundary and OOB of the string.

IMO returning option here should be fine. But t-libs might have something else to say about this?

[Amanieu]

We discussed this in the libs-api meeting and are happy to merge this as it is. The _checked suffix is consistent with the already stabilized _unchecked methods, and returning an Option is consistent with the .get() method.

@rfcbot fcp merge

[rfcbot]

Team member @Amanieu has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.