//! `Default` trait 用于具有默认值的类型。

#![stable(feature = "rust1", since = "1.0.0")]

/// 一个用于给类型提供有用的默认值的 trait。
///
/// 有时，您希望回退到某种默认值，而不必特别关心它是什么。
/// 这经常出现在定义一组选项的 `struct` 中：
///
/// ```
/// # #[allow(dead_code)]
/// struct SomeOptions {
///     foo: i32,
///     bar: f32,
/// }
/// ```
///
/// 我们如何定义一些默认值？ 您可以使用 `Default`：
///
/// ```
/// # #[allow(dead_code)]
/// #[derive(Default)]
/// struct SomeOptions {
///     foo: i32,
///     bar: f32,
/// }
///
/// fn main() {
///     let options: SomeOptions = Default::default();
/// }
/// ```
///
/// 现在，您将获得所有默认值。Rust 为各种原始类型实现 `Default`。
///
/// 如果要覆盖特定选项，但仍保留其他默认值：
///
/// ```
/// # #[allow(dead_code)]
/// # #[derive(Default)]
/// # struct SomeOptions {
/// #     foo: i32,
/// #     bar: f32,
/// # }
/// fn main() {
///     let options = SomeOptions { foo: 42, ..Default::default() };
/// }
/// ```
///
/// ## Derivable
///
/// 如果类型的所有字段都实现 `Default`，则此 trait 可以与 `#[derive]` 一起使用。
/// 当 `derive`d 时，它将为每个字段的类型使用默认值。
///
/// ### `enum`s
///
/// 在 `enum` 上使用 `#[derive(Default)]` 时，您需要选择默认的单元变体。
/// 您可以通过将 `#[default]` 属性放在变体上来执行此操作。
///
/// ```
/// #[derive(Default)]
/// enum Kind {
///     #[default]
///     A,
///     B,
///     C,
/// }
/// ```
///
/// 您不能在非单元或非详尽变体上使用 `#[default]` 属性。
///
/// ## 如何实现 `Default`？
///
/// 提供 `default()` 方法的实现，该实现返回您类型的值，该值应为默认值：
///
///
/// ```
/// # #![allow(dead_code)]
/// enum Kind {
///     A,
///     B,
///     C,
/// }
///
/// impl Default for Kind {
///     fn default() -> Self { Kind::A }
/// }
/// ```
///
/// # Examples
///
/// ```
/// # #[allow(dead_code)]
/// #[derive(Default)]
/// struct SomeOptions {
///     foo: i32,
///     bar: f32,
/// }
/// ```
///
#[cfg_attr(not(test), rustc_diagnostic_item = "Default")]
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Default: Sized {
    /// 返回类型的 "默认值"。
    ///
    /// 默认值通常是某种初始值，标识值或其他可能有意义的默认值。
    ///
    ///
    /// # Examples
    ///
    /// 使用内置的默认值：
    ///
    /// ```
    /// let i: i8 = Default::default();
    /// let (x, y): (Option<String>, f64) = Default::default();
    /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default();
    /// ```
    ///
    /// 制作自己的：
    ///
    /// ```
    /// # #[allow(dead_code)]
    /// enum Kind {
    ///     A,
    ///     B,
    ///     C,
    /// }
    ///
    /// impl Default for Kind {
    ///     fn default() -> Self { Kind::A }
    /// }
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    fn default() -> Self;
}

/// 根据 `Default` trait 返回类型的默认值。
///
/// 从上下文推断要返回的类型。这等效于 `Default::default()`，但类型更短。
///
/// 例如：
///
/// ```
/// #![feature(default_free_fn)]
///
/// use std::default::default;
///
/// #[derive(Default)]
/// struct AppConfig {
///     foo: FooConfig,
///     bar: BarConfig,
/// }
///
/// #[derive(Default)]
/// struct FooConfig {
///     foo: i32,
/// }
///
/// #[derive(Default)]
/// struct BarConfig {
///     bar: f32,
///     baz: u8,
/// }
///
/// fn main() {
///     let options = AppConfig {
///         foo: default(),
///         bar: BarConfig {
///             bar: 10.1,
///             ..default()
///         },
///     };
/// }
/// ```
#[unstable(feature = "default_free_fn", issue = "73014")]
#[must_use]
#[inline]
pub fn default<T: Default>() -> T {
    Default::default()
}

/// 派生宏，生成 `Default` trait 的 impl。
#[rustc_builtin_macro(Default, attributes(default))]
#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
#[allow_internal_unstable(core_intrinsics)]
pub macro Default($item:item) {
    /* compiler built-in */
}

macro_rules! default_impl {
    ($t:ty, $v:expr, $doc:tt) => {
        #[stable(feature = "rust1", since = "1.0.0")]
        impl Default for $t {
            #[inline]
            #[doc = $doc]
            fn default() -> $t {
                $v
            }
        }
    };
}

default_impl! { (), (), "Returns the default value of `()`" }
default_impl! { bool, false, "Returns the default value of `false`" }
default_impl! { char, '\x00', "Returns the default value of `\\x00`" }

default_impl! { usize, 0, "Returns the default value of `0`" }
default_impl! { u8, 0, "Returns the default value of `0`" }
default_impl! { u16, 0, "Returns the default value of `0`" }
default_impl! { u32, 0, "Returns the default value of `0`" }
default_impl! { u64, 0, "Returns the default value of `0`" }
default_impl! { u128, 0, "Returns the default value of `0`" }

default_impl! { isize, 0, "Returns the default value of `0`" }
default_impl! { i8, 0, "Returns the default value of `0`" }
default_impl! { i16, 0, "Returns the default value of `0`" }
default_impl! { i32, 0, "Returns the default value of `0`" }
default_impl! { i64, 0, "Returns the default value of `0`" }
default_impl! { i128, 0, "Returns the default value of `0`" }

default_impl! { f32, 0.0f32, "Returns the default value of `0.0`" }
default_impl! { f64, 0.0f64, "Returns the default value of `0.0`" }