//! 字符转换。

use crate::char::TryFromCharError;
use crate::convert::TryFrom;
use crate::error::Error;
use crate::fmt;
use crate::mem::transmute;
use crate::str::FromStr;

/// 将 `u32` 转换为 `char`。请参见 [`char::from_u32`]。
#[must_use]
#[inline]
pub(super) const fn from_u32(i: u32) -> Option<char> {
    // FIXME: 一旦 Result::ok 是 const fn，就在这里使用它
    match char_try_from_u32(i) {
        Ok(c) => Some(c),
        Err(_) => None,
    }
}

/// 将 `u32` 转换为 `char`，而忽略有效性。请参见 [`char::from_u32_unchecked`]。
#[inline]
#[must_use]
pub(super) const unsafe fn from_u32_unchecked(i: u32) -> char {
    // SAFETY: 调用者必须保证 `i` 是有效的 char 值。
    if cfg!(debug_assertions) { char::from_u32(i).unwrap() } else { unsafe { transmute(i) } }
}

#[stable(feature = "char_convert", since = "1.13.0")]
impl From<char> for u32 {
    /// 将 [`char`] 转换为 [`u32`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::mem;
    ///
    /// let c = 'c';
    /// let u = u32::from(c);
    /// assert!(4 == mem::size_of_val(&u))
    /// ```
    #[inline]
    fn from(c: char) -> Self {
        c as u32
    }
}

#[stable(feature = "more_char_conversions", since = "1.51.0")]
impl From<char> for u64 {
    /// 将 [`char`] 转换为 [`u64`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::mem;
    ///
    /// let c = '👤';
    /// let u = u64::from(c);
    /// assert!(8 == mem::size_of_val(&u))
    /// ```
    #[inline]
    fn from(c: char) -> Self {
        // 字符强制转换为代码点的值，然后零扩展为 64 位。
        // 请参见 [https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics]
        c as u64
    }
}

#[stable(feature = "more_char_conversions", since = "1.51.0")]
impl From<char> for u128 {
    /// 将 [`char`] 转换为 [`u128`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::mem;
    ///
    /// let c = '⚙';
    /// let u = u128::from(c);
    /// assert!(16 == mem::size_of_val(&u))
    /// ```
    #[inline]
    fn from(c: char) -> Self {
        // 字符强制转换为代码点的值，然后零扩展为 128 位。
        // 请参见 [https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics]
        c as u128
    }
}

/// 将 U+0000..=U+00FF 中代码点的 `char` 映射到 0x00..=0xFF 中具有相同值的字节，如果代码点大于 U+00FF 则失败。
///
///
/// 有关编码的详细信息，请参见 [`impl From<u8> for char`](char#impl-From<u8>-for-char)。
#[stable(feature = "u8_from_char", since = "1.59.0")]
impl TryFrom<char> for u8 {
    type Error = TryFromCharError;

    #[inline]
    fn try_from(c: char) -> Result<u8, Self::Error> {
        u8::try_from(u32::from(c)).map_err(|_| TryFromCharError(()))
    }
}

/// 将 0x00..=0xFF 中的字节映射到 `char`，该 `char` 的代码点具有相同的值，即 U+0000..=U+00FF。
///
/// Unicode 的设计使其可以使用 IANA 称为 ISO-8859-1 的字符编码有效地解码字节。
/// 此编码与 ASCII 兼容。
///
/// 请注意，这与 ISO/IEC 8859-1 又名不同
/// ISO 8859-1 (连字符少一个)，它留下了一些 "blanks" 字节值，这些值未分配给任何字符。
/// ISO-8859-1 (属于 IANA) 将它们分配给 C0 和 C1 控制代码。
///
/// 请注意，这也与 Windows-1252 也不同
/// 代码页 1252，它是 ISO/IEC 8859-1 的超集，它为标点符号和各种拉丁字符分配了一些 (不是全部) 空格。
///
/// 为了进一步混淆，[在 Web 上](https://encoding.spec.whatwg.org/) `ascii`，`iso-8859-1` 和 `windows-1252` 都是 Windows-1252 超集的别名，该超集用相应的 C0 和 C1 控制代码填充了其余的空白。
///
///
///
///
///
#[stable(feature = "char_convert", since = "1.13.0")]
impl From<u8> for char {
    /// 将 [`u8`] 转换为 [`char`]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::mem;
    ///
    /// let u = 32 as u8;
    /// let c = char::from(u);
    /// assert!(4 == mem::size_of_val(&c))
    /// ```
    #[inline]
    fn from(i: u8) -> Self {
        i as char
    }
}

/// 解析 char 时可以返回的错误。
///
/// 此 `struct` 是在使用 [`char::from_str`] 方法时创建的。
#[stable(feature = "char_from_str", since = "1.20.0")]
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ParseCharError {
    kind: CharErrorKind,
}

#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum CharErrorKind {
    EmptyString,
    TooManyChars,
}

#[stable(feature = "char_from_str", since = "1.20.0")]
impl Error for ParseCharError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match self.kind {
            CharErrorKind::EmptyString => "cannot parse char from empty string",
            CharErrorKind::TooManyChars => "too many characters in string",
        }
    }
}

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

#[stable(feature = "char_from_str", since = "1.20.0")]
impl FromStr for char {
    type Err = ParseCharError;

    #[inline]
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let mut chars = s.chars();
        match (chars.next(), chars.next()) {
            (None, _) => Err(ParseCharError { kind: CharErrorKind::EmptyString }),
            (Some(c), None) => Ok(c),
            _ => Err(ParseCharError { kind: CharErrorKind::TooManyChars }),
        }
    }
}

#[inline]
const fn char_try_from_u32(i: u32) -> Result<char, CharTryFromError> {
    // 这是检查的优化版本 (i > MAX as u32) || (i >= 0xD800 && i <= 0xDFFF)，也可以写成 i >= 0x110000 || (i >= 0xD800 && i < 0xE000)。
    //
    // 与 0xD800 的 XOR 置换范围，使 0xD800..0xE000 映射到 0x0000..0x0800，同时保持 0xFFFF 之外的所有高位相同。
    // 特别是，numbers >= 0x110000 停留在此范围内。
    //
    // 减去 0x800 会导致 0x0000..0x0800 进行包装，这意味着针对 0x110000 - 0x800 的单个无符号比较将检测包装的代理范围以及最初大于 0x110000 的数字。
    //
    //
    //
    //
    //
    //
    //
    if (i ^ 0xD800).wrapping_sub(0x800) >= 0x110000 - 0x800 {
        Err(CharTryFromError(()))
    } else {
        // SAFETY: 检查这是合法的 unicode 值
        Ok(unsafe { transmute(i) })
    }
}

#[stable(feature = "try_from", since = "1.34.0")]
impl TryFrom<u32> for char {
    type Error = CharTryFromError;

    #[inline]
    fn try_from(i: u32) -> Result<Self, Self::Error> {
        char_try_from_u32(i)
    }
}

/// [`prim@u32`] 到 [`prim@char`] 转换失败时返回的错误类型。
///
/// 这个 `struct` 是由 [`char::try_from<u32>`](char#impl-TryFrom<u32>-for-char) 方法创建的。
/// 有关更多信息，请参见其文档。
#[stable(feature = "try_from", since = "1.34.0")]
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct CharTryFromError(());

#[stable(feature = "try_from", since = "1.34.0")]
impl fmt::Display for CharTryFromError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        "converted integer out of range for `char`".fmt(f)
    }
}

/// 将给定基数中的数字转换为 `char`。请参见 [`char::from_digit`]。
#[inline]
#[must_use]
pub(super) const fn from_digit(num: u32, radix: u32) -> Option<char> {
    if radix > 36 {
        panic!("from_digit: radix is too high (maximum 36)");
    }
    if num < radix {
        let num = num as u8;
        if num < 10 { Some((b'0' + num) as char) } else { Some((b'a' + num - 10) as char) }
    } else {
        None
    }
}