//! 字符转换。

use crate::convert::TryFrom;
use crate::fmt;
use crate::mem::transmute;
use crate::str::FromStr;

use super::MAX;

/// 将 `u32` 转换为 `char`。
///
/// 请注意，所有 [`char`] 都是有效的 [`u32`]，并且可以使用以下命令将其强制转换为一个
/// `as`:
///
/// ```
/// let c = '💯';
/// let i = c as u32;
///
/// assert_eq!(128175, i);
/// ```
///
/// 但是，事实并非如此: 并非所有有效的 [u32] 都是有效的 [char]。
/// `from_u32()` 如果输入的值不是 [`char`] 的有效值，则将返回 `None`。
///
/// 有关忽略这些检查的该函数的不安全版本，请参见 [`from_u32_unchecked`]。
///
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// use std::char;
///
/// let c = char::from_u32(0x2764);
///
/// assert_eq!(Some('❤'), c);
/// ```
///
/// 当输入不是有效的 [`char`] 时返回 `None`:
///
/// ```
/// use std::char;
///
/// let c = char::from_u32(0x110000);
///
/// assert_eq!(None, c);
/// ```
///
#[doc(alias = "chr")]
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn from_u32(i: u32) -> Option<char> {
    char::try_from(i).ok()
}

/// 将 `u32` 转换为 `char`，而忽略有效性。
///
/// 请注意，所有 [`char`] 都是有效的 [`u32`]，并且可以使用以下命令将其强制转换为一个
/// `as`:
///
/// ```
/// let c = '💯';
/// let i = c as u32;
///
/// assert_eq!(128175, i);
/// ```
///
/// 但是，事实并非如此: 并非所有有效的 [u32] 都是有效的 [char]。
/// `from_u32_unchecked()` 会忽略这一点，并盲目地将其强制转换为 [`char`]，从而可能创建无效的 [`char`]。
///
///
/// # Safety
///
/// 该函数是不安全的，因为它可能创建无效的 `char` 值。
///
/// 有关此函数的安全版本，请参见 [`from_u32`] 函数。
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// use std::char;
///
/// let c = unsafe { char::from_u32_unchecked(0x2764) };
///
/// assert_eq!('❤', c);
/// ```
#[inline]
#[stable(feature = "char_from_unchecked", since = "1.5.0")]
pub 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
    }
}

/// 将 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 时可以返回的错误。
#[stable(feature = "char_from_str", since = "1.20.0")]
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ParseCharError {
    kind: CharErrorKind,
}

impl ParseCharError {
    #[unstable(
        feature = "char_error_internals",
        reason = "this method should not be available publicly",
        issue = "none"
    )]
    #[doc(hidden)]
    pub fn __description(&self) -> &str {
        match self.kind {
            CharErrorKind::EmptyString => "cannot parse char from empty string",
            CharErrorKind::TooManyChars => "too many characters in string",
        }
    }
}

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

#[stable(feature = "char_from_str", since = "1.20.0")]
impl fmt::Display for ParseCharError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        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 }),
        }
    }
}

#[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> {
        if (i > MAX as u32) || (i >= 0xD800 && i <= 0xDFFF) {
            Err(CharTryFromError(()))
        } else {
            // SAFETY: 检查这是合法的 unicode 值
            Ok(unsafe { transmute(i) })
        }
    }
}

/// 从 u32 转换为 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`。
///
/// 这里的 'radix' 有时也称为 'base'。
/// 基数 2 表示二进制数，以十进制表示的十进制，以十六进制表示十六进制的基数，以给出一些公共值。
///
/// 支持任意基数。
///
/// `from_digit()` 如果输入不是给定基数中的数字，则将返回 `None`。
///
/// # Panics
///
/// Panics (如果基数大于 36)。
///
/// # Examples
///
/// 基本用法:
///
/// ```
/// use std::char;
///
/// let c = char::from_digit(4, 10);
///
/// assert_eq!(Some('4'), c);
///
/// // 十进制 11 是以 16 为底的一位数字
/// let c = char::from_digit(11, 16);
///
/// assert_eq!(Some('b'), c);
/// ```
///
/// 当输入不是数字时返回 `None`:
///
/// ```
/// use std::char;
///
/// let c = char::from_digit(20, 10);
///
/// assert_eq!(None, c);
/// ```
///
/// 传递较大的基数，导致 panic:
///
/// ```should_panic
/// use std::char;
///
/// // 这个 panics
/// let c = char::from_digit(1, 37);
/// ```
///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub 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
    }
}