c_str.rs - source
Description: Source of the Rust file `library/core/src/ffi/c_str.rs`.

#
core/ffi/
c_str.rs

    1//! [`CStr`] and its related types.
    2
    3use crate::cmp::Ordering;
    4use crate::error::Error;
    5use crate::ffi::c_char;
    6use crate::intrinsics::const_eval_select;
    7use crate::iter::FusedIterator;
    8use crate::marker::PhantomData;
    9use crate::ptr::NonNull;
    10use crate::slice::memchr;
    11use crate::{fmt, ops, slice, str};
    12
    13// FIXME: because this is doc(inline)d, we *have* to use intra-doc links because the actual link
    14//   depends on where the item is being documented. however, since this is libcore, we can't
    15//   actually reference libstd or liballoc in intra-doc links. so, the best we can do is remove the
    16//   links to `CString` and `String` for now until a solution is developed
    17
    18/// A dynamically-sized view of a C string.
    19///
    20/// The type `&CStr` represents a reference to a borrowed nul-terminated
    21/// array of bytes. It can be constructed safely from a <code>&[[u8]]</code>
    22/// slice, or unsafely from a raw `*const c_char`. It can be expressed as a
    23/// literal in the form `c"Hello world"`.
    24///
    25/// The `&CStr` can then be converted to a Rust <code>&[str]</code> by performing
    26/// UTF-8 validation, or into an owned `CString`.
    27///
    28/// `&CStr` is to `CString` as <code>&[str]</code> is to `String`: the former
    29/// in each pair are borrowing references; the latter are owned
    30/// strings.
    31///
    32/// Note that this structure does **not** have a guaranteed layout (the `repr(transparent)`
    33/// notwithstanding) and should not be placed in the signatures of FFI functions.
    34/// Instead, safe wrappers of FFI functions may leverage [`CStr::as_ptr`] and the unsafe
    35/// [`CStr::from_ptr`] constructor to provide a safe interface to other consumers.
    36///
    37/// # Examples
    38///
    39/// Inspecting a foreign C string:
    40///
    41/// ```
    42/// use std::ffi::CStr;
    43/// use std::os::raw::c_char;
    44///
    45/// # /* Extern functions are awkward in doc comments - fake it instead
    46/// extern "C" { fn my_string() -> *const c_char; }
    47/// # */ unsafe extern "C" fn my_string() -> *const c_char { c"hello".as_ptr() }
    48///
    49/// unsafe {
    50///     let slice = CStr::from_ptr(my_string());
    51///     println!("string buffer size without nul terminator: {}", slice.to_bytes().len());
    52/// }
    53/// ```
    54///
    55/// Passing a Rust-originating C string:
    56///
    57/// ```
    58/// use std::ffi::CStr;
    59/// use std::os::raw::c_char;
    60///
    61/// fn work(data: &CStr) {
    62///     unsafe extern "C" fn work_with(s: *const c_char) {}
    63///     unsafe { work_with(data.as_ptr()) }
    64/// }
    65///
    66/// let s = c"Hello world!";
    67/// work(&s);
    68/// ```
    69///
    70/// Converting a foreign C string into a Rust `String`:
    71///
    72/// ```
    73/// use std::ffi::CStr;
    74/// use std::os::raw::c_char;
    75///
    76/// # /* Extern functions are awkward in doc comments - fake it instead
    77/// extern "C" { fn my_string() -> *const c_char; }
    78/// # */ unsafe extern "C" fn my_string() -> *const c_char { c"hello".as_ptr() }
    79///
    80/// fn my_string_safe() -> String {
    81///     let cstr = unsafe { CStr::from_ptr(my_string()) };
    82///     // Get a copy-on-write Cow<'_, str>, then extract the
    83///     // allocated String (or allocate a fresh one if needed).
    84///     cstr.to_string_lossy().into_owned()
    85/// }
    86///
    87/// println!("string: {}", my_string_safe());
    88/// ```
    89///
    90/// [str]: prim@str "str"
    91#[derive(PartialEq, Eq, Hash)]
    92#[stable(feature = "core_c_str", since = "1.64.0")]
    93#[rustc_diagnostic_item = "cstr_type"]
    94#[rustc_has_incoherent_inherent_impls]
    95#[lang = "CStr"]
    96// `fn from` in `impl From<&CStr> for Box<CStr>` current implementation relies
    97// on `CStr` being layout-compatible with `[u8]`.
    98// However, `CStr` layout is considered an implementation detail and must not be relied upon. We
    99// want `repr(transparent)` but we don't want it to show up in rustdoc, so we hide it under
    100// `cfg(doc)`. This is an ad-hoc implementation of attribute privacy.
    101#[repr(transparent)]
    102pub struct CStr {
    103    // FIXME: this should not be represented with a DST slice but rather with
    104    //        just a raw `c_char` along with some form of marker to make
    105    //        this an unsized type. Essentially `sizeof(&CStr)` should be the
    106    //        same as `sizeof(&c_char)` but `CStr` should be an unsized type.
    107    inner: [c_char],
    108}
    109
    110/// An error indicating that a nul byte was not in the expected position.
    111///
    112/// The slice used to create a [`CStr`] must have one and only one nul byte,
    113/// positioned at the end.
    114///
    115/// This error is created by the [`CStr::from_bytes_with_nul`] method.
    116/// See its documentation for more.
    117///
    118/// # Examples
    119///
    120/// ```
    121/// use std::ffi::{CStr, FromBytesWithNulError};
    122///
    123/// let _: FromBytesWithNulError = CStr::from_bytes_with_nul(b"f\0oo").unwrap_err();
    124/// ```
    125#[derive(Clone, Copy, PartialEq, Eq, Debug)]
    126#[stable(feature = "core_c_str", since = "1.64.0")]
    127pub enum FromBytesWithNulError {
    128    /// Data provided contains an interior nul byte at byte `position`.
    129    InteriorNul {
    130        /// The position of the interior nul byte.
    131        position: usize,
    132    },
    133    /// Data provided is not nul terminated.
    134    NotNulTerminated,
    135}
    136
    137#[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")]
    138impl fmt::Display for FromBytesWithNulError {
    139    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    140        match self {
    141            Self::InteriorNul { position } => {
    142                write!(f, "data provided contains an interior nul byte at byte position {position}")
    143            }
    144            Self::NotNulTerminated => write!(f, "data provided is not nul terminated"),
    145        }
    146    }
    147}
    148
    149#[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")]
    150impl Error for FromBytesWithNulError {}
    151
    152/// An error indicating that no nul byte was present.
    153///
    154/// A slice used to create a [`CStr`] must contain a nul byte somewhere
    155/// within the slice.
    156///
    157/// This error is created by the [`CStr::from_bytes_until_nul`] method.
    158#[derive(Clone, PartialEq, Eq, Debug)]
    159#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")]
    160pub struct FromBytesUntilNulError(());
    161
    162#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")]
    163impl fmt::Display for FromBytesUntilNulError {
    164    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    165        write!(f, "data provided does not contain a nul")
    166    }
    167}
    168
    169/// Shows the underlying bytes as a normal string, with invalid UTF-8
    170/// presented as hex escape sequences.
    171#[stable(feature = "cstr_debug", since = "1.3.0")]
    172impl fmt::Debug for CStr {
    173    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    174        fmt::Debug::fmt(crate::bstr::ByteStr::from_bytes(self.to_bytes()), f)
    175    }
    176}
    177
    178#[stable(feature = "cstr_default", since = "1.10.0")]
    179impl Default for &CStr {
    180    #[inline]
    181    fn default() -> Self {
    182        c""
    183    }
    184}
    185
    186impl CStr {
    187    /// Wraps a raw C string with a safe C string wrapper.
    188    ///
    189    /// This function will wrap the provided `ptr` with a `CStr` wrapper, which
    190    /// allows inspection and interoperation of non-owned C strings. The total
    191    /// size of the terminated buffer must be smaller than [`isize::MAX`] **bytes**
    192    /// in memory (a restriction from [`slice::from_raw_parts`]).
    193    ///
    194    /// # Safety
    195    ///
    196    /// * The memory pointed to by `ptr` must contain a valid nul terminator at the
    197    ///   end of the string.
    198    ///
    199    /// * `ptr` must be [valid] for reads of bytes up to and including the nul terminator.
    200    ///   This means in particular:
    201    ///
    202    ///     * The entire memory range of this `CStr` must be contained within a single allocation!
    203    ///     * `ptr` must be non-null even for a zero-length cstr.
    204    ///
    205    /// * The memory referenced by the returned `CStr` must not be mutated for
    206    ///   the duration of lifetime `'a`.
    207    ///
    208    /// * The nul terminator must be within `isize::MAX` from `ptr`
    209    ///
    210    /// > **Note**: This operation is intended to be a 0-cost cast but it is
    211    /// > currently implemented with an up-front calculation of the length of
    212    /// > the string. This is not guaranteed to always be the case.
    213    ///
    214    /// # Caveat
    215    ///
    216    /// The lifetime for the returned slice is inferred from its usage. To prevent accidental misuse,
    217    /// it's suggested to tie the lifetime to whichever source lifetime is safe in the context,
    218    /// such as by providing a helper function taking the lifetime of a host value for the slice,
    219    /// or by explicit annotation.
    220    ///
    221    /// # Examples
    222    ///
    223    /// ```
    224    /// use std::ffi::{c_char, CStr};
    225    ///
    226    /// fn my_string() -> *const c_char {
    227    ///     c"hello".as_ptr()
    228    /// }
    229    ///
    230    /// unsafe {
    231    ///     let slice = CStr::from_ptr(my_string());
    232    ///     assert_eq!(slice.to_str().unwrap(), "hello");
    233    /// }
    234    /// ```
    235    ///
    236    /// ```
    237    /// use std::ffi::{c_char, CStr};
    238    ///
    239    /// const HELLO_PTR: *const c_char = {
    240    ///     const BYTES: &[u8] = b"Hello, world!\0";
    241    ///     BYTES.as_ptr().cast()
    242    /// };
    243    /// const HELLO: &CStr = unsafe { CStr::from_ptr(HELLO_PTR) };
    244    ///
    245    /// assert_eq!(c"Hello, world!", HELLO);
    246    /// ```
    247    ///
    248    /// [valid]: core::ptr#safety
    249    #[inline] // inline is necessary for codegen to see strlen.
    250    #[must_use]
    251    #[stable(feature = "rust1", since = "1.0.0")]
    252    #[rustc_const_stable(feature = "const_cstr_from_ptr", since = "1.81.0")]
    253    pub const unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr {
    254        // SAFETY: The caller has provided a pointer that points to a valid C
    255        // string with a NUL terminator less than `isize::MAX` from `ptr`.
    256        let len = unsafe { strlen(ptr) };
    257
    258        // SAFETY: The caller has provided a valid pointer with length less than
    259        // `isize::MAX`, so `from_raw_parts` is safe. The content remains valid
    260        // and doesn't change for the lifetime of the returned `CStr`. This
    261        // means the call to `from_bytes_with_nul_unchecked` is correct.
    262        //
    263        // The cast from c_char to u8 is ok because a c_char is always one byte.
    264        unsafe { Self::from_bytes_with_nul_unchecked(slice::from_raw_parts(ptr.cast(), len + 1)) }
    265    }
    266
    267    /// Creates a C string wrapper from a byte slice with any number of nuls.
    268    ///
    269    /// This method will create a `CStr` from any byte slice that contains at
    270    /// least one nul byte. Unlike with [`CStr::from_bytes_with_nul`], the caller
    271    /// does not need to know where the nul byte is located.
    272    ///
    273    /// If the first byte is a nul character, this method will return an
    274    /// empty `CStr`. If multiple nul characters are present, the `CStr` will
    275    /// end at the first one.
    276    ///
    277    /// If the slice only has a single nul byte at the end, this method is
    278    /// equivalent to [`CStr::from_bytes_with_nul`].
    279    ///
    280    /// # Examples
    281    /// ```
    282    /// use std::ffi::CStr;
    283    ///
    284    /// let mut buffer = [0u8; 16];
    285    /// unsafe {
    286    ///     // Here we might call an unsafe C function that writes a string
    287    ///     // into the buffer.
    288    ///     let buf_ptr = buffer.as_mut_ptr();
    289    ///     buf_ptr.write_bytes(b'A', 8);
    290    /// }
    291    /// // Attempt to extract a C nul-terminated string from the buffer.
    292    /// let c_str = CStr::from_bytes_until_nul(&buffer[..]).unwrap();
    293    /// assert_eq!(c_str.to_str().unwrap(), "AAAAAAAA");
    294    /// ```
    295    ///
    296    #[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")]
    297    #[rustc_const_stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")]
    298    pub const fn from_bytes_until_nul(bytes: &[u8]) -> Result<&CStr, FromBytesUntilNulError> {
    299        let nul_pos = memchr::memchr(0, bytes);
    300        match nul_pos {
    301            Some(nul_pos) => {
    302                // FIXME(const-hack) replace with range index
    303                // SAFETY: nul_pos + 1 <= bytes.len()
    304                let subslice = unsafe { crate::slice::from_raw_parts(bytes.as_ptr(), nul_pos + 1) };
    305                // SAFETY: We know there is a nul byte at nul_pos, so this slice
    306                // (ending at the nul byte) is a well-formed C string.
    307                Ok(unsafe { CStr::from_bytes_with_nul_unchecked(subslice) })
    308            }
    309            None => Err(FromBytesUntilNulError(())),
    310        }
    311    }
    312
    313    /// Creates a C string wrapper from a byte slice with exactly one nul
    314    /// terminator.
    315    ///
    316    /// This function will cast the provided `bytes` to a `CStr`
    317    /// wrapper after ensuring that the byte slice is nul-terminated
    318    /// and does not contain any interior nul bytes.
    319    ///
    320    /// If the nul byte may not be at the end,
    321    /// [`CStr::from_bytes_until_nul`] can be used instead.
    322    ///
    323    /// # Examples
    324    ///
    325    /// ```
    326    /// use std::ffi::CStr;
    327    ///
    328    /// let cstr = CStr::from_bytes_with_nul(b"hello\0");
    329    /// assert_eq!(cstr, Ok(c"hello"));
    330    /// ```
    331    ///
    332    /// Creating a `CStr` without a trailing nul terminator is an error:
    333    ///
    334    /// ```
    335    /// use std::ffi::{CStr, FromBytesWithNulError};
    336    ///
    337    /// let cstr = CStr::from_bytes_with_nul(b"hello");
    338    /// assert_eq!(cstr, Err(FromBytesWithNulError::NotNulTerminated));
    339    /// ```
    340    ///
    341    /// Creating a `CStr` with an interior nul byte is an error:
    342    ///
    343    /// ```
    344    /// use std::ffi::{CStr, FromBytesWithNulError};
    345    ///
    346    /// let cstr = CStr::from_bytes_with_nul(b"he\0llo\0");
    347    /// assert_eq!(cstr, Err(FromBytesWithNulError::InteriorNul { position: 2 }));
    348    /// ```
    349    #[stable(feature = "cstr_from_bytes", since = "1.10.0")]
    350    #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")]
    351    pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, FromBytesWithNulError> {
    352        let nul_pos = memchr::memchr(0, bytes);
    353        match nul_pos {
    354            Some(nul_pos) if nul_pos + 1 == bytes.len() => {
    355                // SAFETY: We know there is only one nul byte, at the end
    356                // of the byte slice.
    357                Ok(unsafe { Self::from_bytes_with_nul_unchecked(bytes) })
    358            }
    359            Some(position) => Err(FromBytesWithNulError::InteriorNul { position }),
    360            None => Err(FromBytesWithNulError::NotNulTerminated),
    361        }
    362    }
    363
    364    /// Unsafely creates a C string wrapper from a byte slice.
    365    ///
    366    /// This function will cast the provided `bytes` to a `CStr` wrapper without
    367    /// performing any sanity checks.
    368    ///
    369    /// # Safety
    370    /// The provided slice **must** be nul-terminated and not contain any interior
    371    /// nul bytes.
    372    ///
    373    /// # Examples
    374    ///
    375    /// ```
    376    /// use std::ffi::CStr;
    377    ///
    378    /// let bytes = b"Hello world!\0";
    379    ///
    380    /// let cstr = unsafe { CStr::from_bytes_with_nul_unchecked(bytes) };
    381    /// assert_eq!(cstr.to_bytes_with_nul(), bytes);
    382    /// ```
    383    #[inline]
    384    #[must_use]
    385    #[stable(feature = "cstr_from_bytes", since = "1.10.0")]
    386    #[rustc_const_stable(feature = "const_cstr_unchecked", since = "1.59.0")]
    387    #[rustc_allow_const_fn_unstable(const_eval_select)]
    388    pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr {
    389        const_eval_select!(
    390            @capture { bytes: &[u8] } -> &CStr:
    391            if const {
    392                // Saturating so that an empty slice panics in the assert with a good
    393                // message, not here due to underflow.
    394                let mut i = bytes.len().saturating_sub(1);
    395                assert!(!bytes.is_empty() && bytes[i] == 0, "input was not nul-terminated");
    396
    397                // Ending nul byte exists, skip to the rest.
    398                while i != 0 {
    399                    i -= 1;
    400                    let byte = bytes[i];
    401                    assert!(byte != 0, "input contained interior nul");
    402                }
    403
    404                // SAFETY: See runtime cast comment below.
    405                unsafe { &*(bytes as *const [u8] as *const CStr) }
    406            } else {
    407                // Chance at catching some UB at runtime with debug builds.
    408                debug_assert!(!bytes.is_empty() && bytes[bytes.len() - 1] == 0);
    409
    410                // SAFETY: Casting to CStr is safe because its internal representation
    411                // is a [u8] too (safe only inside std).
    412                // Dereferencing the obtained pointer is safe because it comes from a
    413                // reference. Making a reference is then safe because its lifetime
    414                // is bound by the lifetime of the given `bytes`.
    415                unsafe { &*(bytes as *const [u8] as *const CStr) }
    416            }
    417        )
    418    }
    419
    420    /// Returns the inner pointer to this C string.
    421    ///
    422    /// The returned pointer will be valid for as long as `self` is, and points
    423    /// to a contiguous region of memory terminated with a 0 byte to represent
    424    /// the end of the string.
    425    ///
    426    /// The type of the returned pointer is
    427    /// [`*const c_char`][crate::ffi::c_char], and whether it's
    428    /// an alias for `*const i8` or `*const u8` is platform-specific.
    429    ///
    430    /// **WARNING**
    431    ///
    432    /// The returned pointer is read-only; writing to it (including passing it
    433    /// to C code that writes to it) causes undefined behavior.
    434    ///
    435    /// It is your responsibility to make sure that the underlying memory is not
    436    /// freed too early. For example, the following code will cause undefined
    437    /// behavior when `ptr` is used inside the `unsafe` block:
    438    ///
    439    /// ```no_run
    440    /// # #![expect(dangling_pointers_from_temporaries)]
    441    /// use std::ffi::{CStr, CString};
    442    ///
    443    /// // 💀 The meaning of this entire program is undefined,
    444    /// // 💀 and nothing about its behavior is guaranteed,
    445    /// // 💀 not even that its behavior resembles the code as written,
    446    /// // 💀 just because it contains a single instance of undefined behavior!
    447    ///
    448    /// // 🚨 creates a dangling pointer to a temporary `CString`
    449    /// // 🚨 that is deallocated at the end of the statement
    450    /// let ptr = CString::new("Hi!".to_uppercase()).unwrap().as_ptr();
    451    ///
    452    /// // without undefined behavior, you would expect that `ptr` equals:
    453    /// dbg!(CStr::from_bytes_with_nul(b"HI!\0").unwrap());
    454    ///
    455    /// // 🙏 Possibly the program behaved as expected so far,
    456    /// // 🙏 and this just shows `ptr` is now garbage..., but
    457    /// // 💀 this violates `CStr::from_ptr`'s safety contract
    458    /// // 💀 leading to a dereference of a dangling pointer,
    459    /// // 💀 which is immediate undefined behavior.
    460    /// // 💀 *BOOM*, you're dead, your entire program has no meaning.
    461    /// dbg!(unsafe { CStr::from_ptr(ptr) });
    462    /// ```
    463    ///
    464    /// This happens because, the pointer returned by `as_ptr` does not carry any
    465    /// lifetime information, and the `CString` is deallocated immediately after
    466    /// the expression that it is part of has been evaluated.
    467    /// To fix the problem, bind the `CString` to a local variable:
    468    ///
    469    /// ```
    470    /// use std::ffi::{CStr, CString};
    471    ///
    472    /// let c_str = CString::new("Hi!".to_uppercase()).unwrap();
    473    /// let ptr = c_str.as_ptr();
    474    ///
    475    /// assert_eq!(unsafe { CStr::from_ptr(ptr) }, c"HI!");
    476    /// ```
    477    #[inline]
    478    #[must_use]
    479    #[stable(feature = "rust1", since = "1.0.0")]
    480    #[rustc_const_stable(feature = "const_str_as_ptr", since = "1.32.0")]
    481    #[rustc_as_ptr]
    482    #[rustc_never_returns_null_ptr]
    483    pub const fn as_ptr(&self) -> *const c_char {
    484        self.inner.as_ptr()
    485    }
    486
    487    /// We could eventually expose this publicly, if we wanted.
    488    #[inline]
    489    #[must_use]
    490    const fn as_non_null_ptr(&self) -> NonNull<c_char> {
    491        // FIXME(const_trait_impl) replace with `NonNull::from`
    492        // SAFETY: a reference is never null
    493        unsafe { NonNull::new_unchecked(&self.inner as *const [c_char] as *mut [c_char]) }
    494            .as_non_null_ptr()
    495    }
    496
    497    /// Returns the length of `self`. Like C's `strlen`, this does not include the nul terminator.
    498    ///
    499    /// > **Note**: This method is currently implemented as a constant-time
    500    /// > cast, but it is planned to alter its definition in the future to
    501    /// > perform the length calculation whenever this method is called.
    502    ///
    503    /// # Examples
    504    ///
    505    /// ```
    506    /// assert_eq!(c"foo".count_bytes(), 3);
    507    /// assert_eq!(c"".count_bytes(), 0);
    508    /// ```
    509    #[inline]
    510    #[must_use]
    511    #[doc(alias("len", "strlen"))]
    512    #[stable(feature = "cstr_count_bytes", since = "1.79.0")]
    513    #[rustc_const_stable(feature = "const_cstr_from_ptr", since = "1.81.0")]
    514    pub const fn count_bytes(&self) -> usize {
    515        self.inner.len() - 1
    516    }
    517
    518    /// Returns `true` if `self.to_bytes()` has a length of 0.
    519    ///
    520    /// # Examples
    521    ///
    522    /// ```
    523    /// assert!(!c"foo".is_empty());
    524    /// assert!(c"".is_empty());
    525    /// ```
    526    #[inline]
    527    #[stable(feature = "cstr_is_empty", since = "1.71.0")]
    528    #[rustc_const_stable(feature = "cstr_is_empty", since = "1.71.0")]
    529    pub const fn is_empty(&self) -> bool {
    530        // SAFETY: We know there is at least one byte; for empty strings it
    531        // is the NUL terminator.
    532        // FIXME(const-hack): use get_unchecked
    533        unsafe { *self.inner.as_ptr() == 0 }
    534    }
    535
    536    /// Converts this C string to a byte slice.
    537    ///
    538    /// The returned slice will **not** contain the trailing nul terminator that this C
    539    /// string has.
    540    ///
    541    /// > **Note**: This method is currently implemented as a constant-time
    542    /// > cast, but it is planned to alter its definition in the future to
    543    /// > perform the length calculation whenever this method is called.
    544    ///
    545    /// # Examples
    546    ///
    547    /// ```
    548    /// assert_eq!(c"foo".to_bytes(), b"foo");
    549    /// ```
    550    #[inline]
    551    #[must_use = "this returns the result of the operation, \
    552                  without modifying the original"]
    553    #[stable(feature = "rust1", since = "1.0.0")]
    554    #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")]
    555    pub const fn to_bytes(&self) -> &[u8] {
    556        let bytes = self.to_bytes_with_nul();
    557        // FIXME(const-hack) replace with range index
    558        // SAFETY: to_bytes_with_nul returns slice with length at least 1
    559        unsafe { slice::from_raw_parts(bytes.as_ptr(), bytes.len() - 1) }
    560    }
    561
    562    /// Converts this C string to a byte slice containing the trailing 0 byte.
    563    ///
    564    /// This function is the equivalent of [`CStr::to_bytes`] except that it
    565    /// will retain the trailing nul terminator instead of chopping it off.
    566    ///
    567    /// > **Note**: This method is currently implemented as a 0-cost cast, but
    568    /// > it is planned to alter its definition in the future to perform the
    569    /// > length calculation whenever this method is called.
    570    ///
    571    /// # Examples
    572    ///
    573    /// ```
    574    /// assert_eq!(c"foo".to_bytes_with_nul(), b"foo\0");
    575    /// ```
    576    #[inline]
    577    #[must_use = "this returns the result of the operation, \
    578                  without modifying the original"]
    579    #[stable(feature = "rust1", since = "1.0.0")]
    580    #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")]
    581    pub const fn to_bytes_with_nul(&self) -> &[u8] {
    582        // SAFETY: Transmuting a slice of `c_char`s to a slice of `u8`s
    583        // is safe on all supported targets.
    584        unsafe { &*((&raw const self.inner) as *const [u8]) }
    585    }
    586
    587    /// Iterates over the bytes in this C string.
    588    ///
    589    /// The returned iterator will **not** contain the trailing nul terminator
    590    /// that this C string has.
    591    ///
    592    /// # Examples
    593    ///
    594    /// ```
    595    /// #![feature(cstr_bytes)]
    596    ///
    597    /// assert!(c"foo".bytes().eq(*b"foo"));
    598    /// ```
    599    #[inline]
    600    #[unstable(feature = "cstr_bytes", issue = "112115")]
    601    pub fn bytes(&self) -> Bytes<'_> {
    602        Bytes::new(self)
    603    }
    604
    605    /// Yields a <code>&[str]</code> slice if the `CStr` contains valid UTF-8.
    606    ///
    607    /// If the contents of the `CStr` are valid UTF-8 data, this
    608    /// function will return the corresponding <code>&[str]</code> slice. Otherwise,
    609    /// it will return an error with details of where UTF-8 validation failed.
    610    ///
    611    /// [str]: prim@str "str"
    612    ///
    613    /// # Examples
    614    ///
    615    /// ```
    616    /// assert_eq!(c"foo".to_str(), Ok("foo"));
    617    /// ```
    618    #[stable(feature = "cstr_to_str", since = "1.4.0")]
    619    #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")]
    620    pub const fn to_str(&self) -> Result<&str, str::Utf8Error> {
    621        // N.B., when `CStr` is changed to perform the length check in `.to_bytes()`
    622        // instead of in `from_ptr()`, it may be worth considering if this should
    623        // be rewritten to do the UTF-8 check inline with the length calculation
    624        // instead of doing it afterwards.
    625        str::from_utf8(self.to_bytes())
    626    }
    627
    628    /// Returns an object that implements [`Display`] for safely printing a [`CStr`] that may
    629    /// contain non-Unicode data.
    630    ///
    631    /// Behaves as if `self` were first lossily converted to a `str`, with invalid UTF-8 presented
    632    /// as the Unicode replacement character: �.
    633    ///
    634    /// [`Display`]: fmt::Display
    635    ///
    636    /// # Examples
    637    ///
    638    /// ```
    639    /// #![feature(cstr_display)]
    640    ///
    641    /// let cstr = c"Hello, world!";
    642    /// println!("{}", cstr.display());
    643    /// ```
    644    #[unstable(feature = "cstr_display", issue = "139984")]
    645    #[must_use = "this does not display the `CStr`; \
    646                  it returns an object that can be displayed"]
    647    #[inline]
    648    pub fn display(&self) -> impl fmt::Display {
    649        crate::bstr::ByteStr::from_bytes(self.to_bytes())
    650    }
    651
    652    /// Returns the same string as a string slice `&CStr`.
    653    ///
    654    /// This method is redundant when used directly on `&CStr`, but
    655    /// it helps dereferencing other string-like types to string slices,
    656    /// for example references to `Box<CStr>` or `Arc<CStr>`.
    657    #[inline]
    658    #[unstable(feature = "str_as_str", issue = "130366")]
    659    pub const fn as_c_str(&self) -> &CStr {
    660        self
    661    }
    662}
    663
    664#[stable(feature = "c_string_eq_c_str", since = "1.90.0")]
    665impl PartialEq<&Self> for CStr {
    666    #[inline]
    667    fn eq(&self, other: &&Self) -> bool {
    668        *self == **other
    669    }
    670
    671    #[inline]
    672    fn ne(&self, other: &&Self) -> bool {
    673        *self != **other
    674    }
    675}
    676
    677// `.to_bytes()` representations are compared instead of the inner `[c_char]`s,
    678// because `c_char` is `i8` (not `u8`) on some platforms.
    679// That is why this is implemented manually and not derived.
    680#[stable(feature = "rust1", since = "1.0.0")]
    681impl PartialOrd for CStr {
    682    #[inline]
    683    fn partial_cmp(&self, other: &CStr) -> Option<Ordering> {
    684        self.to_bytes().partial_cmp(&other.to_bytes())
    685    }
    686}
    687
    688#[stable(feature = "rust1", since = "1.0.0")]
    689impl Ord for CStr {
    690    #[inline]
    691    fn cmp(&self, other: &CStr) -> Ordering {
    692        self.to_bytes().cmp(&other.to_bytes())
    693    }
    694}
    695
    696#[stable(feature = "cstr_range_from", since = "1.47.0")]
    697impl ops::Index<ops::RangeFrom<usize>> for CStr {
    698    type Output = CStr;
    699
    700    #[inline]
    701    fn index(&self, index: ops::RangeFrom<usize>) -> &CStr {
    702        let bytes = self.to_bytes_with_nul();
    703        // we need to manually check the starting index to account for the null
    704        // byte, since otherwise we could get an empty string that doesn't end
    705        // in a null.
    706        if index.start < bytes.len() {
    707            // SAFETY: Non-empty tail of a valid `CStr` is still a valid `CStr`.
    708            unsafe { CStr::from_bytes_with_nul_unchecked(&bytes[index.start..]) }
    709        } else {
    710            panic!(
    711                "index out of bounds: the len is {} but the index is {}",
    712                bytes.len(),
    713                index.start
    714            );
    715        }
    716    }
    717}
    718
    719#[stable(feature = "cstring_asref", since = "1.7.0")]
    720#[rustc_const_unstable(feature = "const_convert", issue = "143773")]
    721impl const AsRef<CStr> for CStr {
    722    #[inline]
    723    fn as_ref(&self) -> &CStr {
    724        self
    725    }
    726}
    727
    728/// Calculate the length of a nul-terminated string. Defers to C's `strlen` when possible.
    729///
    730/// # Safety
    731///
    732/// The pointer must point to a valid buffer that contains a NUL terminator. The NUL must be
    733/// located within `isize::MAX` from `ptr`.
    734#[inline]
    735#[unstable(feature = "cstr_internals", issue = "none")]
    736#[rustc_allow_const_fn_unstable(const_eval_select)]
    737const unsafe fn strlen(ptr: *const c_char) -> usize {
    738    const_eval_select!(
    739        @capture { s: *const c_char = ptr } -> usize:
    740        if const {
    741            let mut len = 0;
    742
    743            // SAFETY: Outer caller has provided a pointer to a valid C string.
    744            while unsafe { *s.add(len) } != 0 {
    745                len += 1;
    746            }
    747
    748            len
    749        } else {
    750            unsafe extern "C" {
    751                /// Provided by libc or compiler_builtins.
    752                fn strlen(s: *const c_char) -> usize;
    753            }
    754
    755            // SAFETY: Outer caller has provided a pointer to a valid C string.
    756            unsafe { strlen(s) }
    757        }
    758    )
    759}
    760
    761/// An iterator over the bytes of a [`CStr`], without the nul terminator.
    762///
    763/// This struct is created by the [`bytes`] method on [`CStr`].
    764/// See its documentation for more.
    765///
    766/// [`bytes`]: CStr::bytes
    767#[must_use = "iterators are lazy and do nothing unless consumed"]
    768#[unstable(feature = "cstr_bytes", issue = "112115")]
    769#[derive(Clone, Debug)]
    770pub struct Bytes<'a> {
    771    // since we know the string is nul-terminated, we only need one pointer
    772    ptr: NonNull<u8>,
    773    phantom: PhantomData<&'a [c_char]>,
    774}
    775
    776#[unstable(feature = "cstr_bytes", issue = "112115")]
    777unsafe impl Send for Bytes<'_> {}
    778
    779#[unstable(feature = "cstr_bytes", issue = "112115")]
    780unsafe impl Sync for Bytes<'_> {}
    781
    782impl<'a> Bytes<'a> {
    783    #[inline]
    784    fn new(s: &'a CStr) -> Self {
    785        Self { ptr: s.as_non_null_ptr().cast(), phantom: PhantomData }
    786    }
    787
    788    #[inline]
    789    fn is_empty(&self) -> bool {
    790        // SAFETY: We uphold that the pointer is always valid to dereference
    791        // by starting with a valid C string and then never incrementing beyond
    792        // the nul terminator.
    793        unsafe { self.ptr.read() == 0 }
    794    }
    795}
    796
    797#[unstable(feature = "cstr_bytes", issue = "112115")]
    798impl Iterator for Bytes<'_> {
    799    type Item = u8;
    800
    801    #[inline]
    802    fn next(&mut self) -> Option<u8> {
    803        // SAFETY: We only choose a pointer from a valid C string, which must
    804        // be non-null and contain at least one value. Since we always stop at
    805        // the nul terminator, which is guaranteed to exist, we can assume that
    806        // the pointer is non-null and valid. This lets us safely dereference
    807        // it and assume that adding 1 will create a new, non-null, valid
    808        // pointer.
    809        unsafe {
    810            let ret = self.ptr.read();
    811            if ret == 0 {
    812                None
    813            } else {
    814                self.ptr = self.ptr.add(1);
    815                Some(ret)
    816            }
    817        }
    818    }
    819
    820    #[inline]
    821    fn size_hint(&self) -> (usize, Option<usize>) {
    822        if self.is_empty() { (0, Some(0)) } else { (1, None) }
    823    }
    824
    825    #[inline]
    826    fn count(self) -> usize {
    827        // SAFETY: We always hold a valid pointer to a C string
    828        unsafe { strlen(self.ptr.as_ptr().cast()) }
    829    }
    830}
    831
    832#[unstable(feature = "cstr_bytes", issue = "112115")]
    833impl FusedIterator for Bytes<'_> {}