Tracking Issue for `CStr::bytes`

[clarfonthey]

Feature gate: #![feature(cstr_bytes)]

This is a tracking issue for the CStr::bytes API.

Public API

impl CStr {
    pub fn bytes(&self) -> CStrBytes<'_>;
}

// core::ffi::c_str::Bytes
pub struct Bytes<'a> {
    // ...
}
impl Iterator for Bytes<'_> {
    type Item = u8;
    // ...
}

Steps / History

• API change proposal (ACP)¹: ACP: CStr::bytes iterator libs-team#135
• Implementation: Add CStr::bytes iterator #104353
• impl Send + Sync and override count for the CStr::bytes iterator #127444
• Final comment period (FCP)²
• Stabilization PR

Unresolved Questions

• Where should this type be located? This is discussed in ACP: std::ffi::c and std::ffi::os submodules libs-team#134. (Resolution: Store in core::ffi::c_str.)
• Should an AsRef<CStr> and as_c_str method be added to CStrBytes to reflect the slice::Iter API?

Footnotes

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

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

[clarfonthey]

Going through old branches and figured I might as well include the diff for the AsRef impl here just in case we ever do decide to go with it, and so that I can prune the branch locally.

diff --git a/library/core/src/ffi/c_str.rs b/library/core/src/ffi/c_str.rs
index dbdbaccb535..d571e9acb3c 100644
--- a/library/core/src/ffi/c_str.rs
+++ b/library/core/src/ffi/c_str.rs
@@ -783,6 +783,23 @@ fn is_empty(&self) -> bool {
         // the nul terminator.
         unsafe { self.ptr.read() == 0 }
     }
+
+    /// Returns the remainder of the string as a slice.
+    #[unstable(feature = "cstr_bytes", issue = "none")]
+    #[inline]
+    pub fn as_c_str(&self) -> &'a CStr {
+        // SAFETY: We start with a valid C string and never increment beyond the
+        // nul terminator, retaining a valid C string, even if it's empty.
+        unsafe { CStr::from_ptr(self.ptr.as_ptr().cast_const().cast()) }
+    }
+}
+
+#[unstable(feature = "cstr_bytes", issue = "none")]
+impl AsRef<CStr> for Bytes<'_> {
+    #[inline]
+    fn as_ref(&self) -> &CStr {
+        self.as_c_str()
+    }
 }

 #[unstable(feature = "cstr_bytes", issue = "112115")]