//! 字符串操作。
//!
//! 有关更多详细信息，请参见 [`std::str`] 模块。
//!
//! [`std::str`]: ../../std/str/index.html

#![stable(feature = "rust1", since = "1.0.0")]

mod converts;
mod count;
mod error;
mod iter;
mod traits;
mod validations;

use self::pattern::Pattern;
use self::pattern::{DoubleEndedSearcher, ReverseSearcher, Searcher};

use crate::ascii;
use crate::char::{self, EscapeDebugExtArgs};
use crate::mem;
use crate::slice::{self, SliceIndex};

pub mod pattern;

mod lossy;
#[unstable(feature = "utf8_chunks", issue = "99543")]
pub use lossy::{Utf8Chunk, Utf8Chunks};

#[stable(feature = "rust1", since = "1.0.0")]
pub use converts::{from_utf8, from_utf8_unchecked};

#[stable(feature = "str_mut_extras", since = "1.20.0")]
pub use converts::{from_utf8_mut, from_utf8_unchecked_mut};

#[stable(feature = "rust1", since = "1.0.0")]
pub use error::{ParseBoolError, Utf8Error};

#[stable(feature = "rust1", since = "1.0.0")]
pub use traits::FromStr;

#[stable(feature = "rust1", since = "1.0.0")]
pub use iter::{Bytes, CharIndices, Chars, Lines, SplitWhitespace};

#[stable(feature = "rust1", since = "1.0.0")]
#[allow(deprecated)]
pub use iter::LinesAny;

#[stable(feature = "rust1", since = "1.0.0")]
pub use iter::{RSplit, RSplitTerminator, Split, SplitTerminator};

#[stable(feature = "rust1", since = "1.0.0")]
pub use iter::{RSplitN, SplitN};

#[stable(feature = "str_matches", since = "1.2.0")]
pub use iter::{Matches, RMatches};

#[stable(feature = "str_match_indices", since = "1.5.0")]
pub use iter::{MatchIndices, RMatchIndices};

#[stable(feature = "encode_utf16", since = "1.8.0")]
pub use iter::EncodeUtf16;

#[stable(feature = "str_escape", since = "1.34.0")]
pub use iter::{EscapeDebug, EscapeDefault, EscapeUnicode};

#[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
pub use iter::SplitAsciiWhitespace;

#[stable(feature = "split_inclusive", since = "1.51.0")]
pub use iter::SplitInclusive;

#[unstable(feature = "str_internals", issue = "none")]
pub use validations::{next_code_point, utf8_char_width};

use iter::MatchIndicesInternal;
use iter::SplitInternal;
use iter::{MatchesInternal, SplitNInternal};

#[inline(never)]
#[cold]
#[track_caller]
#[rustc_allow_const_fn_unstable(const_eval_select)]
const fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
    // SAFETY: 两个分支的 panic
    unsafe {
        crate::intrinsics::const_eval_select(
            (s, begin, end),
            slice_error_fail_ct,
            slice_error_fail_rt,
        )
    }
}

#[track_caller]
const fn slice_error_fail_ct(_: &str, _: usize, _: usize) -> ! {
    panic!("failed to slice string");
}

#[track_caller]
fn slice_error_fail_rt(s: &str, begin: usize, end: usize) -> ! {
    const MAX_DISPLAY_LENGTH: usize = 256;
    let trunc_len = s.floor_char_boundary(MAX_DISPLAY_LENGTH);
    let s_trunc = &s[..trunc_len];
    let ellipsis = if trunc_len < s.len() { "[...]" } else { "" };

    // 1. 越界
    if begin > s.len() || end > s.len() {
        let oob_index = if begin > s.len() { begin } else { end };
        panic!("byte index {oob_index} is out of bounds of `{s_trunc}`{ellipsis}");
    }

    // 2. begin <= end
    assert!(
        begin <= end,
        "begin <= end ({} <= {}) when slicing `{}`{}",
        begin,
        end,
        s_trunc,
        ellipsis
    );

    // 3. 角色边界
    let index = if !s.is_char_boundary(begin) { begin } else { end };
    // 找到角色
    let char_start = s.floor_char_boundary(index);
    // `char_start` 必须小于 len 和一个字符边界
    let ch = s[char_start..].chars().next().unwrap();
    let char_range = char_start..char_start + ch.len_utf8();
    panic!(
        "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}",
        index, ch, char_range, s_trunc, ellipsis
    );
}

#[cfg(not(test))]
impl str {
    /// 返回 `self` 的长度。
    ///
    /// 该长度以字节为单位，而不是 [`char`] 或字素。
    /// 换句话说，它可能不是人类认为的字符串长度。
    ///
    /// [`char`]: prim@char
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let len = "foo".len();
    /// assert_eq!(3, len);
    ///
    /// assert_eq!("ƒoo".len(), 4); // fancy f!
    /// assert_eq!("ƒoo".chars().count(), 3);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_stable(feature = "const_str_len", since = "1.39.0")]
    #[must_use]
    #[inline]
    pub const fn len(&self) -> usize {
        self.as_bytes().len()
    }

    /// 如果 `self` 的长度为零字节，则返回 `true`。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = "";
    /// assert!(s.is_empty());
    ///
    /// let s = "not empty";
    /// assert!(!s.is_empty());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_stable(feature = "const_str_is_empty", since = "1.39.0")]
    #[must_use]
    #[inline]
    pub const fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// 检查第 index 个字节是 UTF-8 代码点序列中的第一个字节还是字符串的末尾。
    ///
    ///
    /// 字符串的开头和结尾 (当 `index == self.len()`) 被视为边界时。
    ///
    /// 如果 `index` 大于 `self.len()`，则返回 `false`。
    ///
    /// # Examples
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard";
    /// assert!(s.is_char_boundary(0));
    /// // start of `老`
    /// assert!(s.is_char_boundary(6));
    /// assert!(s.is_char_boundary(s.len()));
    ///
    /// // `ö` 的第二个字节
    /// assert!(!s.is_char_boundary(2));
    ///
    /// // third byte of `老`
    /// assert!(!s.is_char_boundary(8));
    /// ```
    ///
    #[must_use]
    #[stable(feature = "is_char_boundary", since = "1.9.0")]
    #[inline]
    pub fn is_char_boundary(&self, index: usize) -> bool {
        // 0 总是可以的。
        // 显式测试 0，以便可以轻松优化检查，并在这种情况下跳过读取字符串数据。
        //
        // 请注意，优化 `self.get(..index)` 依赖于此。
        if index == 0 {
            return true;
        }

        match self.as_bytes().get(index) {
            // 对于 `None`，我们有两个选择：
            //
            // - index == self.len() 空字符串是有效的，因此返回 true
            // - index > self.len() 在这种情况下返回 false
            //
            // 检查正好放在这里，因为它改进了更高 opt-level 上生成的代码。
            // 有关更多详细信息，请参见 PR #84751。
            //
            //
            None => index == self.len(),

            Some(&b) => b.is_utf8_char_boundary(),
        }
    }

    /// 查找不超过 `index` 的最接近的 `x`，其中 `is_char_boundary(x)` 是 `true`。
    ///
    /// 此方法可以帮助您截断字符串，使其仍然是有效的 UTF-8，但不超过给定的字节数。
    /// 请注意，这纯粹是在字符级别完成的，并且仍然可以在视觉上分割字素，即使底层字符没有被分割。
    ///
    /// 例如，表情符号 🧑‍🔬 (科学家) 可以被拆分，以便字符串仅包含 🧑 (人)。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(round_char_boundary)]
    /// let s = "❤️🧡💛💚💙💜";
    /// assert_eq!(s.len(), 26);
    /// assert!(!s.is_char_boundary(13));
    ///
    /// let closest = s.floor_char_boundary(13);
    /// assert_eq!(closest, 10);
    /// assert_eq!(&s[..closest], "❤️🧡");
    /// ```
    ///
    #[unstable(feature = "round_char_boundary", issue = "93743")]
    #[inline]
    pub fn floor_char_boundary(&self, index: usize) -> usize {
        if index >= self.len() {
            self.len()
        } else {
            let lower_bound = index.saturating_sub(3);
            let new_index = self.as_bytes()[lower_bound..=index]
                .iter()
                .rposition(|b| b.is_utf8_char_boundary());

            // SAFETY: 我们知道字符边界将在四个字节内
            unsafe { lower_bound + new_index.unwrap_unchecked() }
        }
    }

    /// 查找不低于 `index` 的最接近的 `x`，其中 `is_char_boundary(x)` 是 `true`。
    ///
    /// 这种方法是对 [`floor_char_boundary`] 的自然补充。
    /// 有关更多详细信息，请参见该方法。
    ///
    /// [`floor_char_boundary`]: str::floor_char_boundary
    ///
    /// # Panics
    ///
    /// 如果 `index > self.len()`，就会出现 panic。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(round_char_boundary)]
    /// let s = "❤️🧡💛💚💙💜";
    /// assert_eq!(s.len(), 26);
    /// assert!(!s.is_char_boundary(13));
    ///
    /// let closest = s.ceil_char_boundary(13);
    /// assert_eq!(closest, 14);
    /// assert_eq!(&s[..closest], "❤️🧡💛");
    /// ```
    #[unstable(feature = "round_char_boundary", issue = "93743")]
    #[inline]
    pub fn ceil_char_boundary(&self, index: usize) -> usize {
        if index > self.len() {
            slice_error_fail(self, index, index)
        } else {
            let upper_bound = Ord::min(index + 4, self.len());
            self.as_bytes()[index..upper_bound]
                .iter()
                .position(|b| b.is_utf8_char_boundary())
                .map_or(upper_bound, |pos| pos + index)
        }
    }

    /// 将字符串切片转换为字节切片。
    /// 要将字节切片切回为字符串切片，请使用 [`from_utf8`] 函数。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let bytes = "bors".as_bytes();
    /// assert_eq!(b"bors", bytes);
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_stable(feature = "str_as_bytes", since = "1.39.0")]
    #[must_use]
    #[inline(always)]
    #[allow(unused_attributes)]
    pub const fn as_bytes(&self) -> &[u8] {
        // SAFETY: 常量声音，因为我们转换了两种具有相同布局的类型
        unsafe { mem::transmute(self) }
    }

    /// 将可变字符串切片转换为可变字节切片。
    ///
    /// # Safety
    ///
    /// 调用者必须确保在借用结束和使用底层 `str` 之前，切片的内容是有效的 UTF-8。
    ///
    ///
    /// 使用内容无效的 `str` UTF-8 是未定义的行为。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let mut s = String::from("Hello");
    /// let bytes = unsafe { s.as_bytes_mut() };
    ///
    /// assert_eq!(b"Hello", bytes);
    /// ```
    ///
    /// Mutability:
    ///
    /// ```
    /// let mut s = String::from("🗻∈🌏");
    ///
    /// unsafe {
    ///     let bytes = s.as_bytes_mut();
    ///
    ///     bytes[0] = 0xF0;
    ///     bytes[1] = 0x9F;
    ///     bytes[2] = 0x8D;
    ///     bytes[3] = 0x94;
    /// }
    ///
    /// assert_eq!("🍔∈🌏", s);
    /// ```
    #[stable(feature = "str_mut_extras", since = "1.20.0")]
    #[must_use]
    #[inline(always)]
    pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
        // SAFETY: 从 `&str` 到 `&[u8]` 的转换是安全的，因为 `str` 与 `&[u8]` 具有相同的布局 (只有 std 可以保证)。
        //
        // 指针解引用是安全的，因为它来自变量引用，该变量对写操作有效。
        //
        unsafe { &mut *(self as *mut str as *mut [u8]) }
    }

    /// 将字符串切片转换为裸指针。
    ///
    /// 由于字符串切片是字节的切片，所以裸指针指向 [`u8`]。
    /// 该指针将指向字符串切片的第一个字节。
    ///
    /// 调用者必须确保返回的指针永远不会被写入。
    /// 如果需要更改字符串切片的内容，请使用 [`as_mut_ptr`]。
    ///
    ///
    /// [`as_mut_ptr`]: str::as_mut_ptr
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = "Hello";
    /// let ptr = s.as_ptr();
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")]
    #[must_use]
    #[inline(always)]
    pub const fn as_ptr(&self) -> *const u8 {
        self as *const str as *const u8
    }

    /// 将可变字符串切片转换为裸指针。
    ///
    /// 由于字符串切片是字节的切片，所以裸指针指向 [`u8`]。
    /// 该指针将指向字符串切片的第一个字节。
    ///
    /// 您有责任确保仅以有效的 UTF-8 方式修改字符串切片。
    ///
    ///
    #[stable(feature = "str_as_mut_ptr", since = "1.36.0")]
    #[must_use]
    #[inline(always)]
    pub fn as_mut_ptr(&mut self) -> *mut u8 {
        self as *mut str as *mut u8
    }

    /// 返回 `str` 的子切片。
    ///
    /// 这是索引 `str` 的非紧急选择。
    /// 每当等效的索引操作将为 panic 时，将返回 [`None`]。
    ///
    /// # Examples
    ///
    /// ```
    /// let v = String::from("🗻∈🌏");
    ///
    /// assert_eq!(Some("🗻"), v.get(0..4));
    ///
    /// // 索引不在 UTF-8 序列边界上
    /// assert!(v.get(1..).is_none());
    /// assert!(v.get(..8).is_none());
    ///
    /// // 越界
    /// assert!(v.get(..42).is_none());
    /// ```
    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
    #[inline]
    pub fn get<I: SliceIndex<str>>(&self, i: I) -> Option<&I::Output> {
        i.get(self)
    }

    /// 返回 `str` 的可变子切片。
    ///
    /// 这是索引 `str` 的非紧急选择。
    /// 每当等效的索引操作将为 panic 时，将返回 [`None`]。
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = String::from("hello");
    /// // 正确的长度
    /// assert!(v.get_mut(0..5).is_some());
    /// // 越界
    /// assert!(v.get_mut(..42).is_none());
    /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
    ///
    /// assert_eq!("hello", v);
    /// {
    ///     let s = v.get_mut(0..2);
    ///     let s = s.map(|s| {
    ///         s.make_ascii_uppercase();
    ///         &*s
    ///     });
    ///     assert_eq!(Some("HE"), s);
    /// }
    /// assert_eq!("HEllo", v);
    /// ```
    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
    #[inline]
    pub fn get_mut<I: SliceIndex<str>>(&mut self, i: I) -> Option<&mut I::Output> {
        i.get_mut(self)
    }

    /// 返回未经检查的 `str` 子切片。
    ///
    /// 这是索引 `str` 的未经检查的替代方法。
    ///
    /// # Safety
    ///
    /// 此函数的调用者有责任满足以下先决条件：
    ///
    /// * 起始索引不得超过结束索引；
    /// * 索引必须在原始切片的范围内；
    /// * 索引必须位于 UTF-8 序列边界上。
    ///
    /// 否则，返回的字符串切片可能会引用无效的内存或违反 `str` 类型传达的不变量。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let v = "🗻∈🌏";
    /// unsafe {
    ///     assert_eq!("🗻", v.get_unchecked(0..4));
    ///     assert_eq!("∈", v.get_unchecked(4..7));
    ///     assert_eq!("🌏", v.get_unchecked(7..11));
    /// }
    /// ```
    ///
    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
    #[inline]
    pub unsafe fn get_unchecked<I: SliceIndex<str>>(&self, i: I) -> &I::Output {
        // SAFETY: 调用者必须维护 `get_unchecked` 的安全保证；
        // 切片是可解引用的，因为 `self` 是一个安全的引用。
        // 返回的指针是安全的，因为 `SliceIndex` 的 impls 必须保证它是正确的。
        unsafe { &*i.get_unchecked(self) }
    }

    /// 返回 `str` 的可变，未经检查的子切片。
    ///
    /// 这是索引 `str` 的未经检查的替代方法。
    ///
    /// # Safety
    ///
    /// 此函数的调用者有责任满足以下先决条件：
    ///
    /// * 起始索引不得超过结束索引；
    /// * 索引必须在原始切片的范围内；
    /// * 索引必须位于 UTF-8 序列边界上。
    ///
    /// 否则，返回的字符串切片可能会引用无效的内存或违反 `str` 类型传达的不变量。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// let mut v = String::from("🗻∈🌏");
    /// unsafe {
    ///     assert_eq!("🗻", v.get_unchecked_mut(0..4));
    ///     assert_eq!("∈", v.get_unchecked_mut(4..7));
    ///     assert_eq!("🌏", v.get_unchecked_mut(7..11));
    /// }
    /// ```
    ///
    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
    #[inline]
    pub unsafe fn get_unchecked_mut<I: SliceIndex<str>>(&mut self, i: I) -> &mut I::Output {
        // SAFETY: 调用者必须维护 `get_unchecked_mut` 的安全保证；
        // 切片是可解引用的，因为 `self` 是一个安全的引用。
        // 返回的指针是安全的，因为 `SliceIndex` 的 impls 必须保证它是正确的。
        unsafe { &mut *i.get_unchecked_mut(self) }
    }

    /// 从另一个字符串切片中创建一个字符串切片，从而绕过安全检查。
    ///
    /// 通常不建议这样做，请谨慎使用！ 有关安全的替代方法，请参见 [`str`] 和 [`Index`]。
    ///
    ///
    /// [`Index`]: crate::ops::Index
    ///
    /// 此新切片从 `begin` 到 `end`，包括 `begin` 但不包括 `end`。
    ///
    /// 要获取可变字符串切片，请参见 [`slice_mut_unchecked`] 方法。
    ///
    /// [`slice_mut_unchecked`]: str::slice_mut_unchecked
    ///
    /// # Safety
    ///
    /// 此函数的调用者有责任满足三个先决条件：
    ///
    /// * `begin` 不得超过 `end`。
    /// * `begin` 和 `end` 必须是字符串切片内的字节位置。
    /// * `begin` 和 `end` 必须位于 UTF-8 序列边界上。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard";
    ///
    /// unsafe {
    ///     assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
    /// }
    ///
    /// let s = "Hello, world!";
    ///
    /// unsafe {
    ///     assert_eq!("world", s.slice_unchecked(7, 12));
    /// }
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[deprecated(since = "1.29.0", note = "use `get_unchecked(begin..end)` instead")]
    #[must_use]
    #[inline]
    pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str {
        // SAFETY: 调用者必须维护 `get_unchecked` 的安全保证；
        // 切片是可解引用的，因为 `self` 是一个安全的引用。
        // 返回的指针是安全的，因为 `SliceIndex` 的 impls 必须保证它是正确的。
        unsafe { &*(begin..end).get_unchecked(self) }
    }

    /// 从另一个字符串切片中创建一个字符串切片，从而绕过安全检查。
    /// 通常不建议这样做，请谨慎使用！ 有关安全的替代方案，请参见 [`str`] 和 [`IndexMut`]。
    ///
    ///
    /// [`IndexMut`]: crate::ops::IndexMut
    ///
    /// 此新切片从 `begin` 到 `end`，包括 `begin` 但不包括 `end`。
    ///
    /// 要获取不可变的字符串切片，请参见 [`slice_unchecked`] 方法。
    ///
    /// [`slice_unchecked`]: str::slice_unchecked
    ///
    /// # Safety
    ///
    /// 此函数的调用者有责任满足三个先决条件：
    ///
    /// * `begin` 不得超过 `end`。
    /// * `begin` 和 `end` 必须是字符串切片内的字节位置。
    /// * `begin` 和 `end` 必须位于 UTF-8 序列边界上。
    ///
    ///
    ///
    ///
    #[stable(feature = "str_slice_mut", since = "1.5.0")]
    #[deprecated(since = "1.29.0", note = "use `get_unchecked_mut(begin..end)` instead")]
    #[inline]
    pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str {
        // SAFETY: 调用者必须维护 `get_unchecked_mut` 的安全保证；
        // 切片是可解引用的，因为 `self` 是一个安全的引用。
        // 返回的指针是安全的，因为 `SliceIndex` 的 impls 必须保证它是正确的。
        unsafe { &mut *(begin..end).get_unchecked_mut(self) }
    }

    /// 在索引处将一个字符串切片分成两个。
    ///
    /// 参数 `mid` 应该是字符串开头的字节偏移量。
    /// 它也必须在 UTF-8 代码点的边界上。
    ///
    /// 返回的两个切片从字符串切片的开头到 `mid`，从 `mid` 到字符串切片的结尾。
    ///
    /// 要获取可变字符串切片，请参见 [`split_at_mut`] 方法。
    ///
    /// [`split_at_mut`]: str::split_at_mut
    ///
    /// # Panics
    ///
    /// 如果 `mid` 不在 UTF-8 代码点边界上，或者它超过了字符串切片的最后一个代码点的末尾，就会出现 panics。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = "Per Martin-Löf";
    ///
    /// let (first, last) = s.split_at(3);
    ///
    /// assert_eq!("Per", first);
    /// assert_eq!(" Martin-Löf", last);
    /// ```
    ///
    ///
    #[inline]
    #[must_use]
    #[stable(feature = "str_split_at", since = "1.4.0")]
    pub fn split_at(&self, mid: usize) -> (&str, &str) {
        // is_char_boundary 检查索引是否在 [0, .len()] 中
        if self.is_char_boundary(mid) {
            // SAFETY: 刚刚检查 `mid` 是否在 char 边界上。
            unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
        } else {
            slice_error_fail(self, 0, mid)
        }
    }

    /// 在索引处将一个可变字符串切片切成两部分。
    ///
    /// 参数 `mid` 应该是字符串开头的字节偏移量。
    /// 它也必须在 UTF-8 代码点的边界上。
    ///
    /// 返回的两个切片从字符串切片的开头到 `mid`，从 `mid` 到字符串切片的结尾。
    ///
    /// 要获取不可变的字符串切片，请参见 [`split_at`] 方法。
    ///
    /// [`split_at`]: str::split_at
    ///
    /// # Panics
    ///
    /// 如果 `mid` 不在 UTF-8 代码点边界上，或者它超过了字符串切片的最后一个代码点的末尾，就会出现 panics。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let mut s = "Per Martin-Löf".to_string();
    /// {
    ///     let (first, last) = s.split_at_mut(3);
    ///     first.make_ascii_uppercase();
    ///     assert_eq!("PER", first);
    ///     assert_eq!(" Martin-Löf", last);
    /// }
    /// assert_eq!("PER Martin-Löf", s);
    /// ```
    ///
    #[inline]
    #[must_use]
    #[stable(feature = "str_split_at", since = "1.4.0")]
    pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
        // is_char_boundary 检查索引是否在 [0, .len()] 中
        if self.is_char_boundary(mid) {
            let len = self.len();
            let ptr = self.as_mut_ptr();
            // SAFETY: 刚刚检查 `mid` 是否在 char 边界上。
            unsafe {
                (
                    from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
                    from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
                )
            }
        } else {
            slice_error_fail(self, 0, mid)
        }
    }

    /// 返回字符串切片的 [`char`] 上的迭代器。
    ///
    /// 由于字符串切片由有效的 UTF-8 组成，因此我们可以通过 [`char`] 遍历字符串切片。
    /// 此方法返回这样的迭代器。
    ///
    /// 请务必记住，[`char`] 表示 Unicode 标量值，可能与您对 'character' 的概念不符。
    ///
    /// 实际需要的是在字形簇上进行迭代。
    /// Rust 的标准库未提供此功能，请检查 crates.io。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let word = "goodbye";
    ///
    /// let count = word.chars().count();
    /// assert_eq!(7, count);
    ///
    /// let mut chars = word.chars();
    ///
    /// assert_eq!(Some('g'), chars.next());
    /// assert_eq!(Some('o'), chars.next());
    /// assert_eq!(Some('o'), chars.next());
    /// assert_eq!(Some('d'), chars.next());
    /// assert_eq!(Some('b'), chars.next());
    /// assert_eq!(Some('y'), chars.next());
    /// assert_eq!(Some('e'), chars.next());
    ///
    /// assert_eq!(None, chars.next());
    /// ```
    ///
    /// 请记住，[`char`] 可能与您对字符的直觉不符：
    ///
    /// [`char`]: prim@char
    ///
    /// ```
    /// let y = "y̆";
    ///
    /// let mut chars = y.chars();
    ///
    /// assert_eq!(Some('y'), chars.next()); // 不是 'y̆'
    /// assert_eq!(Some('\u{0306}'), chars.next());
    ///
    /// assert_eq!(None, chars.next());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn chars(&self) -> Chars<'_> {
        Chars { iter: self.as_bytes().iter() }
    }

    /// 返回字符串切片的 [`char`] 及其位置上的迭代器。
    ///
    /// 由于字符串切片由有效的 UTF-8 组成，因此我们可以通过 [`char`] 遍历字符串切片。
    /// 这个方法返回这两个 [`char`] 以及它们的字节位置的迭代器。
    ///
    /// 迭代器产生元组。位置是第一，[`char`] 是第二。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let word = "goodbye";
    ///
    /// let count = word.char_indices().count();
    /// assert_eq!(7, count);
    ///
    /// let mut char_indices = word.char_indices();
    ///
    /// assert_eq!(Some((0, 'g')), char_indices.next());
    /// assert_eq!(Some((1, 'o')), char_indices.next());
    /// assert_eq!(Some((2, 'o')), char_indices.next());
    /// assert_eq!(Some((3, 'd')), char_indices.next());
    /// assert_eq!(Some((4, 'b')), char_indices.next());
    /// assert_eq!(Some((5, 'y')), char_indices.next());
    /// assert_eq!(Some((6, 'e')), char_indices.next());
    ///
    /// assert_eq!(None, char_indices.next());
    /// ```
    ///
    /// 请记住，[`char`] 可能与您对字符的直觉不符：
    ///
    /// [`char`]: prim@char
    ///
    /// ```
    /// let yes = "y̆es";
    ///
    /// let mut char_indices = yes.char_indices();
    ///
    /// assert_eq!(Some((0, 'y')), char_indices.next()); // 不是 (0，'y̆')
    /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
    ///
    /// // 注意这里的 3 - 最后一个字符占用了两个字节
    /// assert_eq!(Some((3, 'e')), char_indices.next());
    /// assert_eq!(Some((4, 's')), char_indices.next());
    ///
    /// assert_eq!(None, char_indices.next());
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn char_indices(&self) -> CharIndices<'_> {
        CharIndices { front_offset: 0, iter: self.chars() }
    }

    /// 在字符串切片的字节上进行迭代的迭代器。
    ///
    /// 由于字符串切片由字节序列组成，因此我们可以逐字节遍历字符串切片。
    /// 此方法返回这样的迭代器。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let mut bytes = "bors".bytes();
    ///
    /// assert_eq!(Some(b'b'), bytes.next());
    /// assert_eq!(Some(b'o'), bytes.next());
    /// assert_eq!(Some(b'r'), bytes.next());
    /// assert_eq!(Some(b's'), bytes.next());
    ///
    /// assert_eq!(None, bytes.next());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn bytes(&self) -> Bytes<'_> {
        Bytes(self.as_bytes().iter().copied())
    }

    /// 用空格分割字符串切片。
    ///
    /// 返回的迭代器将返回作为原始字符串切片的子切片的字符串切片，并以任意数量的空格分隔。
    ///
    ///
    /// 'Whitespace' 是根据 Unicode 派生核心属性 `White_Space` 的条款定义的。
    /// 如果只想在 ASCII 空格上分割，请使用 [`split_ascii_whitespace`]。
    ///
    /// [`split_ascii_whitespace`]: str::split_ascii_whitespace
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let mut iter = "A few words".split_whitespace();
    ///
    /// assert_eq!(Some("A"), iter.next());
    /// assert_eq!(Some("few"), iter.next());
    /// assert_eq!(Some("words"), iter.next());
    ///
    /// assert_eq!(None, iter.next());
    /// ```
    ///
    /// 考虑所有类型的空白：
    ///
    /// ```
    /// let mut iter = " Mary   had\ta\u{2009}little  \n\t lamb".split_whitespace();
    /// assert_eq!(Some("Mary"), iter.next());
    /// assert_eq!(Some("had"), iter.next());
    /// assert_eq!(Some("a"), iter.next());
    /// assert_eq!(Some("little"), iter.next());
    /// assert_eq!(Some("lamb"), iter.next());
    ///
    /// assert_eq!(None, iter.next());
    /// ```
    ///
    /// 如果字符串为空或全为空白，则迭代器不产生字符串切片:
    ///
    /// ```
    /// assert_eq!("".split_whitespace().next(), None);
    /// assert_eq!("   ".split_whitespace().next(), None);
    /// ```
    #[must_use = "this returns the split string as an iterator, \
                  without modifying the original"]
    #[stable(feature = "split_whitespace", since = "1.1.0")]
    #[cfg_attr(not(test), rustc_diagnostic_item = "str_split_whitespace")]
    #[inline]
    pub fn split_whitespace(&self) -> SplitWhitespace<'_> {
        SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
    }

    /// 用 ASCII 空格分割字符串切片。
    ///
    /// 返回的迭代器将返回作为原始字符串切片的子切片的字符串切片，并以任意数量的 ASCII 空格分隔。
    ///
    /// 要改为按 Unicode `Whitespace` 进行拆分，请使用 [`split_whitespace`]。
    ///
    /// [`split_whitespace`]: str::split_whitespace
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let mut iter = "A few words".split_ascii_whitespace();
    ///
    /// assert_eq!(Some("A"), iter.next());
    /// assert_eq!(Some("few"), iter.next());
    /// assert_eq!(Some("words"), iter.next());
    ///
    /// assert_eq!(None, iter.next());
    /// ```
    ///
    /// 考虑所有类型的 ASCII 空白：
    ///
    /// ```
    /// let mut iter = " Mary   had\ta little  \n\t lamb".split_ascii_whitespace();
    /// assert_eq!(Some("Mary"), iter.next());
    /// assert_eq!(Some("had"), iter.next());
    /// assert_eq!(Some("a"), iter.next());
    /// assert_eq!(Some("little"), iter.next());
    /// assert_eq!(Some("lamb"), iter.next());
    ///
    /// assert_eq!(None, iter.next());
    /// ```
    ///
    /// 如果字符串为空或全部为 ASCII 空格，则迭代器不产生字符串切片:
    ///
    /// ```
    /// assert_eq!("".split_ascii_whitespace().next(), None);
    /// assert_eq!("   ".split_ascii_whitespace().next(), None);
    /// ```
    #[must_use = "this returns the split string as an iterator, \
                  without modifying the original"]
    #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
    #[inline]
    pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> {
        let inner =
            self.as_bytes().split(IsAsciiWhitespace).filter(BytesIsNotEmpty).map(UnsafeBytesToStr);
        SplitAsciiWhitespace { inner }
    }

    /// 在字符串的各行上进行迭代的迭代器，作为字符串切片。
    ///
    /// 行在换行符 (`\n`) 或回车符后跟换行符 (`\r\n`) 的行尾处拆分。
    ///
    /// 迭代器返回的行中不包含行终止符。
    ///
    /// 最后一行的结尾是可选的。
    /// 以最后一行结尾的字符串将返回与没有其他最后一行结尾的相同字符串相同的行。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let text = "foo\r\nbar\n\nbaz\n";
    /// let mut lines = text.lines();
    ///
    /// assert_eq!(Some("foo"), lines.next());
    /// assert_eq!(Some("bar"), lines.next());
    /// assert_eq!(Some(""), lines.next());
    /// assert_eq!(Some("baz"), lines.next());
    ///
    /// assert_eq!(None, lines.next());
    /// ```
    ///
    /// 不需要最后一行：
    ///
    /// ```
    /// let text = "foo\nbar\n\r\nbaz";
    /// let mut lines = text.lines();
    ///
    /// assert_eq!(Some("foo"), lines.next());
    /// assert_eq!(Some("bar"), lines.next());
    /// assert_eq!(Some(""), lines.next());
    /// assert_eq!(Some("baz"), lines.next());
    ///
    /// assert_eq!(None, lines.next());
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn lines(&self) -> Lines<'_> {
        Lines(self.split_inclusive('\n').map(LinesMap))
    }

    /// 字符串行上的迭代器。
    #[stable(feature = "rust1", since = "1.0.0")]
    #[deprecated(since = "1.4.0", note = "use lines() instead now")]
    #[inline]
    #[allow(deprecated)]
    pub fn lines_any(&self) -> LinesAny<'_> {
        LinesAny(self.lines())
    }

    /// 在编码为 UTF-16 的字符串上返回 `u16` 的迭代器。
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let text = "Zażółć gęślą jaźń";
    ///
    /// let utf8_len = text.len();
    /// let utf16_len = text.encode_utf16().count();
    ///
    /// assert!(utf16_len <= utf8_len);
    /// ```
    #[must_use = "this returns the encoded string as an iterator, \
                  without modifying the original"]
    #[stable(feature = "encode_utf16", since = "1.8.0")]
    pub fn encode_utf16(&self) -> EncodeUtf16<'_> {
        EncodeUtf16 { chars: self.chars(), extra: 0 }
    }

    /// 如果给定的模式与该字符串切片的子切片匹配，则返回 `true`。
    ///
    /// 如果不是，则返回 `false`。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let bananas = "bananas";
    ///
    /// assert!(bananas.contains("nana"));
    /// assert!(!bananas.contains("apples"));
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn contains<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
        pat.is_contained_in(self)
    }

    /// 如果给定的模式与此字符串切片的前缀匹配，则返回 `true`。
    ///
    /// 如果不是，则返回 `false`。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let bananas = "bananas";
    ///
    /// assert!(bananas.starts_with("bana"));
    /// assert!(!bananas.starts_with("nana"));
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn starts_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
        pat.is_prefix_of(self)
    }

    /// 如果给定的模式与该字符串切片的后缀匹配，则返回 `true`。
    ///
    /// 如果不是，则返回 `false`。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let bananas = "bananas";
    ///
    /// assert!(bananas.ends_with("anas"));
    /// assert!(!bananas.ends_with("nana"));
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn ends_with<'a, P>(&'a self, pat: P) -> bool
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        pat.is_suffix_of(self)
    }

    /// 返回此字符串切片中与模式匹配的第一个字符的字节索引。
    ///
    /// 如果模式不匹配，则返回 [`None`]。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard Gepardi";
    ///
    /// assert_eq!(s.find('L'), Some(0));
    /// assert_eq!(s.find('é'), Some(14));
    /// assert_eq!(s.find("pard"), Some(17));
    /// ```
    ///
    /// 使用无点样式和闭包的更复杂的模式：
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard";
    ///
    /// assert_eq!(s.find(char::is_whitespace), Some(5));
    /// assert_eq!(s.find(char::is_lowercase), Some(1));
    /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
    /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
    /// ```
    ///
    /// 找不到模式：
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard";
    /// let x: &[_] = &['1', '2'];
    ///
    /// assert_eq!(s.find(x), None);
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn find<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option<usize> {
        pat.into_searcher(self).next_match().map(|(i, _)| i)
    }

    /// 返回此字符串切片中模式的最后一个匹配项的第一个字符的字节索引。
    ///
    /// 如果模式不匹配，则返回 [`None`]。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard Gepardi";
    ///
    /// assert_eq!(s.rfind('L'), Some(13));
    /// assert_eq!(s.rfind('é'), Some(14));
    /// assert_eq!(s.rfind("pard"), Some(24));
    /// ```
    ///
    /// 闭包的更复杂模式：
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard";
    ///
    /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
    /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
    /// ```
    ///
    /// 找不到模式：
    ///
    /// ```
    /// let s = "Löwe 老虎 Léopard";
    /// let x: &[_] = &['1', '2'];
    ///
    /// assert_eq!(s.rfind(x), None);
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize>
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        pat.into_searcher(self).next_match_back().map(|(i, _)| i)
    }

    /// 在此字符串切片的子字符串上进行迭代的迭代器，该子字符串由模式匹配的字符分隔。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 如果模式允许反向搜索且 forward/reverse 搜索产生相同的元素，则返回的迭代器将为 [`DoubleEndedIterator`]。
    /// 例如，对于 [`char`]，这是正确的，但对于 `&str`，则不是。
    ///
    /// 如果模式允许反向搜索，但其结果可能与正向搜索不同，则可以使用 [`rsplit`] 方法。
    ///
    /// [`rsplit`]: str::rsplit
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
    /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
    ///
    /// let v: Vec<&str> = "".split('X').collect();
    /// assert_eq!(v, [""]);
    ///
    /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
    /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
    ///
    /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
    /// assert_eq!(v, ["lion", "tiger", "leopard"]);
    ///
    /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
    /// assert_eq!(v, ["abc", "def", "ghi"]);
    ///
    /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
    /// assert_eq!(v, ["lion", "tiger", "leopard"]);
    /// ```
    ///
    /// 如果模式是一片字符，请在每次出现任何字符时进行分割：
    ///
    /// ```
    /// let v: Vec<&str> = "2020-11-03 23:59".split(&['-', ' ', ':', '@'][..]).collect();
    /// assert_eq!(v, ["2020", "11", "03", "23", "59"]);
    /// ```
    ///
    /// 使用闭包的更复杂的模式：
    ///
    /// ```
    /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
    /// assert_eq!(v, ["abc", "def", "ghi"]);
    /// ```
    ///
    /// 如果一个字符串包含多个连续的分隔符，您将在输出中得到空字符串：
    ///
    /// ```
    /// let x = "||||a||b|c".to_string();
    /// let d: Vec<_> = x.split('|').collect();
    ///
    /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
    /// ```
    ///
    /// 连续的分隔符由空字符串分隔。
    ///
    /// ```
    /// let x = "(///)".to_string();
    /// let d: Vec<_> = x.split('/').collect();
    ///
    /// assert_eq!(d, &["(", "", "", ")"]);
    /// ```
    ///
    /// 字符串开头或结尾的分隔符与空字符串相邻。
    ///
    /// ```
    /// let d: Vec<_> = "010".split("0").collect();
    /// assert_eq!(d, &["", "1", ""]);
    /// ```
    ///
    /// 当空字符串用作分隔符时，它将字符串中的每个字符以及字符串的开头和结尾分隔开。
    ///
    /// ```
    /// let f: Vec<_> = "rust".split("").collect();
    /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
    /// ```
    ///
    /// 当使用空格作为分隔符时，连续的分隔符可能会导致令人惊讶的行为。这段代码是正确的：
    ///
    /// ```
    /// let x = "    a  b c".to_string();
    /// let d: Vec<_> = x.split(' ').collect();
    ///
    /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
    /// ```
    ///
    /// 它确实不会给您：
    ///
    /// ```,ignore
    /// assert_eq!(d, &["a", "b", "c"]);
    /// ```
    ///
    /// 为此行为使用 [`split_whitespace`]。
    ///
    /// [`split_whitespace`]: str::split_whitespace
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> {
        Split(SplitInternal {
            start: 0,
            end: self.len(),
            matcher: pat.into_searcher(self),
            allow_trailing_empty: true,
            finished: false,
        })
    }

    /// 在此字符串切片的子字符串上进行迭代的迭代器，该子字符串由模式匹配的字符分隔。
    /// 与 `split` 产生的迭代器的不同之处在于 `split_inclusive` 将匹配的部分保留为子字符串的终止符。
    ///
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// ```
    /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb."
    ///     .split_inclusive('\n').collect();
    /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb."]);
    /// ```
    ///
    /// 如果字符串的最后一个元素匹配，则该元素将被视为前一个子字符串的终止符。
    /// 该子字符串将是迭代器返回的最后一个项。
    ///
    /// ```
    /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb.\n"
    ///     .split_inclusive('\n').collect();
    /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb.\n"]);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "split_inclusive", since = "1.51.0")]
    #[inline]
    pub fn split_inclusive<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitInclusive<'a, P> {
        SplitInclusive(SplitInternal {
            start: 0,
            end: self.len(),
            matcher: pat.into_searcher(self),
            allow_trailing_empty: false,
            finished: false,
        })
    }

    /// 给定字符串切片的子字符串上的迭代器，该迭代器由与模式匹配的字符分隔，并以相反的顺序产生。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 返回的迭代器要求模式支持反向搜索，如果 forward/reverse 搜索产生相同的元素，它将是 [`DoubleEndedIterator`]。
    ///
    ///
    /// 为了从正面进行迭代，可以使用 [`split`] 方法。
    ///
    /// [`split`]: str::split
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
    /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
    ///
    /// let v: Vec<&str> = "".rsplit('X').collect();
    /// assert_eq!(v, [""]);
    ///
    /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
    /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
    ///
    /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
    /// assert_eq!(v, ["leopard", "tiger", "lion"]);
    /// ```
    ///
    /// 使用闭包的更复杂的模式：
    ///
    /// ```
    /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
    /// assert_eq!(v, ["ghi", "def", "abc"]);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn rsplit<'a, P>(&'a self, pat: P) -> RSplit<'a, P>
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        RSplit(self.split(pat).0)
    }

    /// 给定字符串切片的子字符串上的迭代器，该子字符串由模式匹配的字符分隔。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// 等效于 [`split`]，不同之处在于尾随的子字符串为空时将被跳过。
    ///
    /// [`split`]: str::split
    ///
    /// 此方法可用于 _terminated_ 的字符串数据，而不是用于模式的 _separated_ 的字符串数据。
    ///
    /// # 迭代器行为
    ///
    /// 如果模式允许反向搜索且 forward/reverse 搜索产生相同的元素，则返回的迭代器将为 [`DoubleEndedIterator`]。
    /// 例如，对于 [`char`]，这是正确的，但对于 `&str`，则不是。
    ///
    /// 如果模式允许反向搜索，但其结果可能与正向搜索不同，则可以使用 [`rsplit_terminator`] 方法。
    ///
    /// [`rsplit_terminator`]: str::rsplit_terminator
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
    /// assert_eq!(v, ["A", "B"]);
    ///
    /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
    /// assert_eq!(v, ["A", "", "B", ""]);
    ///
    /// let v: Vec<&str> = "A.B:C.D".split_terminator(&['.', ':'][..]).collect();
    /// assert_eq!(v, ["A", "B", "C", "D"]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> {
        SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
    }

    /// `self` 子字符串上的迭代器，该迭代器由与模式匹配的字符分隔，并以相反的顺序产生。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// 等效于 [`split`]，不同之处在于尾随的子字符串为空时将被跳过。
    ///
    /// [`split`]: str::split
    ///
    /// 此方法可用于 _terminated_ 的字符串数据，而不是用于模式的 _separated_ 的字符串数据。
    ///
    /// # 迭代器行为
    ///
    /// 返回的迭代器要求模式支持反向搜索，如果 forward/reverse 搜索产生相同的元素，则它将是双头模式。
    ///
    ///
    /// 为了从正面进行迭代，可以使用 [`split_terminator`] 方法。
    ///
    /// [`split_terminator`]: str::split_terminator
    ///
    /// # Examples
    ///
    /// ```
    /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
    /// assert_eq!(v, ["B", "A"]);
    ///
    /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
    /// assert_eq!(v, ["", "B", "", "A"]);
    ///
    /// let v: Vec<&str> = "A.B:C.D".rsplit_terminator(&['.', ':'][..]).collect();
    /// assert_eq!(v, ["D", "C", "B", "A"]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn rsplit_terminator<'a, P>(&'a self, pat: P) -> RSplitTerminator<'a, P>
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        RSplitTerminator(self.split_terminator(pat).0)
    }

    /// 给定字符串切片的子字符串上的迭代器 (由模式分隔)，仅限于返回最多 `n` 项。
    ///
    /// 如果返回 `n` 子字符串，则最后一个子字符串 (第 n 个子字符串) 将包含字符串的其余部分。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 返回的迭代器不会是双头的，因为支持效率不高。
    ///
    /// 如果模式允许反向搜索，则可以使用 [`rsplitn`] 方法。
    ///
    /// [`rsplitn`]: str::rsplitn
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
    /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
    ///
    /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
    /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
    ///
    /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
    /// assert_eq!(v, ["abcXdef"]);
    ///
    /// let v: Vec<&str> = "".splitn(1, 'X').collect();
    /// assert_eq!(v, [""]);
    /// ```
    ///
    /// 使用闭包的更复杂的模式：
    ///
    /// ```
    /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
    /// assert_eq!(v, ["abc", "defXghi"]);
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn splitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> SplitN<'a, P> {
        SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
    }

    /// 从字符串的末尾开始，在此字符串切片的子字符串上进行迭代的迭代器，由模式分隔，限制为最多返回 `n` 项。
    ///
    ///
    /// 如果返回 `n` 子字符串，则最后一个子字符串 (第 n 个子字符串) 将包含字符串的其余部分。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 返回的迭代器不会是双头的，因为支持效率不高。
    ///
    /// 要从正面拆分，可以使用 [`splitn`] 方法。
    ///
    /// [`splitn`]: str::splitn
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
    /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
    ///
    /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
    /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
    ///
    /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
    /// assert_eq!(v, ["leopard", "lion::tiger"]);
    /// ```
    ///
    /// 使用闭包的更复杂的模式：
    ///
    /// ```
    /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
    /// assert_eq!(v, ["ghi", "abc1def"]);
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn rsplitn<'a, P>(&'a self, n: usize, pat: P) -> RSplitN<'a, P>
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        RSplitN(self.splitn(n, pat).0)
    }

    /// 在第一次出现指定分隔符时拆分字符串，并在分隔符之前返回前缀，在分隔符之后返回后缀。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!("cfg".split_once('='), None);
    /// assert_eq!("cfg=".split_once('='), Some(("cfg", "")));
    /// assert_eq!("cfg=foo".split_once('='), Some(("cfg", "foo")));
    /// assert_eq!("cfg=foo=bar".split_once('='), Some(("cfg", "foo=bar")));
    /// ```
    #[stable(feature = "str_split_once", since = "1.52.0")]
    #[inline]
    pub fn split_once<'a, P: Pattern<'a>>(&'a self, delimiter: P) -> Option<(&'a str, &'a str)> {
        let (start, end) = delimiter.into_searcher(self).next_match()?;
        // SAFETY: 已知 `Searcher` 返回有效索引。
        unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
    }

    /// 在最后一次出现指定分隔符时分割字符串，并在分隔符之前返回前缀，在分隔符之后返回后缀。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!("cfg".rsplit_once('='), None);
    /// assert_eq!("cfg=foo".rsplit_once('='), Some(("cfg", "foo")));
    /// assert_eq!("cfg=foo=bar".rsplit_once('='), Some(("cfg=foo", "bar")));
    /// ```
    #[stable(feature = "str_split_once", since = "1.52.0")]
    #[inline]
    pub fn rsplit_once<'a, P>(&'a self, delimiter: P) -> Option<(&'a str, &'a str)>
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        let (start, end) = delimiter.into_searcher(self).next_match_back()?;
        // SAFETY: 已知 `Searcher` 返回有效索引。
        unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
    }

    /// 给定字符串切片中某个模式的不相交匹配的迭代器。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 如果模式允许反向搜索且 forward/reverse 搜索产生相同的元素，则返回的迭代器将为 [`DoubleEndedIterator`]。
    /// 例如，对于 [`char`]，这是正确的，但对于 `&str`，则不是。
    ///
    /// 如果模式允许反向搜索，但其结果可能与正向搜索不同，则可以使用 [`rmatches`] 方法。
    ///
    /// [`rmatches`]: str::matches
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
    /// assert_eq!(v, ["abc", "abc", "abc"]);
    ///
    /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
    /// assert_eq!(v, ["1", "2", "3"]);
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "str_matches", since = "1.2.0")]
    #[inline]
    pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> {
        Matches(MatchesInternal(pat.into_searcher(self)))
    }

    /// 在此字符串切片中某个模式的不相交匹配项上进行迭代的迭代器，其生成顺序相反。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 返回的迭代器要求模式支持反向搜索，如果 forward/reverse 搜索产生相同的元素，它将是 [`DoubleEndedIterator`]。
    ///
    ///
    /// 为了从正面进行迭代，可以使用 [`matches`] 方法。
    ///
    /// [`matches`]: str::matches
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
    /// assert_eq!(v, ["abc", "abc", "abc"]);
    ///
    /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
    /// assert_eq!(v, ["3", "2", "1"]);
    /// ```
    ///
    ///
    ///
    #[stable(feature = "str_matches", since = "1.2.0")]
    #[inline]
    pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        RMatches(self.matches(pat).0)
    }

    /// 对该字符串切片中某个模式的不相交匹配以及该匹配开始处的索引的迭代器。
    ///
    /// 对于 `self` 中重叠的 `pat` 匹配项，仅返回与第一个匹配项对应的索引。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 如果模式允许反向搜索且 forward/reverse 搜索产生相同的元素，则返回的迭代器将为 [`DoubleEndedIterator`]。
    /// 例如，对于 [`char`]，这是正确的，但对于 `&str`，则不是。
    ///
    /// 如果模式允许反向搜索，但其结果可能与正向搜索不同，则可以使用 [`rmatch_indices`] 方法。
    ///
    /// [`rmatch_indices`]: str::rmatch_indices
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
    /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
    ///
    /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
    /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
    ///
    /// let v: Vec<_> = "ababa".match_indices("aba").collect();
    /// assert_eq!(v, [(0, "aba")]); // 只有第一个 `aba`
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "str_match_indices", since = "1.5.0")]
    #[inline]
    pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> {
        MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
    }

    /// `self` 中某个模式的不相交匹配项上的迭代器，以与匹配项索引相反的顺序产生。
    ///
    /// 对于 `self` 中的 `pat` 重叠的匹配项，仅返回与最后一个匹配项对应的索引。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 迭代器行为
    ///
    /// 返回的迭代器要求模式支持反向搜索，如果 forward/reverse 搜索产生相同的元素，它将是 [`DoubleEndedIterator`]。
    ///
    ///
    /// 为了从正面进行迭代，可以使用 [`match_indices`] 方法。
    ///
    /// [`match_indices`]: str::match_indices
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
    /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
    ///
    /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
    /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
    ///
    /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
    /// assert_eq!(v, [(2, "aba")]); // 只有最后的 `aba`
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "str_match_indices", since = "1.5.0")]
    #[inline]
    pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        RMatchIndices(self.match_indices(pat).0)
    }

    /// 返回除去前导和尾随空格的字符串切片。
    ///
    /// 'Whitespace' 是根据 Unicode 派生的核心属性 `White_Space` 的术语定义的，该属性包括换行符。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = "\n Hello\tworld\t\n";
    ///
    /// assert_eq!("Hello\tworld", s.trim());
    /// ```
    #[inline]
    #[must_use = "this returns the trimmed string as a slice, \
                  without modifying the original"]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim")]
    pub fn trim(&self) -> &str {
        self.trim_matches(|c: char| c.is_whitespace())
    }

    /// 返回除去前导空格的字符串切片。
    ///
    /// 'Whitespace' 是根据 Unicode 派生的核心属性 `White_Space` 的术语定义的，该属性包括换行符。
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// `start` 在此上下文中表示该字节字符串的第一个位置； 对于从左到右的语言 (例如英语或俄语)，这将是左侧; 对于从右到左的语言 (例如阿拉伯语或希伯来语)，这将是右侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = "\n Hello\tworld\t\n";
    /// assert_eq!("Hello\tworld\t\n", s.trim_start());
    /// ```
    ///
    /// Directionality:
    ///
    /// ```
    /// let s = "  English  ";
    /// assert!(Some('E') == s.trim_start().chars().next());
    ///
    /// let s = "  עברית  ";
    /// assert!(Some('ע') == s.trim_start().chars().next());
    /// ```
    ///
    ///
    #[inline]
    #[must_use = "this returns the trimmed string as a new slice, \
                  without modifying the original"]
    #[stable(feature = "trim_direction", since = "1.30.0")]
    #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim_start")]
    pub fn trim_start(&self) -> &str {
        self.trim_start_matches(|c: char| c.is_whitespace())
    }

    /// 返回除去尾随空格的字符串切片。
    ///
    /// 'Whitespace' 是根据 Unicode 派生的核心属性 `White_Space` 的术语定义的，该属性包括换行符。
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// `end` 在此上下文中表示该字节字符串的最后位置； 对于从左到右的语言 (例如英语或俄语)，这将在右侧; 对于从右到左的语言 (例如阿拉伯语或希伯来语)，将在左侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = "\n Hello\tworld\t\n";
    /// assert_eq!("\n Hello\tworld", s.trim_end());
    /// ```
    ///
    /// Directionality:
    ///
    /// ```
    /// let s = "  English  ";
    /// assert!(Some('h') == s.trim_end().chars().rev().next());
    ///
    /// let s = "  עברית  ";
    /// assert!(Some('ת') == s.trim_end().chars().rev().next());
    /// ```
    ///
    ///
    #[inline]
    #[must_use = "this returns the trimmed string as a new slice, \
                  without modifying the original"]
    #[stable(feature = "trim_direction", since = "1.30.0")]
    #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim_end")]
    pub fn trim_end(&self) -> &str {
        self.trim_end_matches(|c: char| c.is_whitespace())
    }

    /// 返回除去前导空格的字符串切片。
    ///
    /// 'Whitespace' 是根据 Unicode 派生核心属性 `White_Space` 的条款定义的。
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// 'Left' 在此上下文中表示该字节字符串的第一个位置； 对于像阿拉伯语或希伯来语这样从右到左而不是从左到右的语言，这将是右侧，而不是左侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = " Hello\tworld\t";
    ///
    /// assert_eq!("Hello\tworld\t", s.trim_left());
    /// ```
    ///
    /// Directionality:
    ///
    /// ```
    /// let s = "  English";
    /// assert!(Some('E') == s.trim_left().chars().next());
    ///
    /// let s = "  עברית";
    /// assert!(Some('ע') == s.trim_left().chars().next());
    /// ```
    ///
    ///
    #[must_use = "this returns the trimmed string as a new slice, \
                  without modifying the original"]
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[deprecated(since = "1.33.0", note = "superseded by `trim_start`", suggestion = "trim_start")]
    pub fn trim_left(&self) -> &str {
        self.trim_start()
    }

    /// 返回除去尾随空格的字符串切片。
    ///
    /// 'Whitespace' 是根据 Unicode 派生核心属性 `White_Space` 的条款定义的。
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// 'Right' 在此上下文中表示该字节字符串的最后位置； 对于像阿拉伯语或希伯来语这样从右到左而不是从左到右的语言，这将是左侧，而不是右侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// let s = " Hello\tworld\t";
    ///
    /// assert_eq!(" Hello\tworld", s.trim_right());
    /// ```
    ///
    /// Directionality:
    ///
    /// ```
    /// let s = "English  ";
    /// assert!(Some('h') == s.trim_right().chars().rev().next());
    ///
    /// let s = "עברית  ";
    /// assert!(Some('ת') == s.trim_right().chars().rev().next());
    /// ```
    ///
    ///
    #[must_use = "this returns the trimmed string as a new slice, \
                  without modifying the original"]
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[deprecated(since = "1.33.0", note = "superseded by `trim_end`", suggestion = "trim_end")]
    pub fn trim_right(&self) -> &str {
        self.trim_end()
    }

    /// 返回具有与重复删除的模式匹配的所有前缀和后缀的字符串切片。
    ///
    /// [模式][pattern] 可以是 [`char`]、[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
    /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
    ///
    /// let x: &[_] = &['1', '2'];
    /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
    /// ```
    ///
    /// 使用闭包的更复杂的模式：
    ///
    /// ```
    /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
    /// ```
    ///
    #[must_use = "this returns the trimmed string as a new slice, \
                  without modifying the original"]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn trim_matches<'a, P>(&'a self, pat: P) -> &'a str
    where
        P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
    {
        let mut i = 0;
        let mut j = 0;
        let mut matcher = pat.into_searcher(self);
        if let Some((a, b)) = matcher.next_reject() {
            i = a;
            j = b; // 记住最早的已知比匹配，如果出现以下情况，请更正
            // 最后一个匹配不一样
        }
        if let Some((_, b)) = matcher.next_reject_back() {
            j = b;
        }
        // SAFETY: 已知 `Searcher` 返回有效索引。
        unsafe { self.get_unchecked(i..j) }
    }

    /// 返回字符串切片，该字符串切片的所有前缀都与重复删除的模式匹配。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// `start` 在此上下文中表示该字节字符串的第一个位置； 对于从左到右的语言 (例如英语或俄语)，这将是左侧; 对于从右到左的语言 (例如阿拉伯语或希伯来语)，这将是右侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
    /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
    ///
    /// let x: &[_] = &['1', '2'];
    /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
    /// ```
    ///
    ///
    ///
    #[must_use = "this returns the trimmed string as a new slice, \
                  without modifying the original"]
    #[stable(feature = "trim_direction", since = "1.30.0")]
    pub fn trim_start_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
        let mut i = self.len();
        let mut matcher = pat.into_searcher(self);
        if let Some((a, _)) = matcher.next_reject() {
            i = a;
        }
        // SAFETY: 已知 `Searcher` 返回有效索引。
        unsafe { self.get_unchecked(i..self.len()) }
    }

    /// 返回删除了前缀的字符串切片。
    ///
    /// 如果字符串以模式 `prefix` 开头，则返回前缀在 `Some` 中的子字符串。
    /// 与 `trim_start_matches` 不同，此方法只删除一次前缀。
    ///
    /// 如果字符串不是以 `prefix` 开头，则返回 `None`。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!("foo:bar".strip_prefix("foo:"), Some("bar"));
    /// assert_eq!("foo:bar".strip_prefix("bar"), None);
    /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
    /// ```
    #[must_use = "this returns the remaining substring as a new slice, \
                  without modifying the original"]
    #[stable(feature = "str_strip", since = "1.45.0")]
    pub fn strip_prefix<'a, P: Pattern<'a>>(&'a self, prefix: P) -> Option<&'a str> {
        prefix.strip_prefix_of(self)
    }

    /// 返回删除了后缀的字符串切片。
    ///
    /// 如果字符串以模式 `suffix` 结尾，则返回用 `Some` 包装的后缀之前的子字符串。
    /// 与 `trim_end_matches` 不同，此方法仅将后缀删除一次。
    ///
    /// 如果字符串不以 `suffix` 结尾，则返回 `None`。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # Examples
    ///
    /// ```
    /// assert_eq!("bar:foo".strip_suffix(":foo"), Some("bar"));
    /// assert_eq!("bar:foo".strip_suffix("bar"), None);
    /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
    /// ```
    #[must_use = "this returns the remaining substring as a new slice, \
                  without modifying the original"]
    #[stable(feature = "str_strip", since = "1.45.0")]
    pub fn strip_suffix<'a, P>(&'a self, suffix: P) -> Option<&'a str>
    where
        P: Pattern<'a>,
        <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,
    {
        suffix.strip_suffix_of(self)
    }

    /// 返回一个字符串切片，该字符串具有与重复删除的模式匹配的所有后缀。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// `end` 在此上下文中表示该字节字符串的最后位置； 对于从左到右的语言 (例如英语或俄语)，这将在右侧; 对于从右到左的语言 (例如阿拉伯语或希伯来语)，将在左侧。
    ///
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
    /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
    ///
    /// let x: &[_] = &['1', '2'];
    /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");
    /// ```
    ///
    /// 使用闭包的更复杂的模式：
    ///
    /// ```
    /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo");
    /// ```
    ///
    ///
    ///
    #[must_use = "this returns the trimmed string as a new slice, \
                  without modifying the original"]
    #[stable(feature = "trim_direction", since = "1.30.0")]
    pub fn trim_end_matches<'a, P>(&'a self, pat: P) -> &'a str
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        let mut j = 0;
        let mut matcher = pat.into_searcher(self);
        if let Some((_, b)) = matcher.next_reject_back() {
            j = b;
        }
        // SAFETY: 已知 `Searcher` 返回有效索引。
        unsafe { self.get_unchecked(0..j) }
    }

    /// 返回字符串切片，该字符串切片的所有前缀都与重复删除的模式匹配。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// 'Left' 在此上下文中表示该字节字符串的第一个位置； 对于像阿拉伯语或希伯来语这样从右到左而不是从左到右的语言，这将是右侧，而不是左侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法：
    ///
    /// ```
    /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
    /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
    ///
    /// let x: &[_] = &['1', '2'];
    /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[deprecated(
        since = "1.33.0",
        note = "superseded by `trim_start_matches`",
        suggestion = "trim_start_matches"
    )]
    pub fn trim_left_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
        self.trim_start_matches(pat)
    }

    /// 返回一个字符串切片，该字符串具有与重复删除的模式匹配的所有后缀。
    ///
    /// [模式][pattern] 可以是 `&str`，[`char`]，[`char`] 的切片，也可以是确定字符是否匹配的函数或闭包。
    ///
    /// [`char`]: prim@char
    /// [pattern]: self::pattern
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// 'Right' 在此上下文中表示该字节字符串的最后位置； 对于像阿拉伯语或希伯来语这样从右到左而不是从左到右的语言，这将是左侧，而不是右侧。
    ///
    ///
    /// # Examples
    ///
    /// 简单模式：
    ///
    /// ```
    /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
    /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
    ///
    /// let x: &[_] = &['1', '2'];
    /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
    /// ```
    ///
    /// 使用闭包的更复杂的模式：
    ///
    /// ```
    /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo");
    /// ```
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[deprecated(
        since = "1.33.0",
        note = "superseded by `trim_end_matches`",
        suggestion = "trim_end_matches"
    )]
    pub fn trim_right_matches<'a, P>(&'a self, pat: P) -> &'a str
    where
        P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
    {
        self.trim_end_matches(pat)
    }

    /// 将此字符串切片解析为另一种类型。
    ///
    /// 由于 `parse` 非常通用，因此可能导致类型推断问题。
    /// 因此，`parse` 是少数几次您会看到被亲切地称为 'turbofish': `::<>` 的语法之一。
    ///
    /// 这可以帮助推理算法特别了解您要解析为哪种类型。
    ///
    /// `parse` 可以解析为任何实现 [`FromStr`] trait 的类型。
    ///

    /// # Errors
    ///
    /// 如果无法将此字符串切片解析为所需的类型，则将返回 [`Err`]。
    ///
    ///
    /// [`Err`]: FromStr::Err
    ///
    /// # Examples
    ///
    /// 基本用法
    ///
    /// ```
    /// let four: u32 = "4".parse().unwrap();
    ///
    /// assert_eq!(4, four);
    /// ```
    ///
    /// 使用 'turbofish' 而不是注解 `four`：
    ///
    /// ```
    /// let four = "4".parse::<u32>();
    ///
    /// assert_eq!(Ok(4), four);
    /// ```
    ///
    /// 无法解析：
    ///
    /// ```
    /// let nope = "j".parse::<u32>();
    ///
    /// assert!(nope.is_err());
    /// ```
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn parse<F: FromStr>(&self) -> Result<F, F::Err> {
        FromStr::from_str(self)
    }

    /// 检查此字符串中的所有字符是否都在 ASCII 范围内。
    ///
    /// # Examples
    ///
    /// ```
    /// let ascii = "hello!\n";
    /// let non_ascii = "Grüße, Jürgen ❤";
    ///
    /// assert!(ascii.is_ascii());
    /// assert!(!non_ascii.is_ascii());
    /// ```
    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
    #[rustc_const_unstable(feature = "const_slice_is_ascii", issue = "111090")]
    #[must_use]
    #[inline]
    pub const fn is_ascii(&self) -> bool {
        // 我们可以在这里将每个字节视为字符: 所有多字节字符都以一个不在 ASCII 范围内的字节开头，所以我们已经停止了。
        //
        //
        self.as_bytes().is_ascii()
    }

    /// 如果此字符串切片 [`is_ascii`](Self::is_ascii)，则将其作为 [ASCII characters](`ascii::Char`) 的切片返回，否则返回 `None`。
    ///
    #[unstable(feature = "ascii_char", issue = "110998")]
    #[must_use]
    #[inline]
    pub const fn as_ascii(&self) -> Option<&[ascii::Char]> {
        // 就像在 `is_ascii` 中一样，我们可以直接处理字节。
        self.as_bytes().as_ascii()
    }

    /// 检查两个字符串是否为 ASCII 不区分大小写的匹配项。
    ///
    /// 与 `to_ascii_lowercase(a) == to_ascii_lowercase(b)` 相同，但不分配和复制临时文件。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
    /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
    /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
    /// ```
    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
    #[must_use]
    #[inline]
    pub fn eq_ignore_ascii_case(&self, other: &str) -> bool {
        self.as_bytes().eq_ignore_ascii_case(other.as_bytes())
    }

    /// 将此字符串就地转换为其 ASCII 大写等效项。
    ///
    /// ASCII 字母 'a' 到 'z' 映射到 'A' 到 'Z'，但是非 ASCII 字母不变。
    ///
    /// 要返回新的大写值而不修改现有值，请使用 [`to_ascii_uppercase()`]。
    ///
    ///
    /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
    ///
    /// # Examples
    ///
    /// ```
    /// let mut s = String::from("Grüße, Jürgen ❤");
    ///
    /// s.make_ascii_uppercase();
    ///
    /// assert_eq!("GRüßE, JüRGEN ❤", s);
    /// ```
    ///
    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
    #[inline]
    pub fn make_ascii_uppercase(&mut self) {
        // SAFETY: 仅更改 ASCII 字母不会使 UTF-8 无效。
        let me = unsafe { self.as_bytes_mut() };
        me.make_ascii_uppercase()
    }

    /// 将此字符串就地转换为其 ASCII 小写等效项。
    ///
    /// ASCII 字母 'A' 到 'Z' 映射到 'a' 到 'z'，但是非 ASCII 字母不变。
    ///
    /// 要返回新的小写值而不修改现有值，请使用 [`to_ascii_lowercase()`]。
    ///
    ///
    /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
    ///
    /// # Examples
    ///
    /// ```
    /// let mut s = String::from("GRÜßE, JÜRGEN ❤");
    ///
    /// s.make_ascii_lowercase();
    ///
    /// assert_eq!("grÜße, jÜrgen ❤", s);
    /// ```
    ///
    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
    #[inline]
    pub fn make_ascii_lowercase(&mut self) {
        // SAFETY: 仅更改 ASCII 字母不会使 UTF-8 无效。
        let me = unsafe { self.as_bytes_mut() };
        me.make_ascii_lowercase()
    }

    /// 返回一个迭代器，该迭代器使用 [`char::escape_debug`] 对 `self` 中的每个字符进行转义。
    ///
    ///
    /// Note: 只有以字符串开头的扩展字素代码点将被转义。
    ///
    /// # Examples
    ///
    /// 作为迭代器：
    ///
    /// ```
    /// for c in "❤\n!".escape_debug() {
    ///     print!("{c}");
    /// }
    /// println!();
    /// ```
    ///
    /// 直接使用 `println!`：
    ///
    /// ```
    /// println!("{}", "❤\n!".escape_debug());
    /// ```
    ///
    /// 两者都等同于：
    ///
    /// ```
    /// println!("❤\\n!");
    /// ```
    ///
    /// 使用 `to_string`：
    ///
    /// ```
    /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!");
    /// ```
    ///
    #[must_use = "this returns the escaped string as an iterator, \
                  without modifying the original"]
    #[stable(feature = "str_escape", since = "1.34.0")]
    pub fn escape_debug(&self) -> EscapeDebug<'_> {
        let mut chars = self.chars();
        EscapeDebug {
            inner: chars
                .next()
                .map(|first| first.escape_debug_ext(EscapeDebugExtArgs::ESCAPE_ALL))
                .into_iter()
                .flatten()
                .chain(chars.flat_map(CharEscapeDebugContinue)),
        }
    }

    /// 返回一个迭代器，该迭代器使用 [`char::escape_default`] 对 `self` 中的每个字符进行转义。
    ///
    /// # Examples
    ///
    /// 作为迭代器：
    ///
    /// ```
    /// for c in "❤\n!".escape_default() {
    ///     print!("{c}");
    /// }
    /// println!();
    /// ```
    ///
    /// 直接使用 `println!`：
    ///
    /// ```
    /// println!("{}", "❤\n!".escape_default());
    /// ```
    ///
    ///
    /// 两者都等同于：
    ///
    /// ```
    /// println!("\\u{{2764}}\\n!");
    /// ```
    ///
    /// 使用 `to_string`：
    ///
    /// ```
    /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
    /// ```
    #[must_use = "this returns the escaped string as an iterator, \
                  without modifying the original"]
    #[stable(feature = "str_escape", since = "1.34.0")]
    pub fn escape_default(&self) -> EscapeDefault<'_> {
        EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
    }

    /// 返回一个迭代器，该迭代器使用 [`char::escape_unicode`] 对 `self` 中的每个字符进行转义。
    ///
    /// # Examples
    ///
    /// 作为迭代器：
    ///
    /// ```
    /// for c in "❤\n!".escape_unicode() {
    ///     print!("{c}");
    /// }
    /// println!();
    /// ```
    ///
    /// 直接使用 `println!`：
    ///
    /// ```
    /// println!("{}", "❤\n!".escape_unicode());
    /// ```
    ///
    ///
    /// 两者都等同于：
    ///
    /// ```
    /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
    /// ```
    ///
    /// 使用 `to_string`：
    ///
    /// ```
    /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
    /// ```
    #[must_use = "this returns the escaped string as an iterator, \
                  without modifying the original"]
    #[stable(feature = "str_escape", since = "1.34.0")]
    pub fn escape_unicode(&self) -> EscapeUnicode<'_> {
        EscapeUnicode { inner: self.chars().flat_map(CharEscapeUnicode) }
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl AsRef<[u8]> for str {
    #[inline]
    fn as_ref(&self) -> &[u8] {
        self.as_bytes()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Default for &str {
    /// 创建一个空的 str
    #[inline]
    fn default() -> Self {
        ""
    }
}

#[stable(feature = "default_mut_str", since = "1.28.0")]
impl Default for &mut str {
    /// 创建一个空的可变 str
    #[inline]
    fn default() -> Self {
        // SAFETY: 空字符串是有效的 UTF-8。
        unsafe { from_utf8_unchecked_mut(&mut []) }
    }
}

impl_fn_for_zst! {
    /// 可命名，可克隆的 fn 类型
    #[derive(Clone)]
    struct LinesMap impl<'a> Fn = |line: &'a str| -> &'a str {
        let Some(line) = line.strip_suffix('\n') else { return line };
        let Some(line) = line.strip_suffix('\r') else { return line };
        line
    };

    #[derive(Clone)]
    struct CharEscapeDebugContinue impl Fn = |c: char| -> char::EscapeDebug {
        c.escape_debug_ext(EscapeDebugExtArgs {
            escape_grapheme_extended: false,
            escape_single_quote: true,
            escape_double_quote: true
        })
    };

    #[derive(Clone)]
    struct CharEscapeUnicode impl Fn = |c: char| -> char::EscapeUnicode {
        c.escape_unicode()
    };
    #[derive(Clone)]
    struct CharEscapeDefault impl Fn = |c: char| -> char::EscapeDefault {
        c.escape_default()
    };

    #[derive(Clone)]
    struct IsWhitespace impl Fn = |c: char| -> bool {
        c.is_whitespace()
    };

    #[derive(Clone)]
    struct IsAsciiWhitespace impl Fn = |byte: &u8| -> bool {
        byte.is_ascii_whitespace()
    };

    #[derive(Clone)]
    struct IsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b str| -> bool {
        !s.is_empty()
    };

    #[derive(Clone)]
    struct BytesIsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b [u8]| -> bool {
        !s.is_empty()
    };

    #[derive(Clone)]
    struct UnsafeBytesToStr impl<'a> Fn = |bytes: &'a [u8]| -> &'a str {
        // SAFETY: 不安全
        unsafe { from_utf8_unchecked(bytes) }
    };
}

// 这是为了使 Box<dyn Error>` 的 impl From<&str> 和 Box<dyn Error>` 的 `impl<E> From<E> 不重叠。
#[stable(feature = "rust1", since = "1.0.0")]
impl !crate::error::Error for &str {}