Rollup merge of rust-lang#112136 - clarfonthey:ffi-c_str, r=cuviper

Add std::ffi::c_str module

ACP: rust-lang/libs-team#134

`std::ffi` docs before change:
![Structs: VaList, VaListImpl, CStr, CString, FromBytesWithNulError, FromVecWithNulError, IntoStringError, NulError, OsStr, OsString](https://github.com/rust-lang/rust/assets/15850505/b2cf3534-30f9-4ef0-a655-bacdc3a19e17)

`std::ffi` docs after change:
![Re-exports: self::c_str::{FromBytesWithNulError, FromBytesUntilNulError, FromVecWithNulError, NulError, IntoStringError} ; Modules: c_str ; Structs: VaList, VaListImpl, CStr, CString, OsStr, OsString](https://github.com/rust-lang/rust/assets/15850505/23aa6964-da7a-4942-bbf7-42bde2146f9e)

(note: I'm omitting the `c_int`, etc. stuff from the screenshots since it's the same in both. this doesn't just delete those types)

Author: matthiaskrgr

library/alloc/src/ffi/c_str.rs

@@ -1,3 +1,5 @@
+//! [`CString`] and its related types.
+
 #[cfg(test)]
 mod tests;
 

library/alloc/src/ffi/mod.rs

@@ -80,9 +80,13 @@
 
 #![stable(feature = "alloc_ffi", since = "1.64.0")]
 
+#[doc(no_inline)]
 #[stable(feature = "alloc_c_string", since = "1.64.0")]
-pub use self::c_str::FromVecWithNulError;
+pub use self::c_str::{FromVecWithNulError, IntoStringError, NulError};
+
+#[doc(inline)]
 #[stable(feature = "alloc_c_string", since = "1.64.0")]
-pub use self::c_str::{CString, IntoStringError, NulError};
+pub use self::c_str::CString;
 
-mod c_str;
+#[unstable(feature = "c_str_module", issue = "112134")]
+pub mod c_str;

library/core/src/ffi/c_str.rs

@@ -1,3 +1,5 @@
+//! [`CStr`] and its related types.
+
 use crate::cmp::Ordering;
 use crate::error::Error;
 use crate::ffi::c_char;
@@ -9,15 +11,20 @@ use crate::slice;
 use crate::slice::memchr;
 use crate::str;
 
+// FIXME: because this is doc(inline)d, we *have* to use intra-doc links because the actual link
+//   depends on where the item is being documented. however, since this is libcore, we can't
+//   actually reference libstd or liballoc in intra-doc links. so, the best we can do is remove the
+//   links to `CString` and `String` for now until a solution is developed
+
 /// Representation of a borrowed C string.
 ///
 /// This type represents a borrowed reference to a nul-terminated
 /// array of bytes. It can be constructed safely from a <code>&[[u8]]</code>
 /// slice, or unsafely from a raw `*const c_char`. It can then be
 /// converted to a Rust <code>&[str]</code> by performing UTF-8 validation, or
-/// into an owned [`CString`].
+/// into an owned `CString`.
 ///
-/// `&CStr` is to [`CString`] as <code>&[str]</code> is to [`String`]: the former
+/// `&CStr` is to `CString` as <code>&[str]</code> is to `String`: the former
 /// in each pair are borrowed references; the latter are owned
 /// strings.
 ///
@@ -26,9 +33,6 @@ use crate::str;
 /// Instead, safe wrappers of FFI functions may leverage the unsafe [`CStr::from_ptr`] constructor
 /// to provide a safe interface to other consumers.
 ///
-/// [`CString`]: ../../std/ffi/struct.CString.html
-/// [`String`]: ../../std/string/struct.String.html
-///
 /// # Examples
 ///
 /// Inspecting a foreign C string:
@@ -125,10 +129,13 @@ enum FromBytesWithNulErrorKind {
     NotNulTerminated,
 }
 
+// FIXME: const stability attributes should not be required here, I think
 impl FromBytesWithNulError {
+    #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")]
     const fn interior_nul(pos: usize) -> FromBytesWithNulError {
         FromBytesWithNulError { kind: FromBytesWithNulErrorKind::InteriorNul(pos) }
     }
+    #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")]
     const fn not_nul_terminated() -> FromBytesWithNulError {
         FromBytesWithNulError { kind: FromBytesWithNulErrorKind::NotNulTerminated }
     }

library/core/src/ffi/mod.rs

@@ -13,10 +13,20 @@ use crate::fmt;
 use crate::marker::PhantomData;
 use crate::ops::{Deref, DerefMut};
 
+#[doc(no_inline)]
 #[stable(feature = "core_c_str", since = "1.64.0")]
-pub use self::c_str::{CStr, FromBytesUntilNulError, FromBytesWithNulError};
+pub use self::c_str::FromBytesWithNulError;
 
-mod c_str;
+#[doc(no_inline)]
+#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")]
+pub use self::c_str::FromBytesUntilNulError;
+
+#[doc(inline)]
+#[stable(feature = "core_c_str", since = "1.64.0")]
+pub use self::c_str::CStr;
+
+#[unstable(feature = "c_str_module", issue = "112134")]
+pub mod c_str;
 
 macro_rules! type_alias {
     {

library/std/src/ffi/c_str.rs

@@ -0,0 +1,19 @@
+//! [`CStr`], [`CString`], and related types.
+
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use core::ffi::c_str::CStr;
+
+#[stable(feature = "cstr_from_bytes", since = "1.10.0")]
+pub use core::ffi::c_str::FromBytesWithNulError;
+
+#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")]
+pub use core::ffi::c_str::FromBytesUntilNulError;
+
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use alloc::ffi::c_str::{CString, NulError};
+
+#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
+pub use alloc::ffi::c_str::FromVecWithNulError;
+
+#[stable(feature = "cstring_into", since = "1.7.0")]
+pub use alloc::ffi::c_str::IntoStringError;

library/std/src/ffi/mod.rs

@@ -161,12 +161,32 @@
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
-#[stable(feature = "alloc_c_string", since = "1.64.0")]
-pub use alloc::ffi::{CString, FromVecWithNulError, IntoStringError, NulError};
-#[stable(feature = "cstr_from_bytes_until_nul", since = "1.73.0")]
-pub use core::ffi::FromBytesUntilNulError;
-#[stable(feature = "core_c_str", since = "1.64.0")]
-pub use core::ffi::{CStr, FromBytesWithNulError};
+#[unstable(feature = "c_str_module", issue = "112134")]
+pub mod c_str;
+
+#[doc(inline)]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use self::c_str::{CStr, CString};
+
+#[doc(no_inline)]
+#[stable(feature = "cstr_from_bytes", since = "1.10.0")]
+pub use self::c_str::FromBytesWithNulError;
+
+#[doc(no_inline)]
+#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")]
+pub use self::c_str::FromBytesUntilNulError;
+
+#[doc(no_inline)]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use self::c_str::NulError;
+
+#[doc(no_inline)]
+#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
+pub use self::c_str::FromVecWithNulError;
+
+#[doc(no_inline)]
+#[stable(feature = "cstring_into", since = "1.7.0")]
+pub use self::c_str::IntoStringError;
 
 #[stable(feature = "rust1", since = "1.0.0")]
 #[doc(inline)]

library/std/src/lib.rs

@@ -314,6 +314,7 @@
 //
 // Library features (core):
 // tidy-alphabetical-start
+#![feature(c_str_module)]
 #![feature(char_internals)]
 #![feature(core_intrinsics)]
 #![feature(core_io_borrowed_buf)]