Skip to content

Commit

Permalink
Rollup merge of rust-lang#112136 - clarfonthey:ffi-c_str, r=cuviper
Browse files Browse the repository at this point in the history
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)
  • Loading branch information
matthiaskrgr authored Mar 10, 2024
2 parents 094a620 + 1ea6cd7 commit 1b44889
Show file tree
Hide file tree
Showing 7 changed files with 79 additions and 16 deletions.
2 changes: 2 additions & 0 deletions library/alloc/src/ffi/c_str.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! [`CString`] and its related types.
#[cfg(test)]
mod tests;

Expand Down
10 changes: 7 additions & 3 deletions library/alloc/src/ffi/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
17 changes: 12 additions & 5 deletions library/core/src/ffi/c_str.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! [`CStr`] and its related types.
use crate::cmp::Ordering;
use crate::error::Error;
use crate::ffi::c_char;
Expand All @@ -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.
///
Expand All @@ -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:
Expand Down Expand Up @@ -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 }
}
Expand Down
14 changes: 12 additions & 2 deletions library/core/src/ffi/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
{
Expand Down
19 changes: 19 additions & 0 deletions library/std/src/ffi/c_str.rs
Original file line number Diff line number Diff line change
@@ -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;
32 changes: 26 additions & 6 deletions library/std/src/ffi/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand Down
1 change: 1 addition & 0 deletions library/std/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)]
Expand Down

0 comments on commit 1b44889

Please sign in to comment.