use crate::fmt;
use crate::fmt::Formatter;
use crate::fmt::Write;
use crate::iter::FusedIterator;

use super::from_utf8_unchecked;
use super::validations::utf8_char_width;

/// [`Utf8Chunks`] 迭代器返回的项。
///
/// 在解码 UTF-8 字符串时，`Utf8Chunk` 存储一个 [`u8`] 序列，直到第一个断字符。
///
///
/// # Examples
///
/// ```
/// #![feature(utf8_chunks)]
///
/// use std::str::Utf8Chunks;
///
/// // 无效的 UTF-8 字符串
/// let bytes = b"foo\xF1\x80bar";
///
/// // 解码第一个 `Utf8Chunk`
/// let chunk = Utf8Chunks::new(bytes).next().unwrap();
///
/// // 前三个字符有效 UTF-8
/// assert_eq!("foo", chunk.valid());
///
/// // 第四个字符损坏了
/// assert_eq!(b"\xF1\x80", chunk.invalid());
/// ```
#[unstable(feature = "utf8_chunks", issue = "99543")]
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Utf8Chunk<'a> {
    valid: &'a str,
    invalid: &'a [u8],
}

impl<'a> Utf8Chunk<'a> {
    /// 返回下一个经过验证的 UTF-8 子字符串。
    ///
    /// 该子字符串可以在字符串的开头为空，也可以在断开的 UTF-8 字符之间为空。
    ///
    #[must_use]
    #[unstable(feature = "utf8_chunks", issue = "99543")]
    pub fn valid(&self) -> &'a str {
        self.valid
    }

    /// 返回导致失败的无效序列。
    ///
    /// 返回的切片最大长度为 3，并在 [`valid`] 给出的子字符串之后开始。
    /// 解码将在此序列后恢复。
    ///
    /// 如果为空，则这是字符串中的最后一个块。
    /// 如果非空，则遇到意外字节或意外到达输入结尾。
    ///
    /// 有损解码将用 [`U+FFFD REPLACEMENT CHARACTER`] 替换这个序列。
    ///
    /// [`valid`]: Self::valid
    /// [`U+FFFD REPLACEMENT CHARACTER`]: crate::char::REPLACEMENT_CHARACTER
    ///
    ///
    #[must_use]
    #[unstable(feature = "utf8_chunks", issue = "99543")]
    pub fn invalid(&self) -> &'a [u8] {
        self.invalid
    }
}

#[must_use]
#[unstable(feature = "str_internals", issue = "none")]
pub struct Debug<'a>(&'a [u8]);

#[unstable(feature = "str_internals", issue = "none")]
impl fmt::Debug for Debug<'_> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        f.write_char('"')?;

        for chunk in Utf8Chunks::new(self.0) {
            // 有效部分。
            // 在这里，我们再次部分解析次优 UTF-8。
            {
                let valid = chunk.valid();
                let mut from = 0;
                for (i, c) in valid.char_indices() {
                    let esc = c.escape_debug();
                    // 如果 char 需要转义，请清除到目前为止的积压并编写，否则跳过
                    if esc.len() != 1 {
                        f.write_str(&valid[from..i])?;
                        for c in esc {
                            f.write_char(c)?;
                        }
                        from = i + c.len_utf8();
                    }
                }
                f.write_str(&valid[from..])?;
            }

            // 字符串的损坏部分作为十六进制转义。
            for &b in chunk.invalid() {
                write!(f, "\\x{:02X}", b)?;
            }
        }

        f.write_char('"')
    }
}

/// 一个迭代器，用于将大部分 UTF-8 字节的切片解码为字符串切片 ([`&str`]) 和字节切片 ([`&[u8]`][byteslice])。
///
///
/// 如果您想要从 UTF-8 字节切片到字符串切片的简单转换，[`from_utf8`] 更易于使用。
///
/// [byteslice]: slice
/// [`from_utf8`]: super::from_utf8
///
/// # Examples
///
/// 这可用于创建类似于 [`String::from_utf8_lossy`] 的功能，而无需分配堆内存:
///
/// ```
/// #![feature(utf8_chunks)]
///
/// use std::str::Utf8Chunks;
///
/// fn from_utf8_lossy<F>(input: &[u8], mut push: F) where F: FnMut(&str) {
///     for chunk in Utf8Chunks::new(input) {
///         push(chunk.valid());
///
///         if !chunk.invalid().is_empty() {
///             push("\u{FFFD}");
///         }
///     }
/// }
/// ```
///
/// [`String::from_utf8_lossy`]: ../../std/string/struct.String.html#method.from_utf8_lossy
///
///
#[must_use = "iterators are lazy and do nothing unless consumed"]
#[unstable(feature = "utf8_chunks", issue = "99543")]
#[derive(Clone)]
pub struct Utf8Chunks<'a> {
    source: &'a [u8],
}

impl<'a> Utf8Chunks<'a> {
    /// 创建一个新的迭代器来解码字节。
    #[unstable(feature = "utf8_chunks", issue = "99543")]
    pub fn new(bytes: &'a [u8]) -> Self {
        Self { source: bytes }
    }

    #[doc(hidden)]
    #[unstable(feature = "str_internals", issue = "none")]
    pub fn debug(&self) -> Debug<'_> {
        Debug(self.source)
    }
}

#[unstable(feature = "utf8_chunks", issue = "99543")]
impl<'a> Iterator for Utf8Chunks<'a> {
    type Item = Utf8Chunk<'a>;

    fn next(&mut self) -> Option<Utf8Chunk<'a>> {
        if self.source.is_empty() {
            return None;
        }

        const TAG_CONT_U8: u8 = 128;
        fn safe_get(xs: &[u8], i: usize) -> u8 {
            *xs.get(i).unwrap_or(&0)
        }

        let mut i = 0;
        let mut valid_up_to = 0;
        while i < self.source.len() {
            // SAFETY: `i < self.source.len()` per 前一行。
            // 出于某种原因，以下两项的速度都明显较慢：
            // while let Some(&byte) = self.source.get(i) { while let Some(byte) = self.source.get(i).copied() {
            //
            let byte = unsafe { *self.source.get_unchecked(i) };
            i += 1;

            if byte < 128 {
                // 在下面的匹配中，这可能是一个 `1 => ...` 的情况，但对于全 ASCII 输入的常见情况，我们绕过了将相当大的 UTF8_CHAR_WIDTH 表加载到缓存中。
                //
                //
            } else {
                let w = utf8_char_width(byte);

                match w {
                    2 => {
                        if safe_get(self.source, i) & 192 != TAG_CONT_U8 {
                            break;
                        }
                        i += 1;
                    }
                    3 => {
                        match (byte, safe_get(self.source, i)) {
                            (0xE0, 0xA0..=0xBF) => (),
                            (0xE1..=0xEC, 0x80..=0xBF) => (),
                            (0xED, 0x80..=0x9F) => (),
                            (0xEE..=0xEF, 0x80..=0xBF) => (),
                            _ => break,
                        }
                        i += 1;
                        if safe_get(self.source, i) & 192 != TAG_CONT_U8 {
                            break;
                        }
                        i += 1;
                    }
                    4 => {
                        match (byte, safe_get(self.source, i)) {
                            (0xF0, 0x90..=0xBF) => (),
                            (0xF1..=0xF3, 0x80..=0xBF) => (),
                            (0xF4, 0x80..=0x8F) => (),
                            _ => break,
                        }
                        i += 1;
                        if safe_get(self.source, i) & 192 != TAG_CONT_U8 {
                            break;
                        }
                        i += 1;
                        if safe_get(self.source, i) & 192 != TAG_CONT_U8 {
                            break;
                        }
                        i += 1;
                    }
                    _ => break,
                }
            }

            valid_up_to = i;
        }

        // SAFETY: `i <= self.source.len()` 因为它只通过 `i += 1` 递增，并且在每一个递增之间，`i` 与 `self.source.len()` 进行比较。
        // 这要么在 while 循环条件下由 `i < self.source.len()` 直接发生，要么由 `safe_get(self.source, i) & 192 != TAG_CONT_U8` 间接发生。
        // 一旦最新的 `i += 1` 使 `i` 不再小于 `self.source.len()`，循环就会终止，这意味着它最多等于 `self.source.len()`。
        //
        //
        //
        //
        //
        let (inspected, remaining) = unsafe { self.source.split_at_unchecked(i) };
        self.source = remaining;

        // SAFETY: `valid_up_to <= i` 因为它只能通过 `valid_up_to = i` 分配，而 `i` 只会增加。
        //
        let (valid, invalid) = unsafe { inspected.split_at_unchecked(valid_up_to) };

        Some(Utf8Chunk {
            // SAFETY: 直到 `valid_up_to` 的所有字节都是有效的 UTF-8。
            valid: unsafe { from_utf8_unchecked(valid) },
            invalid,
        })
    }
}

#[unstable(feature = "utf8_chunks", issue = "99543")]
impl FusedIterator for Utf8Chunks<'_> {}

#[unstable(feature = "utf8_chunks", issue = "99543")]
impl fmt::Debug for Utf8Chunks<'_> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        f.debug_struct("Utf8Chunks").field("source", &self.debug()).finish()
    }
}