Add OsStr::to_str_split() and OsString::into_string_split().

library/std/src/ffi/os_str.rs

@@ -178,6 +178,34 @@ impl OsString {
  self.inner.into_string().map_err(|buf| OsString { inner: buf })
  }
 
+ /// Splits the `OsString` into a Unicode prefix and non-Unicode suffix.
+ ///
+ /// The returned `String` is the longest prefix of the `OsString` that
+ /// contained valid Unicode. The returned `OsString` is the rest of the
+ /// original value.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// #![feature(osstr_str_prefix_ops)]
+ ///
+ /// use std::ffi::OsString;
+ ///
+ /// let os_string = OsString::from("foo");
+ /// let (prefix, suffix) = os_string.clone().into_string_split();
+ ///
+ /// let mut rejoined = OsString::from(prefix);
+ /// rejoined.push(suffix);
+ /// assert_eq!(rejoined, os_string);
+ /// ```
+ #[unstable(feature = "osstr_str_prefix_ops", issue = "none")]
+ #[must_use]
+ #[inline]
+ pub fn into_string_split(self) -> (String, OsString) {
+ let (prefix, suffix) = self.inner.into_string_split();
+ (prefix, OsString { inner: suffix })
+ }
+
  /// Extends the string with the given <code>&[OsStr]</code> slice.
  ///
  /// # Examples
@@ -703,6 +731,34 @@ impl OsStr {
  self.inner.to_str()
  }
 
+ /// Splits the `OsStr` into a Unicode prefix and non-Unicode suffix.
+ ///
+ /// The returned `str` is the longest prefix of the `OsStr` that
+ /// contained valid Unicode. The returned `OsStr` is the rest of the
+ /// original value.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// #![feature(osstr_str_prefix_ops)]
+ ///
+ /// use std::ffi::{OsStr, OsString};
+ ///
+ /// let os_str = OsStr::new("foo");
+ /// let (prefix, suffix) = os_str.to_str_split();
+ ///
+ /// let mut rejoined = OsString::from(prefix);
+ /// rejoined.push(suffix);
+ /// assert_eq!(rejoined, os_str);
+ /// ```
+ #[unstable(feature = "osstr_str_prefix_ops", issue = "none")]
+ #[must_use]
+ #[inline]
+ pub fn to_str_split(&self) -> (&str, &OsStr) {
+ let (prefix, suffix) = self.inner.to_str_split();
+ (prefix, Self::from_inner(suffix))
+ }
+
  /// Converts an `OsStr` to a <code>[Cow]<[str]></code>.
  ///
  /// Any non-Unicode sequences are replaced with

library/std/src/sys/unix/os_str.rs

@@ -164,6 +164,27 @@ impl Buf {
  String::from_utf8(self.inner).map_err(|p| Buf { inner: p.into_bytes() })
  }
 
+ pub fn into_string_split(self) -> (String, Buf) {
+ let utf8_err = match str::from_utf8(&self.inner) {
+ Ok(_) => {
+ // SAFETY: If `str::from_utf8()` succeeds then the input is UTF-8.
+ let prefix = unsafe { String::from_utf8_unchecked(self.inner) };
+ return (prefix, Buf { inner: Vec::new() });
+ }
+ Err(err) => err,
+ };
+ let utf8_len = utf8_err.valid_up_to();
+ if utf8_len == 0 {
+ return (String::new(), self);
+ }
+ let mut utf8_bytes = self.inner;
+ let rem_bytes = utf8_bytes.split_off(utf8_len);
+ // SAFETY: `Utf8Error::valid_up_to()` returns an index up to which
+ // valid UTF-8 has been verified.
+ let prefix = unsafe { String::from_utf8_unchecked(utf8_bytes) };
+ (prefix, Buf { inner: rem_bytes })
+ }
+
  pub fn push_slice(&mut self, s: &Slice) {
  self.inner.extend_from_slice(&s.inner)
  }
@@ -205,6 +226,21 @@ impl Slice {
  str::from_utf8(&self.inner).ok()
  }
 
+ pub fn to_str_split(&self) -> (&str, &Slice) {
+ let utf8_err = match str::from_utf8(&self.inner) {
+ Ok(prefix) => return (prefix, Slice::from_u8_slice(b"")),
+ Err(err) => err,
+ };
+ let utf8_len = utf8_err.valid_up_to();
+ if utf8_len == 0 {
+ return ("", self);
+ }
+ // SAFETY: `Utf8Error::valid_up_to()` returns an index up to which
+ // valid UTF-8 has been verified.
+ let prefix = unsafe { str::from_utf8_unchecked(&self.inner[..utf8_len]) };
+ (prefix, Slice::from_u8_slice(&self.inner[utf8_len..]))
+ }
+
  pub fn to_string_lossy(&self) -> Cow<'_, str> {
  String::from_utf8_lossy(&self.inner)
  }

library/std/src/sys/unix/os_str/tests.rs

@@ -16,3 +16,37 @@ fn display() {
  Slice::from_u8_slice(b"Hello\xC0\x80 There\xE6\x83 Goodbye").to_string(),
  );
 }
+
+#[test]
+fn buf_into_string_split() {
+ let mut string = Buf::from_string(String::from("héllô wørld"));
+ {
+ let (prefix, suffix) = string.clone().into_string_split();
+ assert_eq!(prefix, String::from("héllô wørld"));
+ assert_eq!(suffix.into_inner(), Vec::new());
+ }
+
+ string.push_slice(Slice::from_u8_slice(b"\xFF"));
+ {
+ let (prefix, suffix) = string.clone().into_string_split();
+ assert_eq!(prefix, String::from("héllô wørld"));
+ assert_eq!(suffix.into_inner(), vec![0xFF]);
+ }
+}
+
+#[test]
+fn slice_to_str_split() {
+ let mut string = Buf::from_string(String::from("héllô wørld"));
+ {
+ let (prefix, suffix) = string.as_slice().to_str_split();
+ assert_eq!(prefix, "héllô wørld");
+ assert_eq!(&suffix.inner, b"");
+ }
+
+ string.push_slice(Slice::from_u8_slice(b"\xFF"));
+ {
+ let (prefix, suffix) = string.as_slice().to_str_split();
+ assert_eq!(prefix, String::from("héllô wørld"));
+ assert_eq!(&suffix.inner, b"\xFF");
+ }
+}

library/std/src/sys/windows/os_str.rs

@@ -98,6 +98,11 @@ impl Buf {
  self.inner.into_string().map_err(|buf| Buf { inner: buf })
  }
 
+ pub fn into_string_split(self) -> (String, Buf) {
+ let (prefix, suffix) = self.inner.into_string_split();
+ (prefix, Buf { inner: suffix })
+ }
+
  pub fn push_slice(&mut self, s: &Slice) {
  self.inner.push_wtf8(&s.inner)
  }
@@ -159,6 +164,11 @@ impl Slice {
  self.inner.as_str()
  }
 
+ pub fn to_str_split(&self) -> (&str, &Slice) {
+ let (prefix, suffix) = self.inner.to_str_split();
+ (prefix, Slice { inner: suffix })
+ }
+
  pub fn to_string_lossy(&self) -> Cow<'_, str> {
  self.inner.to_string_lossy()
  }

library/std/src/sys_common/wtf8.rs

@@ -441,6 +441,42 @@ impl Wtf8Buf {
  }
  }
 
+ /// Consumes the WTF-8 string and converts it to a (UTF-8, WTF-8) pair.
+ ///
+ /// This does not copy the data.
+ ///
+ /// The first element of the return value is the longest prefix of valid
+ /// UTF-8, with the second element being the remainder.
+ pub fn into_string_split(self) -> (String, Wtf8Buf) {
+ if self.is_known_utf8 {
+ // SAFETY: The inner value is known to be UTF-8.
+ let utf8 = unsafe { String::from_utf8_unchecked(self.bytes) };
+ return (utf8, Wtf8Buf::new());
+ }
+
+ let surrogate_pos = match self.next_surrogate(0) {
+ None => {
+ // SAFETY: Well-formed WTF-8 that contains no surrogates is
+ // also well-formed UTF-8.
+ let utf8 = unsafe { String::from_utf8_unchecked(self.bytes) };
+ return (utf8, Wtf8Buf::new());
+ }
+ Some((surrogate_pos, _)) => surrogate_pos,
+ };
+
+ if surrogate_pos == 0 {
+ return (String::new(), self);
+ }
+
+ let mut utf8_bytes = self.bytes;
+ let wtf8_bytes = utf8_bytes.split_off(surrogate_pos);
+ // SAFETY: `utf8_bytes` is a prefix of a WTF-8 value that contains no
+ // surrogates, and well-formed WTF-8 that contains no surrogates is
+ // also well-formed UTF-8.
+ let utf8 = unsafe { String::from_utf8_unchecked(utf8_bytes) };
+ (utf8, Wtf8Buf { bytes: wtf8_bytes, is_known_utf8: false })
+ }
+
  /// Converts this `Wtf8Buf` into a boxed `Wtf8`.
  #[inline]
  pub fn into_box(self) -> Box<Wtf8> {
@@ -664,6 +700,38 @@ impl Wtf8 {
  }
  }
 
+ /// Losslessly split a WTF-8 string into to a (UTF-8, WTF-8) pair.
+ ///
+ /// This does not copy the data.
+ ///
+ /// The first element of the return value is the longest prefix of valid
+ /// UTF-8, with the second element being the remainder.
+ pub fn to_str_split(&self) -> (&str, &Wtf8) {
+ let surrogate_pos = match self.next_surrogate(0) {
+ None => {
+ // SAFETY: Well-formed WTF-8 that contains no surrogates is
+ // also well-formed UTF-8.
+ let utf8 = unsafe { str::from_utf8_unchecked(&self.bytes) };
+ return (utf8, Wtf8::from_str(""));
+ }
+ Some((surrogate_pos, _)) => surrogate_pos,
+ };
+
+ if surrogate_pos == 0 {
+ return ("", self);
+ }
+
+ let (utf8_bytes, wtf8_bytes) = self.bytes.split_at(surrogate_pos);
+ // SAFETY: `utf8_bytes` is a prefix of a WTF-8 value that contains no
+ // surrogates, and well-formed WTF-8 that contains no surrogates is
+ // also well-formed UTF-8.
+ unsafe {
+ let utf8 = str::from_utf8_unchecked(utf8_bytes);
+ let wtf8 = Wtf8::from_bytes_unchecked(wtf8_bytes);
+ (utf8, wtf8)
+ }
+ }
+
  /// Converts the WTF-8 string to potentially ill-formed UTF-16
  /// and return an iterator of 16-bit code units.
  ///

library/std/src/sys_common/wtf8/tests.rs

@@ -352,6 +352,26 @@ fn wtf8buf_into_string_lossy() {
  assert_eq!(string.clone().into_string_lossy(), String::from("aé 💩�"));
 }
 
+#[test]
+fn wtf8buf_into_string_split() {
+ // is_known_utf8
+ let mut string = Wtf8Buf::from_str("aé");
+ assert_eq!(string.clone().into_string_split(), (String::from("aé"), Wtf8Buf::new()),);
+
+ // !is_known_utf8, next_surrogate(0).is_none()
+ string.push_char(' ');
+ string.push(CodePoint::from_u32(0xD83D).unwrap());
+ string.push(CodePoint::from_u32(0xDCA9).unwrap());
+ assert_eq!(string.clone().into_string_split(), (String::from("aé 💩"), Wtf8Buf::new()),);
+
+ // !is_known_utf8, next_surrogate(0).is_some()
+ string.push(CodePoint::from_u32(0xD800).unwrap());
+ assert_eq!(
+ string.clone().into_string_split(),
+ (String::from("aé 💩"), Wtf8Buf::from_wide(&[0xD800])),
+ );
+}
+
 #[test]
 fn wtf8buf_from_iterator() {
  fn f(values: &[u32]) -> Wtf8Buf {
@@ -538,6 +558,20 @@ fn wtf8_to_string_lossy() {
  assert_eq!(string.to_string_lossy(), expected);
 }
 
+#[test]
+fn wtf8_to_str_split() {
+ // next_surrogate(0).is_none()
+ let mut string = Wtf8Buf::from_str("aé 💩");
+ assert_eq!(string.as_slice().to_str_split(), ("aé 💩", Wtf8::from_str("")),);
+
+ // next_surrogate(0).is_some()
+ string.push(CodePoint::from_u32(0xD800).unwrap());
+ assert_eq!(
+ string.as_slice().to_str_split(),
+ ("aé 💩", Wtf8Buf::from_wide(&[0xD800]).as_slice()),
+ );
+}
+
 #[test]
 fn wtf8_display() {
  fn d(b: &[u8]) -> String {