//! `str` 的 Trait 实现。

use crate::cmp::Ordering;
use crate::ops;
use crate::ptr;
use crate::slice::SliceIndex;

use super::ParseBoolError;

/// 实现字符串排序。
///
/// 字符串按字节值按 [lexicographically](Ord#lexicographical-comparison) 排序。
/// 这将根据 Unicode 代码点在代码图中的位置进行排序。
/// 这不一定与 "alphabetical" 顺序相同，后者因语言和区域设置而异。
/// 根据文化认可的标准对字符串进行排序需要 `str` 类型的作用域之外的特定于语言环境的数据。
///
#[stable(feature = "rust1", since = "1.0.0")]
impl Ord for str {
    #[inline]
    fn cmp(&self, other: &str) -> Ordering {
        self.as_bytes().cmp(other.as_bytes())
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl PartialEq for str {
    #[inline]
    fn eq(&self, other: &str) -> bool {
        self.as_bytes() == other.as_bytes()
    }
    #[inline]
    fn ne(&self, other: &str) -> bool {
        !(*self).eq(other)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl Eq for str {}

/// 对字符串执行比较操作。
///
/// [lexicographically](Ord#lexicographical-comparison) 通过字符串的字节值对字符串进行比较。
/// 这将根据 Unicode 代码点在代码表中的位置进行比较。
/// 这不一定与 "alphabetical" 顺序相同，后者因语言和区域设置而异。
/// 根据文化认可的标准比较字符串需要特定于语言环境的数据，该数据不在 `str` 类型的作用域之内。
///
#[stable(feature = "rust1", since = "1.0.0")]
impl PartialOrd for str {
    #[inline]
    fn partial_cmp(&self, other: &str) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<I> ops::Index<I> for str
where
    I: SliceIndex<str>,
{
    type Output = I::Output;

    #[inline]
    fn index(&self, index: I) -> &I::Output {
        index.index(self)
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl<I> ops::IndexMut<I> for str
where
    I: SliceIndex<str>,
{
    #[inline]
    fn index_mut(&mut self, index: I) -> &mut I::Output {
        index.index_mut(self)
    }
}

#[inline(never)]
#[cold]
#[track_caller]
fn str_index_overflow_fail() -> ! {
    panic!("attempted to index str up to maximum usize");
}

/// 使用语法 `&self[..]` 或 `&mut self[..]` 实现子字符串切片。
///
/// 返回整个字符串的片段，即返回 `&self` 或 `&mut self`。相当于 `&self[0 ..
/// len]` 或 `&mut self[0 ..
/// len]`.
/// 与其他索引操作不同，此操作永远不能 panic。
///
/// 此运算为 *O*(1)。
///
/// 在 1.20.0 之前，`Index` 和 `IndexMut` 的直接实现仍支持这些索引操作。
///
/// 等效于 `&self[0 .. len]` 或 `&mut self[0 .. len]`。
#[stable(feature = "str_checked_slicing", since = "1.20.0")]
unsafe impl SliceIndex<str> for ops::RangeFull {
    type Output = str;
    #[inline]
    fn get(self, slice: &str) -> Option<&Self::Output> {
        Some(slice)
    }
    #[inline]
    fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
        Some(slice)
    }
    #[inline]
    unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output {
        slice
    }
    #[inline]
    unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output {
        slice
    }
    #[inline]
    fn index(self, slice: &str) -> &Self::Output {
        slice
    }
    #[inline]
    fn index_mut(self, slice: &mut str) -> &mut Self::Output {
        slice
    }
}

/// 使用语法 `&self[begin .. end]` 或 `&mut self[begin .. end]` 实现子字符串切片。
///
/// 从字节范围 [`begin，`end`) 返回给定字符串的片段。
///
/// 此运算为 *O*(1)。
///
/// 在 1.20.0 之前，`Index` 和 `IndexMut` 的直接实现仍支持这些索引操作。
///
/// # Panics
///
/// 如果 `begin` 或 `end` 未指向字符的起始字节偏移量 (由 `is_char_boundary` 定义)，`begin > end` 或 `end > len`，则为 Panics。
///
///
/// # Examples
///
/// ```
/// let s = "Löwe 老虎 Léopard";
/// assert_eq!(&s[0 .. 1], "L");
///
/// assert_eq!(&s[1 .. 9], "öwe 老");
///
/// // 这些将是 panic:
/// // 字节 2 位于 `ö` 内:
/// // &s[2 ..3];
///
/// // byte 8 lies within `老` &s[1 ..
/// // 8];
///
/// // 字节 100 在字符串 &s[3 之外。
/// // 100];
/// ```
///
///
///
///
#[stable(feature = "str_checked_slicing", since = "1.20.0")]
unsafe impl SliceIndex<str> for ops::Range<usize> {
    type Output = str;
    #[inline]
    fn get(self, slice: &str) -> Option<&Self::Output> {
        if self.start <= self.end
            && slice.is_char_boundary(self.start)
            && slice.is_char_boundary(self.end)
        {
            // SAFETY: 刚刚检查了 `start` 和 `end` 是否在 char 边界上，并且我们传入了安全的引用，因此返回值也将为 1。
            //
            // 我们还检查了字符边界，因此这是有效的 UTF-8。
            Some(unsafe { &*self.get_unchecked(slice) })
        } else {
            None
        }
    }
    #[inline]
    fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
        if self.start <= self.end
            && slice.is_char_boundary(self.start)
            && slice.is_char_boundary(self.end)
        {
            // SAFETY: 刚刚检查 `start` 和 `end` 是否在字符边界上。
            // 我们知道指针是唯一的，因为我们是从 `slice` 获得的。
            Some(unsafe { &mut *self.get_unchecked_mut(slice) })
        } else {
            None
        }
    }
    #[inline]
    unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output {
        let slice = slice as *const [u8];
        // SAFETY: 调用方保证 `self` 在 `slice` 的范围内，该范围满足 `add` 的所有条件。
        //
        let ptr = unsafe { slice.as_ptr().add(self.start) };
        let len = self.end - self.start;
        ptr::slice_from_raw_parts(ptr, len) as *const str
    }
    #[inline]
    unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output {
        let slice = slice as *mut [u8];
        // SAFETY: 请参见 `get_unchecked` 的注释。
        let ptr = unsafe { slice.as_mut_ptr().add(self.start) };
        let len = self.end - self.start;
        ptr::slice_from_raw_parts_mut(ptr, len) as *mut str
    }
    #[inline]
    fn index(self, slice: &str) -> &Self::Output {
        let (start, end) = (self.start, self.end);
        match self.get(slice) {
            Some(s) => s,
            None => super::slice_error_fail(slice, start, end),
        }
    }
    #[inline]
    fn index_mut(self, slice: &mut str) -> &mut Self::Output {
        // is_char_boundary 由于 NLL 问题而无法检查索引是否位于 [0, .len()] 中，因此无法如上所述重用 `get`
        //
        if self.start <= self.end
            && slice.is_char_boundary(self.start)
            && slice.is_char_boundary(self.end)
        {
            // SAFETY: 刚刚检查了 `start` 和 `end` 是否在 char 边界上，并且我们传入了安全的引用，因此返回值也将为 1。
            //
            unsafe { &mut *self.get_unchecked_mut(slice) }
        } else {
            super::slice_error_fail(slice, self.start, self.end)
        }
    }
}

/// 使用语法 `&self[.. end]` 或 `&mut self[.. end]` 实现子字符串切片。
///
/// 从字节范围 [`0`，`end`) 返回给定字符串的片段。
/// 等效于 `&self[0 .. end]` 或 `&mut self[0 .. end]`。
///
/// 此运算为 *O*(1)。
///
/// 在 1.20.0 之前，`Index` 和 `IndexMut` 的直接实现仍支持这些索引操作。
///
/// # Panics
///
/// 如果 `end` 没有指向字符的起始字节偏移量 (由 `is_char_boundary` 定义)，或者 `end > len`，则为 Panics。
///
///
///
#[stable(feature = "str_checked_slicing", since = "1.20.0")]
unsafe impl SliceIndex<str> for ops::RangeTo<usize> {
    type Output = str;
    #[inline]
    fn get(self, slice: &str) -> Option<&Self::Output> {
        if slice.is_char_boundary(self.end) {
            // SAFETY: 刚刚检查了 `end` 是否在 char 边界上，并且我们传递了一个安全的引用，因此返回值也将为 1。
            //
            Some(unsafe { &*self.get_unchecked(slice) })
        } else {
            None
        }
    }
    #[inline]
    fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
        if slice.is_char_boundary(self.end) {
            // SAFETY: 刚刚检查了 `end` 是否在 char 边界上，并且我们传递了一个安全的引用，因此返回值也将为 1。
            //
            Some(unsafe { &mut *self.get_unchecked_mut(slice) })
        } else {
            None
        }
    }
    #[inline]
    unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output {
        let slice = slice as *const [u8];
        let ptr = slice.as_ptr();
        ptr::slice_from_raw_parts(ptr, self.end) as *const str
    }
    #[inline]
    unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output {
        let slice = slice as *mut [u8];
        let ptr = slice.as_mut_ptr();
        ptr::slice_from_raw_parts_mut(ptr, self.end) as *mut str
    }
    #[inline]
    fn index(self, slice: &str) -> &Self::Output {
        let end = self.end;
        match self.get(slice) {
            Some(s) => s,
            None => super::slice_error_fail(slice, 0, end),
        }
    }
    #[inline]
    fn index_mut(self, slice: &mut str) -> &mut Self::Output {
        if slice.is_char_boundary(self.end) {
            // SAFETY: 刚刚检查了 `end` 是否在 char 边界上，并且我们传递了一个安全的引用，因此返回值也将为 1。
            //
            unsafe { &mut *self.get_unchecked_mut(slice) }
        } else {
            super::slice_error_fail(slice, 0, self.end)
        }
    }
}

/// 使用语法 `&self[begin ..]` 或 `&mut self[begin ..]` 实现子字符串切片。
///
/// 从字节范围 [`begin，`len`) 返回给定字符串的片段。等同于 `&self[begin ..
/// len]` 或 `&mut self[begin ..
/// len]`.
///
/// 此运算为 *O*(1)。
///
/// 在 1.20.0 之前，`Index` 和 `IndexMut` 的直接实现仍支持这些索引操作。
///
/// # Panics
///
/// 如果 `begin` 没有指向字符的起始字节偏移量 (由 `is_char_boundary` 定义)，或者 `begin > len`，则为 Panics。
///
///
///
#[stable(feature = "str_checked_slicing", since = "1.20.0")]
unsafe impl SliceIndex<str> for ops::RangeFrom<usize> {
    type Output = str;
    #[inline]
    fn get(self, slice: &str) -> Option<&Self::Output> {
        if slice.is_char_boundary(self.start) {
            // SAFETY: 刚刚检查了 `start` 是否在 char 边界上，并且我们传递了一个安全的引用，因此返回值也将为 1。
            //
            Some(unsafe { &*self.get_unchecked(slice) })
        } else {
            None
        }
    }
    #[inline]
    fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
        if slice.is_char_boundary(self.start) {
            // SAFETY: 刚刚检查了 `start` 是否在 char 边界上，并且我们传递了一个安全的引用，因此返回值也将为 1。
            //
            Some(unsafe { &mut *self.get_unchecked_mut(slice) })
        } else {
            None
        }
    }
    #[inline]
    unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output {
        let slice = slice as *const [u8];
        // SAFETY: 调用方保证 `self` 在 `slice` 的范围内，该范围满足 `add` 的所有条件。
        //
        let ptr = unsafe { slice.as_ptr().add(self.start) };
        let len = slice.len() - self.start;
        ptr::slice_from_raw_parts(ptr, len) as *const str
    }
    #[inline]
    unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output {
        let slice = slice as *mut [u8];
        // SAFETY: 与 `get_unchecked` 相同。
        let ptr = unsafe { slice.as_mut_ptr().add(self.start) };
        let len = slice.len() - self.start;
        ptr::slice_from_raw_parts_mut(ptr, len) as *mut str
    }
    #[inline]
    fn index(self, slice: &str) -> &Self::Output {
        let (start, end) = (self.start, slice.len());
        match self.get(slice) {
            Some(s) => s,
            None => super::slice_error_fail(slice, start, end),
        }
    }
    #[inline]
    fn index_mut(self, slice: &mut str) -> &mut Self::Output {
        if slice.is_char_boundary(self.start) {
            // SAFETY: 刚刚检查了 `start` 是否在 char 边界上，并且我们传递了一个安全的引用，因此返回值也将为 1。
            //
            unsafe { &mut *self.get_unchecked_mut(slice) }
        } else {
            super::slice_error_fail(slice, self.start, slice.len())
        }
    }
}

/// 使用语法 `&self[begin ..= end]` 或 `&mut self[begin ..= end]` 实现子字符串切片。
///
/// 从字节范围 [`begin`, `end`] 返回给定字符串的片段。等效于 `&self [begin .. end + 1]` 或 `&mut self[begin .. end + 1]`，除非 `end` 具有 `usize` 的最大值。
///
/// 此运算为 *O*(1)。
///
/// # Panics
///
/// Panics，如果 `begin` 不指向字符的起始字节偏移 (由 `is_char_boundary` 定义)，如果 `end` 不指向字符的终止字节偏移 (`end + 1` 是起始字节偏移或等于 `len`)，如果 `begin > end`，如果是 `end >= len`。
///
///
///
///
///
///
///
#[stable(feature = "inclusive_range", since = "1.26.0")]
unsafe impl SliceIndex<str> for ops::RangeInclusive<usize> {
    type Output = str;
    #[inline]
    fn get(self, slice: &str) -> Option<&Self::Output> {
        if *self.end() == usize::MAX { None } else { self.into_slice_range().get(slice) }
    }
    #[inline]
    fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
        if *self.end() == usize::MAX { None } else { self.into_slice_range().get_mut(slice) }
    }
    #[inline]
    unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output {
        // SAFETY: 调用者必须坚持 `get_unchecked` 的安全保证。
        unsafe { self.into_slice_range().get_unchecked(slice) }
    }
    #[inline]
    unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output {
        // SAFETY: 调用者必须坚持 `get_unchecked_mut` 的安全保证。
        unsafe { self.into_slice_range().get_unchecked_mut(slice) }
    }
    #[inline]
    fn index(self, slice: &str) -> &Self::Output {
        if *self.end() == usize::MAX {
            str_index_overflow_fail();
        }
        self.into_slice_range().index(slice)
    }
    #[inline]
    fn index_mut(self, slice: &mut str) -> &mut Self::Output {
        if *self.end() == usize::MAX {
            str_index_overflow_fail();
        }
        self.into_slice_range().index_mut(slice)
    }
}

/// 使用语法 `&self[..= end]` 或 `&mut self[..= end]` 实现子字符串切片。
///
/// 从字节范围 [0, `end`] 返回给定字符串的片段。
/// 等效于 `&self [0 .. end + 1]`，除非 `end` 具有 `usize` 的最大值。
///
/// 此运算为 *O*(1)。
///
/// # Panics
///
/// 如果 `end` 没有指向字符的结束字节偏移量 (`end + 1` 是 `is_char_boundary` 定义的起始字节偏移量，或者等于 `len`)，或者如果 `end >= len`，则为 Panics。
///
///
///
///
#[stable(feature = "inclusive_range", since = "1.26.0")]
unsafe impl SliceIndex<str> for ops::RangeToInclusive<usize> {
    type Output = str;
    #[inline]
    fn get(self, slice: &str) -> Option<&Self::Output> {
        if self.end == usize::MAX { None } else { (..self.end + 1).get(slice) }
    }
    #[inline]
    fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
        if self.end == usize::MAX { None } else { (..self.end + 1).get_mut(slice) }
    }
    #[inline]
    unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output {
        // SAFETY: 调用者必须坚持 `get_unchecked` 的安全保证。
        unsafe { (..self.end + 1).get_unchecked(slice) }
    }
    #[inline]
    unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output {
        // SAFETY: 调用者必须坚持 `get_unchecked_mut` 的安全保证。
        unsafe { (..self.end + 1).get_unchecked_mut(slice) }
    }
    #[inline]
    fn index(self, slice: &str) -> &Self::Output {
        if self.end == usize::MAX {
            str_index_overflow_fail();
        }
        (..self.end + 1).index(slice)
    }
    #[inline]
    fn index_mut(self, slice: &mut str) -> &mut Self::Output {
        if self.end == usize::MAX {
            str_index_overflow_fail();
        }
        (..self.end + 1).index_mut(slice)
    }
}

/// 解析字符串中的值
///
/// FromStr 的 [`from_str`] 方法通常通过 [`str`] 的 [`parse`] 方法隐式使用。
/// 有关示例，请参见 [`parse`] 的文档。
///
/// [`from_str`]: FromStr::from_str
/// [`parse`]: str::parse
///
/// `FromStr` 没有生命周期参数，因此您只能解析本身不包含生命周期参数的类型。
///
/// 换句话说，您可以使用 `FromStr` 解析 `i32`，但是不能解析 `&i32`。
/// 您可以解析包含 `i32` 的结构体，但不能解析包含 `&i32` 的结构体。
///
/// # Examples
///
/// `FromStr` 在示例 `Point` 类型上的基本实现:
///
/// ```
/// use std::str::FromStr;
/// use std::num::ParseIntError;
///
/// #[derive(Debug, PartialEq)]
/// struct Point {
///     x: i32,
///     y: i32
/// }
///
/// impl FromStr for Point {
///     type Err = ParseIntError;
///
///     fn from_str(s: &str) -> Result<Self, Self::Err> {
///         let coords: Vec<&str> = s.trim_matches(|p| p == '(' || p == ')' )
///                                  .split(',')
///                                  .collect();
///
///         let x_fromstr = coords[0].parse::<i32>()?;
///         let y_fromstr = coords[1].parse::<i32>()?;
///
///         Ok(Point { x: x_fromstr, y: y_fromstr })
///     }
/// }
///
/// let p = Point::from_str("(1,2)");
/// assert_eq!(p.unwrap(), Point{ x: 1, y: 2} )
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait FromStr: Sized {
    /// 可以从解析中返回的相关错误。
    #[stable(feature = "rust1", since = "1.0.0")]
    type Err;

    /// 解析字符串 `s` 以返回此类型的值。
    ///
    /// 如果解析成功，则返回 [`Ok`] 内部的值，否则，当字符串格式错误时，返回特定于 [`Err`] 内部的错误。
    /// 错误类型特定于 trait 的实现。
    ///
    /// # Examples
    ///
    /// [`i32`] 的基本用法，一种实现 `FromStr` 的类型:
    ///
    /// ```
    /// use std::str::FromStr;
    ///
    /// let s = "5";
    /// let x = i32::from_str(s).unwrap();
    ///
    /// assert_eq!(5, x);
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    fn from_str(s: &str) -> Result<Self, Self::Err>;
}

#[stable(feature = "rust1", since = "1.0.0")]
impl FromStr for bool {
    type Err = ParseBoolError;

    /// 从字符串中解析 `bool`。
    ///
    /// 产生 `Result<bool, ParseBoolError>`，因为 `s` 实际上可以解析，也可以不解析。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::str::FromStr;
    ///
    /// assert_eq!(FromStr::from_str("true"), Ok(true));
    /// assert_eq!(FromStr::from_str("false"), Ok(false));
    /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
    /// ```
    ///
    /// 注意，在许多情况下，`str` 上的 `.parse()` 方法更合适。
    ///
    /// ```
    /// assert_eq!("true".parse(), Ok(true));
    /// assert_eq!("false".parse(), Ok(false));
    /// assert!("not even a boolean".parse::<bool>().is_err());
    /// ```
    #[inline]
    fn from_str(s: &str) -> Result<bool, ParseBoolError> {
        match s {
            "true" => Ok(true),
            "false" => Ok(false),
            _ => Err(ParseBoolError),
        }
    }
}