#[cfg(test)]
mod tests;

use crate::borrow::{Cow, ToOwned};
use crate::boxed::Box;
use crate::rc::Rc;
use crate::slice::hack::into_vec;
use crate::string::String;
use crate::vec::Vec;
use core::borrow::Borrow;
use core::ffi::{c_char, CStr};
use core::fmt;
use core::mem;
use core::num::NonZeroU8;
use core::ops;
use core::ptr;
use core::slice;
use core::slice::memchr;
use core::str::{self, Utf8Error};

#[cfg(target_has_atomic = "ptr")]
use crate::sync::Arc;

/// 一种类型，表示拥有的，C 兼容的，以 nul 终止的字符串，中间没有 nul 字节。
///
/// 此类型的目的是能够从 Rust 字节切片或 vector 安全地生成 C 兼容字符串。
/// 此类型的一个实例是静态保证，底层字节不包含内部 0 字节 (`nul 字符`)，并且最后一个字节为 0 (`nul 终止符`)。
///
/// `CString` 到 <code>&[CStr]</code> 如同 [`String`] 到 <code>&[str]</code>: 每对中的前者是拥有所有权的字符串； 后者是借用的。
///
/// # 创建一个 `CString`
///
/// `CString` 是从字节切片、字节 vector 或任何实现 <code>[Into]<[Vec]<[u8]>></code> 创建的 (例如，您可以直接从 [`String`] 或 <code>&[str]</code>，因为两者都实现了该 trait)。
///
///
/// [`CString::new`] 方法实际上会检查提供的 <code>&[[u8]]</code> 中是否没有 0 个字节，如果找到一个，将返回一个错误。
///
/// # 将裸指针提取到整个 C 字符串
///
/// `CString` 通过 [`Deref`] trait 实现了一个 [`as_ptr`][`CStr::as_ptr`] 方法。此方法将为您提供 `*const c_char`，您可以直接将其输入期望包含以 N 结束的字符串的 extern 函数，例如 C 的 `strdup()`。
/// 注意，[`as_ptr`][`CStr::as_ptr`] 返回一个只读指针。如果 C 代码写入它，则会导致未定义的行为。
///
/// # 提取整个 C 字符串的切片
///
/// 或者，您可以使用 [`CString::as_bytes`] 方法从 `CString` 获取 <code>&[[u8]]</code> 切片。以这种方式产生的切片不包含尾随 nul 终止符。
/// 当您要调用带有 `*const u8` 参数 (不一定是 nul 终止) 的 extern 函数，以及带有字符串长度的另一个参数 (如 C 的 `strndup()`) 时，此功能很有用。
/// 当然，您可以使用 [`len`][slice::len] 方法获取切片的长度。
///
/// 如果您需要一个带 nul 终止符的 <code>&[[u8]]</code> 切片，您可以使用 [`CString::as_bytes_with_nul`] 代替。
///
/// 一旦有了所需的切片类型 (带或不带 nul 终止符)，就可以调用切片自己的 [`as_ptr`][slice::as_ptr] 方法来获取只读的裸指针，以将其传递给 extern 函数。
/// 有关确保裸指针的生命周期的讨论，请参见该函数的文档。
///
/// [str]: prim@str "str"
/// [`Deref`]: ops::Deref
///
/// # Examples
///
/// ```ignore (extern-declaration)
/// # fn main() {
/// use std::ffi::CString;
/// use std::os::raw::c_char;
///
/// extern "C" {
///     fn my_printer(s: *const c_char);
/// }
///
/// // 我们确定我们的字符串中间没有 0 个字节，因此我们可以 .expect()
/////
/// let c_to_print = CString::new("Hello, world!").expect("CString::new failed");
/// unsafe {
///     my_printer(c_to_print.as_ptr());
/// }
/// # }
/// ```
///
/// # Safety
///
/// `CString` 旨在处理传统的 C 样式字符串 (由单个空字节终止的非空字节序列) ； 这些类型的字符串的主要用例是与类似 C 的代码进行互操作。
/// 通常，您将需要转让该外部代码的所有权 to/from。
/// 强烈建议您在使用 `CString` 之前通读 `CString` 文档，因为对 `CString` 实例的所有权管理不当会导致无效的内存访问，内存泄漏和其他内存错误。
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)]
#[cfg_attr(not(test), rustc_diagnostic_item = "cstring_type")]
#[stable(feature = "alloc_c_string", since = "1.64.0")]
pub struct CString {
    // 不变量 1: 切片以零字节结尾，长度至少为一。
    // 不变量 2: 切片仅包含一个零字节。
    // unsafe 函数使用不当会破坏 Invariant 2，但不会破坏 Invariant 1.
    inner: Box<[u8]>,
}

/// 指示发现内部 nul 字节的错误。
///
/// 尽管 Rust 字符串的中间可能包含 nul 个字节，但 C 字符串却不能，因为该字节会有效地截断该字符串。
///
///
/// 该错误是由 [`CString`] 上的 [`new`][`CString::new`] 方法创建的。有关更多信息，请参见其文档。
///
/// # Examples
///
/// ```
/// use std::ffi::{CString, NulError};
///
/// let _: NulError = CString::new(b"f\0oo".to_vec()).unwrap_err();
/// ```
///
#[derive(Clone, PartialEq, Eq, Debug)]
#[stable(feature = "alloc_c_string", since = "1.64.0")]
pub struct NulError(usize, Vec<u8>);

#[derive(Clone, PartialEq, Eq, Debug)]
enum FromBytesWithNulErrorKind {
    InteriorNul(usize),
    NotNulTerminated,
}

/// 指示 nul 字节不在预期位置中的错误。
///
/// 用于创建 [`CString`] 的 vector 的末尾必须只有一个 nul 字节。
///
///
/// 此错误是由 [`CString::from_vec_with_nul`] 方法创建的。
/// 有关更多信息，请参见其文档。
///
/// # Examples
///
/// ```
/// use std::ffi::{CString, FromVecWithNulError};
///
/// let _: FromVecWithNulError = CString::from_vec_with_nul(b"f\0oo".to_vec()).unwrap_err();
/// ```
#[derive(Clone, PartialEq, Eq, Debug)]
#[stable(feature = "alloc_c_string", since = "1.64.0")]
pub struct FromVecWithNulError {
    error_kind: FromBytesWithNulErrorKind,
    bytes: Vec<u8>,
}

#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
impl FromVecWithNulError {
    /// 返回试图转换为 [`CString`] 的 [u8] 个字节的切片。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// // vector 中的一些无效字节
    /// let bytes = b"f\0oo".to_vec();
    ///
    /// let value = CString::from_vec_with_nul(bytes.clone());
    ///
    /// assert_eq!(&bytes[..], value.unwrap_err().as_bytes());
    /// ```
    #[must_use]
    #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
    pub fn as_bytes(&self) -> &[u8] {
        &self.bytes[..]
    }

    /// 返回尝试转换为 [`CString`] 的字节。
    ///
    /// 精心构造此方法以避免分配。
    /// 它将消耗错误，将字节移出，因此不需要制作字节的副本。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// // vector 中的一些无效字节
    /// let bytes = b"f\0oo".to_vec();
    ///
    /// let value = CString::from_vec_with_nul(bytes.clone());
    ///
    /// assert_eq!(bytes, value.unwrap_err().into_bytes());
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
    pub fn into_bytes(self) -> Vec<u8> {
        self.bytes
    }
}

/// 将 [`CString`] 转换为 [`String`] 时，指示 UTF-8 无效的错误。
///
/// `CString` 只是一个带有 nul 终止符的字节缓冲区的包装器；
/// [`CString::into_string`] 对这些字节执行 UTF-8 验证，并可能返回此错误。
///
///
/// 该 `struct` 由 [`CString::into_string()`] 创建。有关更多信息，请参见其文档。
///
#[derive(Clone, PartialEq, Eq, Debug)]
#[stable(feature = "alloc_c_string", since = "1.64.0")]
pub struct IntoStringError {
    inner: CString,
    error: Utf8Error,
}

impl CString {
    /// 从字节容器创建一个新的 C 兼容字符串。
    ///
    /// 此函数将消费提供的数据，并使用底层字节构建新的字符串，从而确保有一个尾随的 0 字节。
    ///
    /// 这个函数将追加这个尾随的 0 字节； 提供的数据不应包含任何 0 字节。
    ///
    /// # Examples
    ///
    /// ```ignore (extern-declaration)
    /// use std::ffi::CString;
    /// use std::os::raw::c_char;
    ///
    /// extern "C" { fn puts(s: *const c_char); }
    ///
    /// let to_print = CString::new("Hello!").expect("CString::new failed");
    /// unsafe {
    ///     puts(to_print.as_ptr());
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// 如果提供的字节包含内部 0 字节，则此函数将返回错误。
    /// 返回的 [`NulError`] 将包含字节以及 nul 字节的位置。
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn new<T: Into<Vec<u8>>>(t: T) -> Result<CString, NulError> {
        trait SpecNewImpl {
            fn spec_new_impl(self) -> Result<CString, NulError>;
        }

        impl<T: Into<Vec<u8>>> SpecNewImpl for T {
            default fn spec_new_impl(self) -> Result<CString, NulError> {
                let bytes: Vec<u8> = self.into();
                match memchr::memchr(0, &bytes) {
                    Some(i) => Err(NulError(i, bytes)),
                    None => Ok(unsafe { CString::_from_vec_unchecked(bytes) }),
                }
            }
        }

        // 避免重新分配的专门化
        #[inline(always)] // 没有它，就不能内联到专门化中
        fn spec_new_impl_bytes(bytes: &[u8]) -> Result<CString, NulError> {
            // 我们不能有这么大的切片，我们会在这里溢出，但使用 `checked_add` 允许 LLVM 假设容量永远不会溢出，并生成两倍短的代码。
            //
            // `saturating_add` 由于某种原因，没有帮助。
            //
            let capacity = bytes.len().checked_add(1).unwrap();

            // 在验证之前分配，以避免重复分配代码。
            // 即使出现错误，我们仍然需要分配和复制内存。
            let mut buffer = Vec::with_capacity(capacity);
            buffer.extend(bytes);

            // 检查 self 的内存而不是新的缓冲区。
            // 如果启用 lto，这将允许更好的优化。
            match memchr::memchr(0, bytes) {
                Some(i) => Err(NulError(i, buffer)),
                None => Ok(unsafe { CString::_from_vec_unchecked(buffer) }),
            }
        }

        impl SpecNewImpl for &'_ [u8] {
            fn spec_new_impl(self) -> Result<CString, NulError> {
                spec_new_impl_bytes(self)
            }
        }

        impl SpecNewImpl for &'_ str {
            fn spec_new_impl(self) -> Result<CString, NulError> {
                spec_new_impl_bytes(self.as_bytes())
            }
        }

        impl SpecNewImpl for &'_ mut [u8] {
            fn spec_new_impl(self) -> Result<CString, NulError> {
                spec_new_impl_bytes(self)
            }
        }

        t.spec_new_impl()
    }

    /// 通过使用字节 vector 来创建 C 兼容字符串，而无需检查内部 0 字节。
    ///
    /// 该函数将追加尾随的 0 字节。
    ///
    /// 此方法等效于 [`CString::new`]，除了不进行运行时断言，即 `v` 不包含 0 字节，并且它需要实际的字节 vector，而不是可以使用 Into 转换为 1 的任何内容。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let raw = b"foo".to_vec();
    /// unsafe {
    ///     let c_string = CString::from_vec_unchecked(raw);
    /// }
    /// ```
    ///
    ///
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub unsafe fn from_vec_unchecked(v: Vec<u8>) -> Self {
        debug_assert!(memchr::memchr(0, &v).is_none());
        unsafe { Self::_from_vec_unchecked(v) }
    }

    unsafe fn _from_vec_unchecked(mut v: Vec<u8>) -> Self {
        v.reserve_exact(1);
        v.push(0);
        Self { inner: v.into_boxed_slice() }
    }

    /// 重新获得通过 [`CString::into_raw`] 转移到 C 的 `CString` 的所有权。
    ///
    /// 此外，将根据指针重新计算字符串的长度。
    ///
    /// # Safety
    ///
    /// 仅应使用先前通过调用 [`CString::into_raw`] 获得的指针进行调用。
    /// 其他用法 (例如，尝试获取由外部代码分配的字符串的所有权) 可能导致未定义的行为或分配器损坏。
    ///
    /// 应该注意的是，长度不仅是 "recomputed,"，而且重新计算的长度必须与 [`CString::into_raw`] 调用的原始长度匹配。
    ///
    /// 这意味着在将字符串传递到可以修改字符串长度的 C 函数时，不应使用 [`CString::into_raw`]/`from_raw` 方法。
    ///
    /// > **Note:** 如果您需要借用由分配的字符串
    /// > 外部代码，请使用 [`CStr`]。如果您需要获得所有权从
    /// > 由外部代码分配的字符串，您将需要
    /// > 制定自己的规定以适当地，可能地释放它
    /// > 使用外部代码的 API 来做到这一点。
    ///
    /// # Examples
    ///
    /// 创建一个 `CString`，将所有权传递给 `extern` 函数 (通过裸指针)，然后使用 `from_raw` 重新获得所有权：
    ///
    /// ```ignore (extern-declaration)
    /// use std::ffi::CString;
    /// use std::os::raw::c_char;
    ///
    /// extern "C" {
    ///     fn some_extern_function(s: *mut c_char);
    /// }
    ///
    /// let c_string = CString::new("Hello!").expect("CString::new failed");
    /// let raw = c_string.into_raw();
    /// unsafe {
    ///     some_extern_function(raw);
    ///     let c_string = CString::from_raw(raw);
    /// }
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[must_use = "call `drop(from_raw(ptr))` if you intend to drop the `CString`"]
    #[stable(feature = "cstr_memory", since = "1.4.0")]
    pub unsafe fn from_raw(ptr: *mut c_char) -> CString {
        // SAFETY: 这是通过从 `CString::into_raw` 调用获得的指针来调用的，并且长度没有被修改。
        // 因此，我们知道在末尾有一个 NUL 字节 (只有一个)，并且有关分配大小的信息在 Rust 侧是正确的。
        //
        //
        //
        unsafe {
            extern "C" {
                /// 由 libc 或 compiler_builtins 提供。
                fn strlen(s: *const c_char) -> usize;
            }
            let len = strlen(ptr) + 1; // 包括 NUL 字节
            let slice = slice::from_raw_parts_mut(ptr, len as usize);
            CString { inner: Box::from_raw(slice as *mut [c_char] as *mut [u8]) }
        }
    }

    /// 消耗 `CString`，并将字符串的所有权转让给 C 调用者。
    ///
    /// 此函数返回的指针必须返回到 Rust，并使用 [`CString::from_raw`] 进行重构以正确释放。
    /// 具体来说，应该 *不要* 使用标准的 C `free()` 函数来释放该字符串。
    ///
    /// 未能调用 [`CString::from_raw`] 将导致内存泄漏。
    ///
    /// C 端必须**不**修改字符串的长度 (通过在字符串内某处写入 `null` 或删除最后一个)，然后使用 [`CString::from_raw`] 将其返回到 Rust。
    ///
    /// 请参见 [`CString::from_raw`] 中的安全性部分。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let c_string = CString::new("foo").expect("CString::new failed");
    ///
    /// let ptr = c_string.into_raw();
    ///
    /// unsafe {
    ///     assert_eq!(b'f', *ptr as u8);
    ///     assert_eq!(b'o', *ptr.add(1) as u8);
    ///     assert_eq!(b'o', *ptr.add(2) as u8);
    ///     assert_eq!(b'\0', *ptr.add(3) as u8);
    ///
    ///     // 重新获得指向空闲内存的指针
    ///     let _ = CString::from_raw(ptr);
    /// }
    /// ```
    ///
    ///
    ///
    #[inline]
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "cstr_memory", since = "1.4.0")]
    pub fn into_raw(self) -> *mut c_char {
        Box::into_raw(self.into_inner()) as *mut c_char
    }

    /// 如果 `CString` 包含有效的 UTF-8 数据，则将其转换为 [`String`]。
    ///
    /// 失败时，将返回原始 `CString` 的所有权。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let valid_utf8 = vec![b'f', b'o', b'o'];
    /// let cstring = CString::new(valid_utf8).expect("CString::new failed");
    /// assert_eq!(cstring.into_string().expect("into_string() call failed"), "foo");
    ///
    /// let invalid_utf8 = vec![b'f', 0xff, b'o', b'o'];
    /// let cstring = CString::new(invalid_utf8).expect("CString::new failed");
    /// let err = cstring.into_string().err().expect("into_string().err() failed");
    /// assert_eq!(err.utf8_error().valid_up_to(), 1);
    /// ```
    #[stable(feature = "cstring_into", since = "1.7.0")]
    pub fn into_string(self) -> Result<String, IntoStringError> {
        String::from_utf8(self.into_bytes()).map_err(|e| IntoStringError {
            error: e.utf8_error(),
            inner: unsafe { Self::_from_vec_unchecked(e.into_bytes()) },
        })
    }

    /// 消耗 `CString` 并返回底层的字节缓冲区。
    ///
    /// 返回的缓冲区不包含尾随 nul 终止符，并且保证不包含任何内部 nul 字节。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let c_string = CString::new("foo").expect("CString::new failed");
    /// let bytes = c_string.into_bytes();
    /// assert_eq!(bytes, vec![b'f', b'o', b'o']);
    /// ```
    ///
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "cstring_into", since = "1.7.0")]
    pub fn into_bytes(self) -> Vec<u8> {
        let mut vec = into_vec(self.into_inner());
        let _nul = vec.pop();
        debug_assert_eq!(_nul, Some(0u8));
        vec
    }

    /// 等效于 [`CString::into_bytes()`]，除了返回的 vector 包括结尾的 nul 终止符。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let c_string = CString::new("foo").expect("CString::new failed");
    /// let bytes = c_string.into_bytes_with_nul();
    /// assert_eq!(bytes, vec![b'f', b'o', b'o', b'\0']);
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "cstring_into", since = "1.7.0")]
    pub fn into_bytes_with_nul(self) -> Vec<u8> {
        into_vec(self.into_inner())
    }

    /// 以字节片形式返回此 `CString` 的内容。
    ///
    /// 返回的切片不包含尾随 nul 终止符，并且保证不包含任何内部 nul 字节。
    /// 如果需要 nul 终止符，请改用 [`CString::as_bytes_with_nul`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let c_string = CString::new("foo").expect("CString::new failed");
    /// let bytes = c_string.as_bytes();
    /// assert_eq!(bytes, &[b'f', b'o', b'o']);
    /// ```
    ///
    ///
    #[inline]
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn as_bytes(&self) -> &[u8] {
        // SAFETY: CString 的长度至少为 1
        unsafe { self.inner.get_unchecked(..self.inner.len() - 1) }
    }

    /// 等效于 [`CString::as_bytes()`]，但返回的切片包括结尾的 nul 终止符。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let c_string = CString::new("foo").expect("CString::new failed");
    /// let bytes = c_string.as_bytes_with_nul();
    /// assert_eq!(bytes, &[b'f', b'o', b'o', b'\0']);
    /// ```
    #[inline]
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn as_bytes_with_nul(&self) -> &[u8] {
        &self.inner
    }

    /// 提取包含整个字符串的 [`CStr`] 切片。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::{CString, CStr};
    ///
    /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed");
    /// let cstr = c_string.as_c_str();
    /// assert_eq!(cstr,
    ///            CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"));
    /// ```
    #[inline]
    #[must_use]
    #[stable(feature = "as_c_str", since = "1.20.0")]
    pub fn as_c_str(&self) -> &CStr {
        &*self
    }

    /// 将此 `CString` 转换为 boxed [`CStr`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::{CString, CStr};
    ///
    /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed");
    /// let boxed = c_string.into_boxed_c_str();
    /// assert_eq!(&*boxed,
    ///            CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"));
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "into_boxed_c_str", since = "1.20.0")]
    pub fn into_boxed_c_str(self) -> Box<CStr> {
        unsafe { Box::from_raw(Box::into_raw(self.into_inner()) as *mut CStr) }
    }

    /// 绕过 "move out of struct which implements [`Drop`] trait" 的限制。
    #[inline]
    fn into_inner(self) -> Box<[u8]> {
        // 理由: `mem::forget(self)` 使对 `ptr::read(&self.inner)` 的先前调用无效，因此我们使用 `ManuallyDrop` 来确保不删除 `self`。
        //
        // 然后我们可以直接返回 box 而不会使其无效。请参见 https://github.com/rust-lang/rust/issues/62553。
        //
        let this = mem::ManuallyDrop::new(self);
        unsafe { ptr::read(&this.inner) }
    }

    /// 将 <code>[Vec]<[u8]></code> 转换为 [`CString`]，而不检查给定的 [`Vec`] 上的不变量。
    ///
    ///
    /// # Safety
    ///
    /// 给定的 [`Vec`] 必须最后一个元素为一个 nul 字节。
    /// 这意味着它不能为空，也不能在其他任何地方有任何其他 nul 字节。
    ///
    /// # Example
    ///
    /// ```
    /// use std::ffi::CString;
    /// assert_eq!(
    ///     unsafe { CString::from_vec_with_nul_unchecked(b"abc\0".to_vec()) },
    ///     unsafe { CString::from_vec_unchecked(b"abc".to_vec()) }
    /// );
    /// ```
    #[must_use]
    #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
    pub unsafe fn from_vec_with_nul_unchecked(v: Vec<u8>) -> Self {
        debug_assert!(memchr::memchr(0, &v).unwrap() + 1 == v.len());
        unsafe { Self::_from_vec_with_nul_unchecked(v) }
    }

    unsafe fn _from_vec_with_nul_unchecked(v: Vec<u8>) -> Self {
        Self { inner: v.into_boxed_slice() }
    }

    /// 尝试将 <code>[Vec]<[u8]></code> 转换为 [`CString`]。
    ///
    /// 存在运行时检查以确保 [`Vec`] (它的最后一个元素) 中只有一个 nul 字节。
    ///
    /// # Errors
    ///
    /// 如果存在 nul 字节而不是最后一个元素，或者不存在 nul 字节，则将返回错误。
    ///
    /// # Examples
    ///
    /// 如果调用成功而没有结尾的 nul 字节，则转换将产生与 [`CString::new`] 相同的结果。
    ///
    ///
    /// ```
    /// use std::ffi::CString;
    /// assert_eq!(
    ///     CString::from_vec_with_nul(b"abc\0".to_vec())
    ///         .expect("CString::from_vec_with_nul failed"),
    ///     CString::new(b"abc".to_vec()).expect("CString::new failed")
    /// );
    /// ```
    ///
    /// 格式不正确的 [`Vec`] 会产生错误。
    ///
    /// ```
    /// use std::ffi::{CString, FromVecWithNulError};
    /// // 内部 nul 字节
    /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"a\0bc".to_vec()).unwrap_err();
    /// // 无空字节
    /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"abc".to_vec()).unwrap_err();
    /// ```
    ///
    ///
    #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
    pub fn from_vec_with_nul(v: Vec<u8>) -> Result<Self, FromVecWithNulError> {
        let nul_pos = memchr::memchr(0, &v);
        match nul_pos {
            Some(nul_pos) if nul_pos + 1 == v.len() => {
                // SAFETY: 我们知道在 vec 的末尾只有一个 nul 字节。
                //
                Ok(unsafe { Self::_from_vec_with_nul_unchecked(v) })
            }
            Some(nul_pos) => Err(FromVecWithNulError {
                error_kind: FromBytesWithNulErrorKind::InteriorNul(nul_pos),
                bytes: v,
            }),
            None => Err(FromVecWithNulError {
                error_kind: FromBytesWithNulErrorKind::NotNulTerminated,
                bytes: v,
            }),
        }
    }
}

// 将此 `CString` 转换为空字符串，以防止意外执行内存不安全代码。
// 内联以防止 LLVM 在调试版本中进行优化。
//
#[stable(feature = "cstring_drop", since = "1.13.0")]
impl Drop for CString {
    #[inline]
    fn drop(&mut self) {
        unsafe {
            *self.inner.get_unchecked_mut(0) = 0;
        }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl ops::Deref for CString {
    type Target = CStr;

    #[inline]
    fn deref(&self) -> &CStr {
        unsafe { CStr::from_bytes_with_nul_unchecked(self.as_bytes_with_nul()) }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for CString {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&**self, f)
    }
}

#[stable(feature = "cstring_into", since = "1.7.0")]
impl From<CString> for Vec<u8> {
    /// 将 [`CString`] 转换为 <code>[Vec]<[u8]></code>。
    ///
    /// 转换消耗 [`CString`]，并删除终止的 NUL 字节。
    #[inline]
    fn from(s: CString) -> Vec<u8> {
        s.into_bytes()
    }
}

#[stable(feature = "cstr_default", since = "1.10.0")]
impl Default for CString {
    /// 创建一个空的 `CString`。
    fn default() -> CString {
        let a: &CStr = Default::default();
        a.to_owned()
    }
}

#[stable(feature = "cstr_borrow", since = "1.3.0")]
impl Borrow<CStr> for CString {
    #[inline]
    fn borrow(&self) -> &CStr {
        self
    }
}

#[stable(feature = "cstring_from_cow_cstr", since = "1.28.0")]
impl<'a> From<Cow<'a, CStr>> for CString {
    /// 通过复制借用的内容将 `Cow<'a, CStr>` 转换为 `CString`。
    ///
    #[inline]
    fn from(s: Cow<'a, CStr>) -> Self {
        s.into_owned()
    }
}

#[cfg(not(test))]
#[stable(feature = "box_from_c_str", since = "1.17.0")]
impl From<&CStr> for Box<CStr> {
    /// 通过将内容复制到新分配的 [`Box`] 中，将 `&CStr` 转换为 `Box<CStr>`。
    ///
    fn from(s: &CStr) -> Box<CStr> {
        let boxed: Box<[u8]> = Box::from(s.to_bytes_with_nul());
        unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) }
    }
}

#[stable(feature = "box_from_cow", since = "1.45.0")]
impl From<Cow<'_, CStr>> for Box<CStr> {
    /// 通过复制借用的内容将 `Cow<'a, CStr>` 转换为 `Box<CStr>`。
    ///
    #[inline]
    fn from(cow: Cow<'_, CStr>) -> Box<CStr> {
        match cow {
            Cow::Borrowed(s) => Box::from(s),
            Cow::Owned(s) => Box::from(s),
        }
    }
}

#[stable(feature = "c_string_from_box", since = "1.18.0")]
impl From<Box<CStr>> for CString {
    /// 将 <code>[Box]<[CStr]></code> 转换为 [`CString`]，无需复制或分配。
    #[inline]
    fn from(s: Box<CStr>) -> CString {
        let raw = Box::into_raw(s) as *mut [u8];
        CString { inner: unsafe { Box::from_raw(raw) } }
    }
}

#[stable(feature = "cstring_from_vec_of_nonzerou8", since = "1.43.0")]
impl From<Vec<NonZeroU8>> for CString {
    /// 将 <code>[Vec]<[NonZeroU8]></code> 转换为 [`CString`]，无需复制或检查内部空字节。
    ///
    #[inline]
    fn from(v: Vec<NonZeroU8>) -> CString {
        unsafe {
            // 将 `Vec<NonZeroU8>` 转换为 `Vec<u8>`。
            let v: Vec<u8> = {
                // SAFETY:
                //   - `NonZeroU8` 和 `u8` 之间的转换是声音；
                //   - `alloc::Layout<NonZeroU8> == alloc::Layout<u8>`.
                let (ptr, len, cap): (*mut NonZeroU8, _, _) = Vec::into_raw_parts(v);
                Vec::from_raw_parts(ptr.cast::<u8>(), len, cap)
            };
            // SAFETY: 给定 `NonZeroU8` 的类型级别不变性，`v` 不能包含空字节。
            //
            Self::_from_vec_unchecked(v)
        }
    }
}

#[cfg(not(test))]
#[stable(feature = "more_box_slice_clone", since = "1.29.0")]
impl Clone for Box<CStr> {
    #[inline]
    fn clone(&self) -> Self {
        (**self).into()
    }
}

#[stable(feature = "box_from_c_string", since = "1.20.0")]
impl From<CString> for Box<CStr> {
    /// 将 [`CString`] 转换为 <code>[Box]<[CStr]></code>，无需复制或分配。
    #[inline]
    fn from(s: CString) -> Box<CStr> {
        s.into_boxed_c_str()
    }
}

#[stable(feature = "cow_from_cstr", since = "1.28.0")]
impl<'a> From<CString> for Cow<'a, CStr> {
    /// 无需复制或分配即可将 [`CString`] 转换为拥有所有权的 [`Cow`]。
    #[inline]
    fn from(s: CString) -> Cow<'a, CStr> {
        Cow::Owned(s)
    }
}

#[stable(feature = "cow_from_cstr", since = "1.28.0")]
impl<'a> From<&'a CStr> for Cow<'a, CStr> {
    /// 将 [`CStr`] 转换为借用的 [`Cow`]，无需复制或分配。
    #[inline]
    fn from(s: &'a CStr) -> Cow<'a, CStr> {
        Cow::Borrowed(s)
    }
}

#[stable(feature = "cow_from_cstr", since = "1.28.0")]
impl<'a> From<&'a CString> for Cow<'a, CStr> {
    /// 将 `&`[`CString`] 转换为借用的 [`Cow`]，无需复制或分配。
    #[inline]
    fn from(s: &'a CString) -> Cow<'a, CStr> {
        Cow::Borrowed(s.as_c_str())
    }
}

#[cfg(target_has_atomic = "ptr")]
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<CString> for Arc<CStr> {
    /// 通过将 [`CString`] 数据移动到新的 [`Arc`] 缓冲区中，将 [`CString`] 转换为 <code>[Arc]<[CStr]></code>。
    ///
    #[inline]
    fn from(s: CString) -> Arc<CStr> {
        let arc: Arc<[u8]> = Arc::from(s.into_inner());
        unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) }
    }
}

#[cfg(target_has_atomic = "ptr")]
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<&CStr> for Arc<CStr> {
    /// 通过将内容复制到新分配的 [`Arc`] 中，将 `&CStr` 转换为 `Arc<CStr>`。
    ///
    #[inline]
    fn from(s: &CStr) -> Arc<CStr> {
        let arc: Arc<[u8]> = Arc::from(s.to_bytes_with_nul());
        unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) }
    }
}

#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<CString> for Rc<CStr> {
    /// 通过将 [`CString`] 数据移动到新的 [`Arc`] 缓冲区中，将 [`CString`] 转换为 <code>[Rc]<[CStr]></code>。
    ///
    #[inline]
    fn from(s: CString) -> Rc<CStr> {
        let rc: Rc<[u8]> = Rc::from(s.into_inner());
        unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) }
    }
}

#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<&CStr> for Rc<CStr> {
    /// 通过将内容复制到新分配的 [`Rc`] 中，将 `&CStr` 转换为 `Rc<CStr>`。
    ///
    #[inline]
    fn from(s: &CStr) -> Rc<CStr> {
        let rc: Rc<[u8]> = Rc::from(s.to_bytes_with_nul());
        unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) }
    }
}

#[cfg(not(test))]
#[stable(feature = "default_box_extra", since = "1.17.0")]
impl Default for Box<CStr> {
    fn default() -> Box<CStr> {
        let boxed: Box<[u8]> = Box::from([0]);
        unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) }
    }
}

impl NulError {
    /// 返回导致 [`CString::new`] 失败的切片中 nul 字节的位置。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let nul_error = CString::new("foo\0bar").unwrap_err();
    /// assert_eq!(nul_error.nul_position(), 3);
    ///
    /// let nul_error = CString::new("foo bar\0").unwrap_err();
    /// assert_eq!(nul_error.nul_position(), 7);
    /// ```
    #[must_use]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn nul_position(&self) -> usize {
        self.0
    }

    /// 消耗此错误，返回底层的 vector 字节，该字节首先生成错误。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let nul_error = CString::new("foo\0bar").unwrap_err();
    /// assert_eq!(nul_error.into_vec(), b"foo\0bar");
    /// ```
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn into_vec(self) -> Vec<u8> {
        self.1
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Display for NulError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "nul byte found in provided data at position: {}", self.0)
    }
}

#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
impl fmt::Display for FromVecWithNulError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.error_kind {
            FromBytesWithNulErrorKind::InteriorNul(pos) => {
                write!(f, "data provided contains an interior nul byte at pos {pos}")
            }
            FromBytesWithNulErrorKind::NotNulTerminated => {
                write!(f, "data provided is not nul terminated")
            }
        }
    }
}

impl IntoStringError {
    /// 消耗此错误，返回产生错误的原始 [`CString`]。
    ///
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "cstring_into", since = "1.7.0")]
    pub fn into_cstring(self) -> CString {
        self.inner
    }

    /// 访问根本的 UTF-8 错误，该错误是引起此错误的原因。
    #[must_use]
    #[stable(feature = "cstring_into", since = "1.7.0")]
    pub fn utf8_error(&self) -> Utf8Error {
        self.error
    }
}

impl IntoStringError {
    fn description(&self) -> &str {
        "C string contained non-utf8 bytes"
    }
}

#[stable(feature = "cstring_into", since = "1.7.0")]
impl fmt::Display for IntoStringError {
    #[allow(deprecated, deprecated_in_future)]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.description().fmt(f)
    }
}

#[stable(feature = "cstr_borrow", since = "1.3.0")]
impl ToOwned for CStr {
    type Owned = CString;

    fn to_owned(&self) -> CString {
        CString { inner: self.to_bytes_with_nul().into() }
    }

    fn clone_into(&self, target: &mut CString) {
        let mut b = into_vec(mem::take(&mut target.inner));
        self.to_bytes_with_nul().clone_into(&mut b);
        target.inner = b.into_boxed_slice();
    }
}

#[stable(feature = "cstring_asref", since = "1.7.0")]
impl From<&CStr> for CString {
    fn from(s: &CStr) -> CString {
        s.to_owned()
    }
}

#[stable(feature = "cstring_asref", since = "1.7.0")]
impl ops::Index<ops::RangeFull> for CString {
    type Output = CStr;

    #[inline]
    fn index(&self, _index: ops::RangeFull) -> &CStr {
        self
    }
}

#[stable(feature = "cstring_asref", since = "1.7.0")]
impl AsRef<CStr> for CString {
    #[inline]
    fn as_ref(&self) -> &CStr {
        self
    }
}

#[cfg(not(test))]
impl CStr {
    /// 将 `CStr` 转换为 <code>[Cow]<[str]></code>。
    ///
    /// 如果 `CStr` 的内容是有效的 UTF-8 数据，该函数将返回一个 <code>[Cow]::[Borrowed]\(&[str])</code> 和相应的 <code>&[str]</code> 切片。
    /// 否则，它将用 [`U+FFFD 替换字符`][U+FFFD] 替换任何无效的 UTF-8 序列，并返回 <code>[Cow]::[Owned]\(&[str])</code> 作为结果。
    ///
    /// [str]: prim@str "str"
    /// [Borrowed]: Cow::Borrowed
    /// [Owned]: Cow::Owned
    /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER "std::char::REPLACEMENT_CHARACTER"
    ///
    /// # Examples
    ///
    /// 在包含有效 UTF-8 的 `CStr` 上调用 `to_string_lossy`：
    ///
    /// ```
    /// use std::borrow::Cow;
    /// use std::ffi::CStr;
    ///
    /// let cstr = CStr::from_bytes_with_nul(b"Hello World\0")
    ///                  .expect("CStr::from_bytes_with_nul failed");
    /// assert_eq!(cstr.to_string_lossy(), Cow::Borrowed("Hello World"));
    /// ```
    ///
    /// 在包含无效 UTF-8 的 `CStr` 上调用 `to_string_lossy`：
    ///
    /// ```
    /// use std::borrow::Cow;
    /// use std::ffi::CStr;
    ///
    /// let cstr = CStr::from_bytes_with_nul(b"Hello \xF0\x90\x80World\0")
    ///                  .expect("CStr::from_bytes_with_nul failed");
    /// assert_eq!(
    ///     cstr.to_string_lossy(),
    ///     Cow::Owned(String::from("Hello �World")) as Cow<'_, str>
    /// );
    /// ```
    ///
    ///
    ///
    ///
    #[rustc_allow_incoherent_impl]
    #[must_use = "this returns the result of the operation, \
                  without modifying the original"]
    #[stable(feature = "cstr_to_str", since = "1.4.0")]
    pub fn to_string_lossy(&self) -> Cow<'_, str> {
        String::from_utf8_lossy(self.to_bytes())
    }

    /// 将 <code>[Box]<[CStr]></code> 转换为 [`CString`]，无需复制或分配。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::ffi::CString;
    ///
    /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed");
    /// let boxed = c_string.into_boxed_c_str();
    /// assert_eq!(boxed.into_c_string(), CString::new("foo").expect("CString::new failed"));
    /// ```
    #[rustc_allow_incoherent_impl]
    #[must_use = "`self` will be dropped if the result is not used"]
    #[stable(feature = "into_boxed_c_str", since = "1.20.0")]
    pub fn into_c_string(self: Box<Self>) -> CString {
        CString::from(self)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl core::error::Error for NulError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "nul byte found in data"
    }
}

#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
impl core::error::Error for FromVecWithNulError {}

#[stable(feature = "cstring_into", since = "1.7.0")]
impl core::error::Error for IntoStringError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "C string contained non-utf8 bytes"
    }

    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        Some(&self.error)
    }
}