use crate::convert::From;
use crate::fmt;
use crate::marker::{PhantomData, Unsize};
use crate::ops::{CoerceUnsized, DispatchFromDyn};
use crate::ptr::NonNull;

/// 原始非空 `*mut T` 周围的包装器，指示该包装器的拥有者拥有引用对象。
/// 对于构建 `Box<T>`，`Vec<T>`，`String` 和 `HashMap<K, V>` 等抽象很有用。
///
/// 与 `*mut T` 不同，`Unique<T>` 的行为与 "as if" 相同，它是 `T` 的实例。
/// 如果 `T` 为 `Send`/`Sync`，则实现 `Send`/`Sync`。
/// 这也暗示了 `T` 实例可以期望的那种强别名保证：
/// 如果没有指向其所属 `unique` 的唯一路径，则不应修改指针的引用对象。
///
/// 如果不确定使用 `Unique` 是否正确，请考虑使用语义较弱的 `NonNull`。
///
///
/// 与 `*mut T` 不同，即使从未解引用指针，指针也必须始终为非 null。
/// 这样一来，枚举就可以将此禁止值用作判别式 - `Option<Unique<T>>` 与 `Unique<T>` 具有相同的大小。
/// 但是，如果指针未解引用，它可能仍会悬垂。
///
/// 与 `*mut T` 不同，`Unique<T>` 在 `T` 上是协变的。
/// 对于任何符合 `Unique` 别名要求的类型，这应该总是正确的。
///
///
///
#[unstable(
    feature = "ptr_internals",
    issue = "none",
    reason = "use `NonNull` instead and consider `PhantomData<T>` \
              (if you also use `#[may_dangle]`), `Send`, and/or `Sync`"
)]
#[doc(hidden)]
#[repr(transparent)]
pub struct Unique<T: ?Sized> {
    pointer: NonNull<T>,
    // NOTE: 此标记不会对差异产生任何影响，但对于 dropck 来说，了解我们在逻辑上拥有 `T` 是必需的。
    //
    //
    // 有关详细信息，请参见：
    // https://github.com/rust-lang/rfcs/blob/master/text/0769-sound-generic-drop.md#phantom-data
    _marker: PhantomData<T>,
}

/// 如果 `T` 是 `Send`，则 `Unique` 指针是 `Send`，因为它们引用的数据是无别名的。
/// 请注意，类型系统不强制使用此别名不变量。使用 `Unique` 的抽象必须强制使用它。
///
///
#[unstable(feature = "ptr_internals", issue = "none")]
unsafe impl<T: Send + ?Sized> Send for Unique<T> {}

/// 如果 `T` 是 `Sync`，则 `Unique` 指针是 `Sync`，因为它们引用的数据是无别名的。
/// 请注意，类型系统不强制使用此别名不变量。使用 `Unique` 的抽象必须强制使用它。
///
///
#[unstable(feature = "ptr_internals", issue = "none")]
unsafe impl<T: Sync + ?Sized> Sync for Unique<T> {}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: Sized> Unique<T> {
    /// 创建一个悬垂但对齐良好的新 `Unique`。
    ///
    /// 与 `Vec::new` 一样，这对于初始化延迟分配的类型很有用。
    ///
    /// 请注意，该指针值可能表示一个指向 `T` 的有效指针，这意味着不得将其用作 "尚未初始化" 标记值。
    /// 延迟分配的类型必须通过其他某种方式来跟踪初始化。
    ///
    ///
    ///
    #[must_use]
    #[inline]
    pub const fn dangling() -> Self {
        // FIXME(const-hack) 替换为 `From`
        Unique { pointer: NonNull::dangling(), _marker: PhantomData }
    }
}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> Unique<T> {
    /// 创建一个新的 `Unique`。
    ///
    /// # Safety
    ///
    /// `ptr` 必须不能为空。
    #[inline]
    pub const unsafe fn new_unchecked(ptr: *mut T) -> Self {
        // SAFETY: 调用者必须保证 `ptr` 不为空。
        unsafe { Unique { pointer: NonNull::new_unchecked(ptr), _marker: PhantomData } }
    }

    /// 如果 `ptr` 不为空，则创建一个新的 `Unique`。
    #[inline]
    pub const fn new(ptr: *mut T) -> Option<Self> {
        if let Some(pointer) = NonNull::new(ptr) {
            Some(Unique { pointer, _marker: PhantomData })
        } else {
            None
        }
    }

    /// 获取底层的 `*mut` 指针。
    #[must_use = "`self` will be dropped if the result is not used"]
    #[inline]
    pub const fn as_ptr(self) -> *mut T {
        self.pointer.as_ptr()
    }

    /// 解引用内容。
    ///
    /// 最终的生命周期被绑定到 self 上，所以它的行为 "好像" 它实际上是一个被借用的 T 的实例。
    /// 如果需要更长的 (unbound) 生命周期，请使用 `&*my_ptr.as_ptr()`。
    ///
    #[must_use]
    #[inline]
    pub const unsafe fn as_ref(&self) -> &T {
        // SAFETY: 调用者必须保证 `self` 满足引用的所有要求。
        //
        unsafe { self.pointer.as_ref() }
    }

    /// 相互解引用内容。
    ///
    /// 最终的生命周期被绑定到 self 上，所以它的行为 "好像" 它实际上是一个被借用的 T 的实例。
    /// 如果需要更长的 (unbound) 生命周期，请使用 `&mut *my_ptr.as_ptr()`。
    ///
    #[must_use]
    #[inline]
    pub const unsafe fn as_mut(&mut self) -> &mut T {
        // SAFETY: 调用者必须保证 `self` 满足可变引用的所有要求。
        //
        unsafe { self.pointer.as_mut() }
    }

    /// 强制转换为另一种类型的指针。
    #[must_use = "`self` will be dropped if the result is not used"]
    #[inline]
    pub const fn cast<U>(self) -> Unique<U> {
        // FIXME(const-hack): 替换为 `From`
        // SAFETY: 是 `NonNull`
        unsafe { Unique::new_unchecked(self.pointer.cast().as_ptr()) }
    }
}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> Clone for Unique<T> {
    #[inline]
    fn clone(&self) -> Self {
        *self
    }
}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> Copy for Unique<T> {}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized, U: ?Sized> CoerceUnsized<Unique<U>> for Unique<T> where T: Unsize<U> {}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized, U: ?Sized> DispatchFromDyn<Unique<U>> for Unique<T> where T: Unsize<U> {}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> fmt::Debug for Unique<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Pointer::fmt(&self.as_ptr(), f)
    }
}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> fmt::Pointer for Unique<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Pointer::fmt(&self.as_ptr(), f)
    }
}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> From<&mut T> for Unique<T> {
    /// 将 `&mut T` 转换为 `Unique<T>`。
    ///
    /// 这种转换是可靠的，因为引用不能为空。
    #[inline]
    fn from(reference: &mut T) -> Self {
        Self::from(NonNull::from(reference))
    }
}

#[unstable(feature = "ptr_internals", issue = "none")]
impl<T: ?Sized> From<NonNull<T>> for Unique<T> {
    /// 将 `NonNull<T>` 转换为 `Unique<T>`。
    ///
    /// 这种转换是可靠的，因为 `NonNull` 不能为空。
    #[inline]
    fn from(pointer: NonNull<T>) -> Self {
        Unique { pointer, _marker: PhantomData }
    }
}