library/core/src/ffi/c_str.rs

   1 use crate::cmp::Ordering;
   2 use crate::ffi::c_char;
   3 use crate::fmt;
   4 use crate::intrinsics;
   5 use crate::ops;
   6 use crate::slice;
   7 use crate::slice::memchr;
   8 use crate::str;
   9
  10 /// Representation of a borrowed C string.
  11 ///
  12 /// This type represents a borrowed reference to a nul-terminated
  13 /// array of bytes. It can be constructed safely from a <code>&[[u8]]</code>
  14 /// slice, or unsafely from a raw `*const c_char`. It can then be
  15 /// converted to a Rust <code>&[str]</code> by performing UTF-8 validation, or
  16 /// into an owned `CString`.
  17 ///
  18 /// `&CStr` is to `CString` as <code>&[str]</code> is to `String`: the former
  19 /// in each pair are borrowed references; the latter are owned
  20 /// strings.
  21 ///
  22 /// Note that this structure is **not** `repr(C)` and is not recommended to be
  23 /// placed in the signatures of FFI functions. Instead, safe wrappers of FFI
  24 /// functions may leverage the unsafe [`CStr::from_ptr`] constructor to provide
  25 /// a safe interface to other consumers.
  26 ///
  27 /// # Examples
  28 ///
  29 /// Inspecting a foreign C string:
  30 ///
  31 /// ```ignore (extern-declaration)
  32 /// use std::ffi::CStr;
  33 /// use std::os::raw::c_char;
  34 ///
  35 /// extern "C" { fn my_string() -> *const c_char; }
  36 ///
  37 /// unsafe {
  38 ///     let slice = CStr::from_ptr(my_string());
  39 ///     println!("string buffer size without nul terminator: {}", slice.to_bytes().len());
  40 /// }
  41 /// ```
  42 ///
  43 /// Passing a Rust-originating C string:
  44 ///
  45 /// ```ignore (extern-declaration)
  46 /// use std::ffi::{CString, CStr};
  47 /// use std::os::raw::c_char;
  48 ///
  49 /// fn work(data: &CStr) {
  50 ///     extern "C" { fn work_with(data: *const c_char); }
  51 ///
  52 ///     unsafe { work_with(data.as_ptr()) }
  53 /// }
  54 ///
  55 /// let s = CString::new("data data data data").expect("CString::new failed");
  56 /// work(&s);
  57 /// ```
  58 ///
  59 /// Converting a foreign C string into a Rust `String`:
  60 ///
  61 /// ```ignore (extern-declaration)
  62 /// use std::ffi::CStr;
  63 /// use std::os::raw::c_char;
  64 ///
  65 /// extern "C" { fn my_string() -> *const c_char; }
  66 ///
  67 /// fn my_string_safe() -> String {
  68 ///     let cstr = unsafe { CStr::from_ptr(my_string()) };
  69 ///     // Get copy-on-write Cow<'_, str>, then guarantee a freshly-owned String allocation
  70 ///     String::from_utf8_lossy(cstr.to_bytes()).to_string()
  71 /// }
  72 ///
  73 /// println!("string: {}", my_string_safe());
  74 /// ```
  75 ///
  76 /// [str]: prim@str "str"
  77 #[derive(Hash)]
  78 #[cfg_attr(not(test), rustc_diagnostic_item = "CStr")]
  79 #[stable(feature = "core_c_str", since = "1.64.0")]
  80 #[rustc_has_incoherent_inherent_impls]
  81 // FIXME:
  82 // `fn from` in `impl From<&CStr> for Box<CStr>` current implementation relies
  83 // on `CStr` being layout-compatible with `[u8]`.
  84 // When attribute privacy is implemented, `CStr` should be annotated as `#[repr(transparent)]`.
  85 // Anyway, `CStr` representation and layout are considered implementation detail, are
  86 // not documented and must not be relied upon.
  87 pub struct CStr {
  88     // FIXME: this should not be represented with a DST slice but rather with
  89     //        just a raw `c_char` along with some form of marker to make
  90     //        this an unsized type. Essentially `sizeof(&CStr)` should be the
  91     //        same as `sizeof(&c_char)` but `CStr` should be an unsized type.
  92     inner: [c_char],
  93 }
  94
  95 /// An error indicating that a nul byte was not in the expected position.
  96 ///
  97 /// The slice used to create a [`CStr`] must have one and only one nul byte,
  98 /// positioned at the end.
  99 ///
 100 /// This error is created by the [`CStr::from_bytes_with_nul`] method.
 101 /// See its documentation for more.
 102 ///
 103 /// # Examples
 104 ///
 105 /// ```
 106 /// use std::ffi::{CStr, FromBytesWithNulError};
 107 ///
 108 /// let _: FromBytesWithNulError = CStr::from_bytes_with_nul(b"f\0oo").unwrap_err();
 109 /// ```
 110 #[derive(Clone, PartialEq, Eq, Debug)]
 111 #[stable(feature = "core_c_str", since = "1.64.0")]
 112 pub struct FromBytesWithNulError {
 113     kind: FromBytesWithNulErrorKind,
 114 }
 115
 116 #[derive(Clone, PartialEq, Eq, Debug)]
 117 enum FromBytesWithNulErrorKind {
 118     InteriorNul(usize),
 119     NotNulTerminated,
 120 }
 121
 122 impl FromBytesWithNulError {
 123     const fn interior_nul(pos: usize) -> FromBytesWithNulError {
 124         FromBytesWithNulError { kind: FromBytesWithNulErrorKind::InteriorNul(pos) }
 125     }
 126     const fn not_nul_terminated() -> FromBytesWithNulError {
 127         FromBytesWithNulError { kind: FromBytesWithNulErrorKind::NotNulTerminated }
 128     }
 129
 130     #[doc(hidden)]
 131     #[unstable(feature = "cstr_internals", issue = "none")]
 132     pub fn __description(&self) -> &str {
 133         match self.kind {
 134             FromBytesWithNulErrorKind::InteriorNul(..) => {
 135                 "data provided contains an interior nul byte"
 136             }
 137             FromBytesWithNulErrorKind::NotNulTerminated => "data provided is not nul terminated",
 138         }
 139     }
 140 }
 141
 142 /// An error indicating that no nul byte was present.
 143 ///
 144 /// A slice used to create a [`CStr`] must contain a nul byte somewhere
 145 /// within the slice.
 146 ///
 147 /// This error is created by the [`CStr::from_bytes_until_nul`] method.
 148 ///
 149 #[derive(Clone, PartialEq, Eq, Debug)]
 150 #[unstable(feature = "cstr_from_bytes_until_nul", issue = "95027")]
 151 pub struct FromBytesUntilNulError(());
 152
 153 #[unstable(feature = "cstr_from_bytes_until_nul", issue = "95027")]
 154 impl fmt::Display for FromBytesUntilNulError {
 155     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 156         write!(f, "data provided does not contain a nul")
 157     }
 158 }
 159
 160 #[stable(feature = "cstr_debug", since = "1.3.0")]
 161 impl fmt::Debug for CStr {
 162     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 163         write!(f, "\"{}\"", self.to_bytes().escape_ascii())
 164     }
 165 }
 166
 167 #[stable(feature = "cstr_default", since = "1.10.0")]
 168 impl Default for &CStr {
 169     fn default() -> Self {
 170         const SLICE: &[c_char] = &[0];
 171         // SAFETY: `SLICE` is indeed pointing to a valid nul-terminated string.
 172         unsafe { CStr::from_ptr(SLICE.as_ptr()) }
 173     }
 174 }
 175
 176 #[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")]
 177 impl fmt::Display for FromBytesWithNulError {
 178     #[allow(deprecated, deprecated_in_future)]
 179     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 180         f.write_str(self.__description())?;
 181         if let FromBytesWithNulErrorKind::InteriorNul(pos) = self.kind {
 182             write!(f, " at byte pos {pos}")?;
 183         }
 184         Ok(())
 185     }
 186 }
 187
 188 impl CStr {
 189     /// Wraps a raw C string with a safe C string wrapper.
 190     ///
 191     /// This function will wrap the provided `ptr` with a `CStr` wrapper, which
 192     /// allows inspection and interoperation of non-owned C strings. The total
 193     /// size of the raw C string must be smaller than `isize::MAX` **bytes**
 194     /// in memory due to calling the `slice::from_raw_parts` function.
 195     ///
 196     /// # Safety
 197     ///
 198     /// * The memory pointed to by `ptr` must contain a valid nul terminator at the
 199     ///   end of the string.
 200     ///
 201     /// * `ptr` must be [valid] for reads of bytes up to and including the null terminator.
 202     ///   This means in particular:
 203     ///
 204     ///     * The entire memory range of this `CStr` must be contained within a single allocated object!
 205     ///     * `ptr` must be non-null even for a zero-length cstr.
 206     ///
 207     /// * The memory referenced by the returned `CStr` must not be mutated for
 208     ///   the duration of lifetime `'a`.
 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     /// ```ignore (extern-declaration)
 224     /// # fn main() {
 225     /// use std::ffi::CStr;
 226     /// use std::os::raw::c_char;
 227     ///
 228     /// extern "C" {
 229     ///     fn my_string() -> *const c_char;
 230     /// }
 231     ///
 232     /// unsafe {
 233     ///     let slice = CStr::from_ptr(my_string());
 234     ///     println!("string returned: {}", slice.to_str().unwrap());
 235     /// }
 236     /// # }
 237     /// ```
 238     ///
 239     /// [valid]: core::ptr#safety
 240     #[inline]
 241     #[must_use]
 242     #[stable(feature = "rust1", since = "1.0.0")]
 243     pub unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr {
 244         // SAFETY: The caller has provided a pointer that points to a valid C
 245         // string with a NUL terminator of size less than `isize::MAX`, whose
 246         // content remain valid and doesn't change for the lifetime of the
 247         // returned `CStr`.
 248         //
 249         // Thus computing the length is fine (a NUL byte exists), the call to
 250         // from_raw_parts is safe because we know the length is at most `isize::MAX`, meaning
 251         // the call to `from_bytes_with_nul_unchecked` is correct.
 252         //
 253         // The cast from c_char to u8 is ok because a c_char is always one byte.
 254         unsafe {
 255             extern "C" {
 256                 /// Provided by libc or compiler_builtins.
 257                 fn strlen(s: *const c_char) -> usize;
 258             }
 259             let len = strlen(ptr);
 260             let ptr = ptr as *const u8;
 261             CStr::from_bytes_with_nul_unchecked(slice::from_raw_parts(ptr, len as usize + 1))
 262         }
 263     }
 264
 265     /// Creates a C string wrapper from a byte slice.
 266     ///
 267     /// This method will create a `CStr` from any byte slice that contains at
 268     /// least one nul byte. The caller does not need to know or specify where
 269     /// the nul byte is located.
 270     ///
 271     /// If the first byte is a nul character, this method will return an
 272     /// empty `CStr`. If multiple nul characters are present, the `CStr` will
 273     /// end at the first one.
 274     ///
 275     /// If the slice only has a single nul byte at the end, this method is
 276     /// equivalent to [`CStr::from_bytes_with_nul`].
 277     ///
 278     /// # Examples
 279     /// ```
 280     /// #![feature(cstr_from_bytes_until_nul)]
 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     #[unstable(feature = "cstr_from_bytes_until_nul", issue = "95027")]
 297     #[rustc_const_unstable(feature = "cstr_from_bytes_until_nul", issue = "95027")]
 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                 let subslice = &bytes[..nul_pos + 1];
 303                 // SAFETY: We know there is a nul byte at nul_pos, so this slice
 304                 // (ending at the nul byte) is a well-formed C string.
 305                 Ok(unsafe { CStr::from_bytes_with_nul_unchecked(subslice) })
 306             }
 307             None => Err(FromBytesUntilNulError(())),
 308         }
 309     }
 310
 311     /// Creates a C string wrapper from a byte slice.
 312     ///
 313     /// This function will cast the provided `bytes` to a `CStr`
 314     /// wrapper after ensuring that the byte slice is nul-terminated
 315     /// and does not contain any interior nul bytes.
 316     ///
 317     /// If the nul byte may not be at the end,
 318     /// [`CStr::from_bytes_until_nul`] can be used instead.
 319     ///
 320     /// # Examples
 321     ///
 322     /// ```
 323     /// use std::ffi::CStr;
 324     ///
 325     /// let cstr = CStr::from_bytes_with_nul(b"hello\0");
 326     /// assert!(cstr.is_ok());
 327     /// ```
 328     ///
 329     /// Creating a `CStr` without a trailing nul terminator is an error:
 330     ///
 331     /// ```
 332     /// use std::ffi::CStr;
 333     ///
 334     /// let cstr = CStr::from_bytes_with_nul(b"hello");
 335     /// assert!(cstr.is_err());
 336     /// ```
 337     ///
 338     /// Creating a `CStr` with an interior nul byte is an error:
 339     ///
 340     /// ```
 341     /// use std::ffi::CStr;
 342     ///
 343     /// let cstr = CStr::from_bytes_with_nul(b"he\0llo\0");
 344     /// assert!(cstr.is_err());
 345     /// ```
 346     #[stable(feature = "cstr_from_bytes", since = "1.10.0")]
 347     #[rustc_const_unstable(feature = "const_cstr_methods", issue = "101719")]
 348     pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, FromBytesWithNulError> {
 349         let nul_pos = memchr::memchr(0, bytes);
 350         match nul_pos {
 351             Some(nul_pos) if nul_pos + 1 == bytes.len() => {
 352                 // SAFETY: We know there is only one nul byte, at the end
 353                 // of the byte slice.
 354                 Ok(unsafe { Self::from_bytes_with_nul_unchecked(bytes) })
 355             }
 356             Some(nul_pos) => Err(FromBytesWithNulError::interior_nul(nul_pos)),
 357             None => Err(FromBytesWithNulError::not_nul_terminated()),
 358         }
 359     }
 360
 361     /// Unsafely creates a C string wrapper from a byte slice.
 362     ///
 363     /// This function will cast the provided `bytes` to a `CStr` wrapper without
 364     /// performing any sanity checks.
 365     ///
 366     /// # Safety
 367     /// The provided slice **must** be nul-terminated and not contain any interior
 368     /// nul bytes.
 369     ///
 370     /// # Examples
 371     ///
 372     /// ```
 373     /// use std::ffi::{CStr, CString};
 374     ///
 375     /// unsafe {
 376     ///     let cstring = CString::new("hello").expect("CString::new failed");
 377     ///     let cstr = CStr::from_bytes_with_nul_unchecked(cstring.to_bytes_with_nul());
 378     ///     assert_eq!(cstr, &*cstring);
 379     /// }
 380     /// ```
 381     #[inline]
 382     #[must_use]
 383     #[stable(feature = "cstr_from_bytes", since = "1.10.0")]
 384     #[rustc_const_stable(feature = "const_cstr_unchecked", since = "1.59.0")]
 385     #[rustc_allow_const_fn_unstable(const_eval_select)]
 386     pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr {
 387         #[inline]
 388         fn rt_impl(bytes: &[u8]) -> &CStr {
 389             // Chance at catching some UB at runtime with debug builds.
 390             debug_assert!(!bytes.is_empty() && bytes[bytes.len() - 1] == 0);
 391
 392             // SAFETY: Casting to CStr is safe because its internal representation
 393             // is a [u8] too (safe only inside std).
 394             // Dereferencing the obtained pointer is safe because it comes from a
 395             // reference. Making a reference is then safe because its lifetime
 396             // is bound by the lifetime of the given `bytes`.
 397             unsafe { &*(bytes as *const [u8] as *const CStr) }
 398         }
 399
 400         const fn const_impl(bytes: &[u8]) -> &CStr {
 401             // Saturating so that an empty slice panics in the assert with a good
 402             // message, not here due to underflow.
 403             let mut i = bytes.len().saturating_sub(1);
 404             assert!(!bytes.is_empty() && bytes[i] == 0, "input was not nul-terminated");
 405
 406             // Ending null byte exists, skip to the rest.
 407             while i != 0 {
 408                 i -= 1;
 409                 let byte = bytes[i];
 410                 assert!(byte != 0, "input contained interior nul");
 411             }
 412
 413             // SAFETY: See `rt_impl` cast.
 414             unsafe { &*(bytes as *const [u8] as *const CStr) }
 415         }
 416
 417         // SAFETY: The const and runtime versions have identical behavior
 418         // unless the safety contract of `from_bytes_with_nul_unchecked` is
 419         // violated, which is UB.
 420         unsafe { intrinsics::const_eval_select((bytes,), const_impl, rt_impl) }
 421     }
 422
 423     /// Returns the inner pointer to this C string.
 424     ///
 425     /// The returned pointer will be valid for as long as `self` is, and points
 426     /// to a contiguous region of memory terminated with a 0 byte to represent
 427     /// the end of the string.
 428     ///
 429     /// **WARNING**
 430     ///
 431     /// The returned pointer is read-only; writing to it (including passing it
 432     /// to C code that writes to it) causes undefined behavior.
 433     ///
 434     /// It is your responsibility to make sure that the underlying memory is not
 435     /// freed too early. For example, the following code will cause undefined
 436     /// behavior when `ptr` is used inside the `unsafe` block:
 437     ///
 438     /// ```no_run
 439     /// # #![allow(unused_must_use)] #![allow(temporary_cstring_as_ptr)]
 440     /// use std::ffi::CString;
 441     ///
 442     /// let ptr = CString::new("Hello").expect("CString::new failed").as_ptr();
 443     /// unsafe {
 444     ///     // `ptr` is dangling
 445     ///     *ptr;
 446     /// }
 447     /// ```
 448     ///
 449     /// This happens because the pointer returned by `as_ptr` does not carry any
 450     /// lifetime information and the `CString` is deallocated immediately after
 451     /// the `CString::new("Hello").expect("CString::new failed").as_ptr()`
 452     /// expression is evaluated.
 453     /// To fix the problem, bind the `CString` to a local variable:
 454     ///
 455     /// ```no_run
 456     /// # #![allow(unused_must_use)]
 457     /// use std::ffi::CString;
 458     ///
 459     /// let hello = CString::new("Hello").expect("CString::new failed");
 460     /// let ptr = hello.as_ptr();
 461     /// unsafe {
 462     ///     // `ptr` is valid because `hello` is in scope
 463     ///     *ptr;
 464     /// }
 465     /// ```
 466     ///
 467     /// This way, the lifetime of the `CString` in `hello` encompasses
 468     /// the lifetime of `ptr` and the `unsafe` block.
 469     #[inline]
 470     #[must_use]
 471     #[stable(feature = "rust1", since = "1.0.0")]
 472     #[rustc_const_stable(feature = "const_str_as_ptr", since = "1.32.0")]
 473     pub const fn as_ptr(&self) -> *const c_char {
 474         self.inner.as_ptr()
 475     }
 476
 477     /// Converts this C string to a byte slice.
 478     ///
 479     /// The returned slice will **not** contain the trailing nul terminator that this C
 480     /// string has.
 481     ///
 482     /// > **Note**: This method is currently implemented as a constant-time
 483     /// > cast, but it is planned to alter its definition in the future to
 484     /// > perform the length calculation whenever this method is called.
 485     ///
 486     /// # Examples
 487     ///
 488     /// ```
 489     /// use std::ffi::CStr;
 490     ///
 491     /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed");
 492     /// assert_eq!(cstr.to_bytes(), b"foo");
 493     /// ```
 494     #[inline]
 495     #[must_use = "this returns the result of the operation, \
 496                   without modifying the original"]
 497     #[stable(feature = "rust1", since = "1.0.0")]
 498     #[rustc_const_unstable(feature = "const_cstr_methods", issue = "101719")]
 499     pub const fn to_bytes(&self) -> &[u8] {
 500         let bytes = self.to_bytes_with_nul();
 501         // SAFETY: to_bytes_with_nul returns slice with length at least 1
 502         unsafe { bytes.get_unchecked(..bytes.len() - 1) }
 503     }
 504
 505     /// Converts this C string to a byte slice containing the trailing 0 byte.
 506     ///
 507     /// This function is the equivalent of [`CStr::to_bytes`] except that it
 508     /// will retain the trailing nul terminator instead of chopping it off.
 509     ///
 510     /// > **Note**: This method is currently implemented as a 0-cost cast, but
 511     /// > it is planned to alter its definition in the future to perform the
 512     /// > length calculation whenever this method is called.
 513     ///
 514     /// # Examples
 515     ///
 516     /// ```
 517     /// use std::ffi::CStr;
 518     ///
 519     /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed");
 520     /// assert_eq!(cstr.to_bytes_with_nul(), b"foo\0");
 521     /// ```
 522     #[inline]
 523     #[must_use = "this returns the result of the operation, \
 524                   without modifying the original"]
 525     #[stable(feature = "rust1", since = "1.0.0")]
 526     #[rustc_const_unstable(feature = "const_cstr_methods", issue = "101719")]
 527     pub const fn to_bytes_with_nul(&self) -> &[u8] {
 528         // SAFETY: Transmuting a slice of `c_char`s to a slice of `u8`s
 529         // is safe on all supported targets.
 530         unsafe { &*(&self.inner as *const [c_char] as *const [u8]) }
 531     }
 532
 533     /// Yields a <code>&[str]</code> slice if the `CStr` contains valid UTF-8.
 534     ///
 535     /// If the contents of the `CStr` are valid UTF-8 data, this
 536     /// function will return the corresponding <code>&[str]</code> slice. Otherwise,
 537     /// it will return an error with details of where UTF-8 validation failed.
 538     ///
 539     /// [str]: prim@str "str"
 540     ///
 541     /// # Examples
 542     ///
 543     /// ```
 544     /// use std::ffi::CStr;
 545     ///
 546     /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed");
 547     /// assert_eq!(cstr.to_str(), Ok("foo"));
 548     /// ```
 549     #[stable(feature = "cstr_to_str", since = "1.4.0")]
 550     #[rustc_const_unstable(feature = "const_cstr_methods", issue = "101719")]
 551     pub const fn to_str(&self) -> Result<&str, str::Utf8Error> {
 552         // N.B., when `CStr` is changed to perform the length check in `.to_bytes()`
 553         // instead of in `from_ptr()`, it may be worth considering if this should
 554         // be rewritten to do the UTF-8 check inline with the length calculation
 555         // instead of doing it afterwards.
 556         str::from_utf8(self.to_bytes())
 557     }
 558 }
 559
 560 #[stable(feature = "rust1", since = "1.0.0")]
 561 impl PartialEq for CStr {
 562     fn eq(&self, other: &CStr) -> bool {
 563         self.to_bytes().eq(other.to_bytes())
 564     }
 565 }
 566 #[stable(feature = "rust1", since = "1.0.0")]
 567 impl Eq for CStr {}
 568 #[stable(feature = "rust1", since = "1.0.0")]
 569 impl PartialOrd for CStr {
 570     fn partial_cmp(&self, other: &CStr) -> Option<Ordering> {
 571         self.to_bytes().partial_cmp(&other.to_bytes())
 572     }
 573 }
 574 #[stable(feature = "rust1", since = "1.0.0")]
 575 impl Ord for CStr {
 576     fn cmp(&self, other: &CStr) -> Ordering {
 577         self.to_bytes().cmp(&other.to_bytes())
 578     }
 579 }
 580
 581 #[stable(feature = "cstr_range_from", since = "1.47.0")]
 582 impl ops::Index<ops::RangeFrom<usize>> for CStr {
 583     type Output = CStr;
 584
 585     fn index(&self, index: ops::RangeFrom<usize>) -> &CStr {
 586         let bytes = self.to_bytes_with_nul();
 587         // we need to manually check the starting index to account for the null
 588         // byte, since otherwise we could get an empty string that doesn't end
 589         // in a null.
 590         if index.start < bytes.len() {
 591             // SAFETY: Non-empty tail of a valid `CStr` is still a valid `CStr`.
 592             unsafe { CStr::from_bytes_with_nul_unchecked(&bytes[index.start..]) }
 593         } else {
 594             panic!(
 595                 "index out of bounds: the len is {} but the index is {}",
 596                 bytes.len(),
 597                 index.start
 598             );
 599         }
 600     }
 601 }
 602
 603 #[stable(feature = "cstring_asref", since = "1.7.0")]
 604 impl AsRef<CStr> for CStr {
 605     #[inline]
 606     fn as_ref(&self) -> &CStr {
 607         self
 608     }
 609 }