Skip to content

Commit e99b66b

Browse files
borsbors
committed
Auto merge of #118578 - mina86:c, r=dtolnay
core: introduce split_at{,_mut}_checked Introduce split_at_checked and split_at_mut_checked methods to slices types (including str) which are non-panicking versions of split_at and split_at_mut respectively. This is analogous to get method being non-panicking version of indexing. - rust-lang/libs-team#308 - #119128
2 parents a58ec8f + 50cbbef commit e99b66b

File tree

3 files changed

+217
-28
lines changed

3 files changed

+217
-28
lines changed

‎library/core/src/lib.rs

+1
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,7 @@
185185
#![feature(set_ptr_value)]
186186
#![feature(slice_ptr_get)]
187187
#![feature(slice_split_at_unchecked)]
188+
#![feature(split_at_checked)]
188189
#![feature(str_internals)]
189190
#![feature(str_split_inclusive_remainder)]
190191
#![feature(str_split_remainder)]

‎library/core/src/slice/mod.rs

+105-10
Original file line numberDiff line numberDiff line change
@@ -1842,7 +1842,8 @@ impl<T> [T] {
18421842
///
18431843
/// # Panics
18441844
///
1845-
/// Panics if `mid > len`.
1845+
/// Panics if `mid > len`. For a non-panicking alternative see
1846+
/// [`split_at_checked`](slice::split_at_checked).
18461847
///
18471848
/// # Examples
18481849
///
@@ -1869,14 +1870,15 @@ impl<T> [T] {
18691870
/// ```
18701871
#[stable(feature = "rust1", since = "1.0.0")]
18711872
#[rustc_const_stable(feature = "const_slice_split_at_not_mut", since = "1.71.0")]
1873+
#[rustc_allow_const_fn_unstable(split_at_checked)]
18721874
#[inline]
18731875
#[track_caller]
18741876
#[must_use]
18751877
pub const fn split_at(&self, mid: usize) -> (&[T], &[T]) {
1876-
assert!(mid <= self.len());
1877-
// SAFETY: `[ptr; mid]` and `[mid; len]` are inside `self`, which
1878-
// fulfills the requirements of `split_at_unchecked`.
1879-
unsafe { self.split_at_unchecked(mid) }
1878+
match self.split_at_checked(mid) {
1879+
Some(pair) => pair,
1880+
None => panic!("mid > len"),
1881+
}
18801882
}
18811883

18821884
/// Divides one mutable slice into two at an index.
@@ -1887,7 +1889,8 @@ impl<T> [T] {
18871889
///
18881890
/// # Panics
18891891
///
1890-
/// Panics if `mid > len`.
1892+
/// Panics if `mid > len`. For a non-panicking alternative see
1893+
/// [`split_at_mut_checked`](slice::split_at_mut_checked).
18911894
///
18921895
/// # Examples
18931896
///
@@ -1906,10 +1909,10 @@ impl<T> [T] {
19061909
#[must_use]
19071910
#[rustc_const_unstable(feature = "const_slice_split_at_mut", issue = "101804")]
19081911
pub const fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) {
1909-
assert!(mid <= self.len());
1910-
// SAFETY: `[ptr; mid]` and `[mid; len]` are inside `self`, which
1911-
// fulfills the requirements of `from_raw_parts_mut`.
1912-
unsafe { self.split_at_mut_unchecked(mid) }
1912+
match self.split_at_mut_checked(mid) {
1913+
Some(pair) => pair,
1914+
None => panic!("mid > len"),
1915+
}
19131916
}
19141917

19151918
/// Divides one slice into two at an index, without doing bounds checking.
@@ -2031,6 +2034,98 @@ impl<T> [T] {
20312034
unsafe { (from_raw_parts_mut(ptr, mid), from_raw_parts_mut(ptr.add(mid), len - mid)) }
20322035
}
20332036

2037+
/// Divides one slice into two at an index, returning `None` if the slice is
2038+
/// too short.
2039+
///
2040+
/// If `mid ≤ len` returns a pair of slices where the first will contain all
2041+
/// indices from `[0, mid)` (excluding the index `mid` itself) and the
2042+
/// second will contain all indices from `[mid, len)` (excluding the index
2043+
/// `len` itself).
2044+
///
2045+
/// Otherwise, if `mid > len`, returns `None`.
2046+
///
2047+
/// # Examples
2048+
///
2049+
/// ```
2050+
/// #![feature(split_at_checked)]
2051+
///
2052+
/// let v = [1, -2, 3, -4, 5, -6];
2053+
///
2054+
/// {
2055+
/// let (left, right) = v.split_at_checked(0).unwrap();
2056+
/// assert_eq!(left, []);
2057+
/// assert_eq!(right, [1, -2, 3, -4, 5, -6]);
2058+
/// }
2059+
///
2060+
/// {
2061+
/// let (left, right) = v.split_at_checked(2).unwrap();
2062+
/// assert_eq!(left, [1, -2]);
2063+
/// assert_eq!(right, [3, -4, 5, -6]);
2064+
/// }
2065+
///
2066+
/// {
2067+
/// let (left, right) = v.split_at_checked(6).unwrap();
2068+
/// assert_eq!(left, [1, -2, 3, -4, 5, -6]);
2069+
/// assert_eq!(right, []);
2070+
/// }
2071+
///
2072+
/// assert_eq!(None, v.split_at_checked(7));
2073+
/// ```
2074+
#[unstable(feature = "split_at_checked", reason = "new API", issue = "119128")]
2075+
#[rustc_const_unstable(feature = "split_at_checked", issue = "119128")]
2076+
#[inline]
2077+
#[must_use]
2078+
pub const fn split_at_checked(&self, mid: usize) -> Option<(&[T], &[T])> {
2079+
if mid <= self.len() {
2080+
// SAFETY: `[ptr; mid]` and `[mid; len]` are inside `self`, which
2081+
// fulfills the requirements of `split_at_unchecked`.
2082+
Some(unsafe { self.split_at_unchecked(mid) })
2083+
} else {
2084+
None
2085+
}
2086+
}
2087+
2088+
/// Divides one mutable slice into two at an index, returning `None` if the
2089+
/// slice is too short.
2090+
///
2091+
/// If `mid ≤ len` returns a pair of slices where the first will contain all
2092+
/// indices from `[0, mid)` (excluding the index `mid` itself) and the
2093+
/// second will contain all indices from `[mid, len)` (excluding the index
2094+
/// `len` itself).
2095+
///
2096+
/// Otherwise, if `mid > len`, returns `None`.
2097+
///
2098+
/// # Examples
2099+
///
2100+
/// ```
2101+
/// #![feature(split_at_checked)]
2102+
///
2103+
/// let mut v = [1, 0, 3, 0, 5, 6];
2104+
///
2105+
/// if let Some((left, right)) = v.split_at_mut_checked(2) {
2106+
/// assert_eq!(left, [1, 0]);
2107+
/// assert_eq!(right, [3, 0, 5, 6]);
2108+
/// left[1] = 2;
2109+
/// right[1] = 4;
2110+
/// }
2111+
/// assert_eq!(v, [1, 2, 3, 4, 5, 6]);
2112+
///
2113+
/// assert_eq!(None, v.split_at_mut_checked(7));
2114+
/// ```
2115+
#[unstable(feature = "split_at_checked", reason = "new API", issue = "119128")]
2116+
#[rustc_const_unstable(feature = "split_at_checked", issue = "119128")]
2117+
#[inline]
2118+
#[must_use]
2119+
pub const fn split_at_mut_checked(&mut self, mid: usize) -> Option<(&mut [T], &mut [T])> {
2120+
if mid <= self.len() {
2121+
// SAFETY: `[ptr; mid]` and `[mid; len]` are inside `self`, which
2122+
// fulfills the requirements of `split_at_unchecked`.
2123+
Some(unsafe { self.split_at_mut_unchecked(mid) })
2124+
} else {
2125+
None
2126+
}
2127+
}
2128+
20342129
/// Returns an iterator over subslices separated by elements that match
20352130
/// `pred`. The matched element is not contained in the subslices.
20362131
///

‎library/core/src/str/mod.rs

+111-18
Original file line numberDiff line numberDiff line change
@@ -641,8 +641,9 @@ impl str {
641641
///
642642
/// # Panics
643643
///
644-
/// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
645-
/// past the end of the last code point of the string slice.
644+
/// Panics if `mid` is not on a UTF-8 code point boundary, or if it is past
645+
/// the end of the last code point of the string slice. For a non-panicking
646+
/// alternative see [`split_at_checked`](str::split_at_checked).
646647
///
647648
/// # Examples
648649
///
@@ -658,12 +659,9 @@ impl str {
658659
#[must_use]
659660
#[stable(feature = "str_split_at", since = "1.4.0")]
660661
pub fn split_at(&self, mid: usize) -> (&str, &str) {
661-
// is_char_boundary checks that the index is in [0, .len()]
662-
if self.is_char_boundary(mid) {
663-
// SAFETY: just checked that `mid` is on a char boundary.
664-
unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
665-
} else {
666-
slice_error_fail(self, 0, mid)
662+
match self.split_at_checked(mid) {
663+
None => slice_error_fail(self, 0, mid),
664+
Some(pair) => pair,
667665
}
668666
}
669667

@@ -681,8 +679,9 @@ impl str {
681679
///
682680
/// # Panics
683681
///
684-
/// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
685-
/// past the end of the last code point of the string slice.
682+
/// Panics if `mid` is not on a UTF-8 code point boundary, or if it is past
683+
/// the end of the last code point of the string slice. For a non-panicking
684+
/// alternative see [`split_at_mut_checked`](str::split_at_mut_checked).
686685
///
687686
/// # Examples
688687
///
@@ -702,20 +701,114 @@ impl str {
702701
pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
703702
// is_char_boundary checks that the index is in [0, .len()]
704703
if self.is_char_boundary(mid) {
705-
let len = self.len();
706-
let ptr = self.as_mut_ptr();
707704
// SAFETY: just checked that `mid` is on a char boundary.
708-
unsafe {
709-
(
710-
from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
711-
from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
712-
)
713-
}
705+
unsafe { self.split_at_mut_unchecked(mid) }
714706
} else {
715707
slice_error_fail(self, 0, mid)
716708
}
717709
}
718710

711+
/// Divide one string slice into two at an index.
712+
///
713+
/// The argument, `mid`, should be a valid byte offset from the start of the
714+
/// string. It must also be on the boundary of a UTF-8 code point. The
715+
/// method returns `None` if that’s not the case.
716+
///
717+
/// The two slices returned go from the start of the string slice to `mid`,
718+
/// and from `mid` to the end of the string slice.
719+
///
720+
/// To get mutable string slices instead, see the [`split_at_mut_checked`]
721+
/// method.
722+
///
723+
/// [`split_at_mut_checked`]: str::split_at_mut_checked
724+
///
725+
/// # Examples
726+
///
727+
/// ```
728+
/// #![feature(split_at_checked)]
729+
///
730+
/// let s = "Per Martin-Löf";
731+
///
732+
/// let (first, last) = s.split_at_checked(3).unwrap();
733+
/// assert_eq!("Per", first);
734+
/// assert_eq!(" Martin-Löf", last);
735+
///
736+
/// assert_eq!(None, s.split_at_checked(13)); // Inside “ö”
737+
/// assert_eq!(None, s.split_at_checked(16)); // Beyond the string length
738+
/// ```
739+
#[inline]
740+
#[must_use]
741+
#[unstable(feature = "split_at_checked", reason = "new API", issue = "119128")]
742+
pub fn split_at_checked(&self, mid: usize) -> Option<(&str, &str)> {
743+
// is_char_boundary checks that the index is in [0, .len()]
744+
if self.is_char_boundary(mid) {
745+
// SAFETY: just checked that `mid` is on a char boundary.
746+
Some(unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) })
747+
} else {
748+
None
749+
}
750+
}
751+
752+
/// Divide one mutable string slice into two at an index.
753+
///
754+
/// The argument, `mid`, should be a valid byte offset from the start of the
755+
/// string. It must also be on the boundary of a UTF-8 code point. The
756+
/// method returns `None` if that’s not the case.
757+
///
758+
/// The two slices returned go from the start of the string slice to `mid`,
759+
/// and from `mid` to the end of the string slice.
760+
///
761+
/// To get immutable string slices instead, see the [`split_at_checked`] method.
762+
///
763+
/// [`split_at_checked`]: str::split_at_checked
764+
///
765+
/// # Examples
766+
///
767+
/// ```
768+
/// #![feature(split_at_checked)]
769+
///
770+
/// let mut s = "Per Martin-Löf".to_string();
771+
/// if let Some((first, last)) = s.split_at_mut_checked(3) {
772+
/// first.make_ascii_uppercase();
773+
/// assert_eq!("PER", first);
774+
/// assert_eq!(" Martin-Löf", last);
775+
/// }
776+
/// assert_eq!("PER Martin-Löf", s);
777+
///
778+
/// assert_eq!(None, s.split_at_mut_checked(13)); // Inside “ö”
779+
/// assert_eq!(None, s.split_at_mut_checked(16)); // Beyond the string length
780+
/// ```
781+
#[inline]
782+
#[must_use]
783+
#[unstable(feature = "split_at_checked", reason = "new API", issue = "119128")]
784+
pub fn split_at_mut_checked(&mut self, mid: usize) -> Option<(&mut str, &mut str)> {
785+
// is_char_boundary checks that the index is in [0, .len()]
786+
if self.is_char_boundary(mid) {
787+
// SAFETY: just checked that `mid` is on a char boundary.
788+
Some(unsafe { self.split_at_mut_unchecked(mid) })
789+
} else {
790+
None
791+
}
792+
}
793+
794+
/// Divide one string slice into two at an index.
795+
///
796+
/// # Safety
797+
///
798+
/// The caller must ensure that `mid` is a valid byte offset from the start
799+
/// of the string and falls on the boundary of a UTF-8 code point.
800+
unsafe fn split_at_mut_unchecked(&mut self, mid: usize) -> (&mut str, &mut str) {
801+
let len = self.len();
802+
let ptr = self.as_mut_ptr();
803+
// SAFETY: caller guarantees `mid` is on a char boundary.
804+
unsafe {
805+
(
806+
from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
807+
from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
808+
)
809+
}
810+
}
811+
719812
/// Returns an iterator over the [`char`]s of a string slice.
720813
///
721814
/// As a string slice consists of valid UTF-8, we can iterate through a

0 commit comments

Comments
 (0)