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

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

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

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

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

pub mod pattern;

#[unstable(feature = "str_internals", issue = "none")]
#[allow(missing_docs)]
pub mod lossy;

#[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;

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

use validations::truncate_to_char_boundary;

#[inline(never)]
#[cold]
#[track_caller]
fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
    const MAX_DISPLAY_LENGTH: usize = 256;
    let (truncated, s_trunc) = truncate_to_char_boundary(s, MAX_DISPLAY_LENGTH);
    let ellipsis = if truncated { "[...]" } else { "" };

    // 1. 越界
    if begin > s.len() || end > s.len() {
        let oob_index = if begin > s.len() { begin } else { end };
        panic!("byte index {} is out of bounds of `{}`{}", oob_index, 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 mut char_start = index;
    while !s.is_char_boundary(char_start) {
        char_start -= 1;
    }
    // `char_start` 必须小于 len 和 char 边界
    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
    );
}

#[lang = "str"]
#[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")]
    #[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());
    /// ```
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_const_stable(feature = "const_str_is_empty", since = "1.39.0")]
    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));
    /// ```
    ///
    #[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(),

            // 这有点神奇，等于: b <128 ||b>=192
            Some(&b) => (b as i8) >= -0x40,
        }
    }

    /// 将字符串切片转换为字节切片。
    /// 要将字节切片切回为字符串切片，请使用 [`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")]
    #[inline(always)]
    #[allow(unused_attributes)]
    #[rustc_allow_const_fn_unstable(const_fn_transmute)]
    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")]
    #[inline(always)]
    pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
        // SAFETY: 从 `&str` 到 `&[u8]` 的转换是安全的，因为 `str` 具有与 `&[u8]` 相同的布局 (只有 libstd 可以提供此保证)。
        //
        // 指针解引用是安全的，因为它来自变量引用，该变量对写操作有效。
        //
        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")]
    #[inline]
    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")]
    #[inline]
    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` 和 `end` 必须在字符串 `Slice` 中的字节位置。
    /// * `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")]
    #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked(begin..end)` instead")]
    #[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` 和 `end` 必须在字符串 `Slice` 中的字节位置。
    /// * `begin` 和 `end` 必须位于 UTF-8 序列边界上。
    ///
    ///
    ///
    ///
    #[stable(feature = "str_slice_mut", since = "1.5.0")]
    #[rustc_deprecated(since = "1.29.0", reason = "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
    ///
    /// Panics，如果 `mid` 不在 UTF-8 代码点边界上，或者超过字符串切片的最后一个代码点的末尾。
    ///
    ///
    /// # 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]
    #[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
    ///
    /// Panics，如果 `mid` 不在 UTF-8 代码点边界上，或者超过字符串切片的最后一个代码点的末尾。
    ///
    ///
    /// # 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]
    #[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());
    /// ```
    ///
    #[stable(feature = "split_whitespace", since = "1.1.0")]
    #[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());
    /// ```
    #[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_terminator('\n').map(LinesAnyMap))
    }

    /// 字符串行上的迭代器。
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_deprecated(since = "1.4.0", reason = "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);
    /// ```
    #[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", ""]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[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"]);
    /// ```
    ///
    ///
    ///
    ///
    ///
    ///
    #[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=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()?;
        Some((&self[..start], &self[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()?;
        Some((&self[..start], &self[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::match_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 = " Hello\tworld\t";
    ///
    /// 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")]
    pub fn trim(&self) -> &str {
        self.trim_matches(|c: char| c.is_whitespace())
    }

    /// 返回除去前导空格的字符串切片。
    ///
    /// 'Whitespace' 根据 Unicode 派生核心属性 `White_Space` 的术语定义。
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// `start` 在本文中，是指该字节字符串的第一个位置; 对于从左到右的语言 (例如英语或俄语)，这将是左侧; 对于从右到左的语言 (例如阿拉伯语或希伯来语)，这将是右侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// let s = " Hello\tworld\t";
    /// assert_eq!("Hello\tworld\t", 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")]
    pub fn trim_start(&self) -> &str {
        self.trim_start_matches(|c: char| c.is_whitespace())
    }

    /// 返回除去尾随空格的字符串切片。
    ///
    /// 'Whitespace' 根据 Unicode 派生核心属性 `White_Space` 的术语定义。
    ///
    /// # 文字方向性
    ///
    /// 字符串是字节序列。
    /// `end` 在本文中，是指该字节字符串的最后一个位置; 对于从左到右的语言 (例如英语或俄语)，这将在右侧; 对于从右到左的语言 (例如阿拉伯语或希伯来语)，将在左侧。
    ///
    ///
    /// # Examples
    ///
    /// 基本用法:
    ///
    /// ```
    /// let s = " Hello\tworld\t";
    /// assert_eq!(" 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")]
    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());
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_deprecated(
        since = "1.33.0",
        reason = "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());
    /// ```
    ///
    ///
    #[inline]
    #[stable(feature = "rust1", since = "1.0.0")]
    #[rustc_deprecated(
        since = "1.33.0",
        reason = "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")]
    #[rustc_deprecated(
        since = "1.33.0",
        reason = "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")]
    #[rustc_deprecated(
        since = "1.33.0",
        reason = "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")]
    #[inline]
    pub fn is_ascii(&self) -> bool {
        // 我们可以在这里将每个字节视为字符: 所有多字节字符都以一个不在 ascii 范围内的字节开头，因此我们将在此停止。
        //
        //
        self.as_bytes().is_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")]
    #[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: 之所以安全，是因为我们用相同的布局转换了两种类型。
        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: 之所以安全，是因为我们用相同的布局转换了两种类型。
        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!");
    /// ```
    ///
    #[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!");
    /// ```
    #[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}");
    /// ```
    #[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 LinesAnyMap impl<'a> Fn = |line: &'a str| -> &'a str {
        let l = line.len();
        if l > 0 && line.as_bytes()[l - 1] == b'\r' { &line[0 .. l - 1] }
        else { 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) }
    };
}