src/libcore/default.rs

   1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! The `Default` trait for types which may have meaningful default values.
  12 //!
  13 //! Sometimes, you want to fall back to some kind of default value, and
  14 //! don't particularly care what it is. This comes up often with `struct`s
  15 //! that define a set of options:
  16 //!
  17 //! ```
  18 //! struct SomeOptions {
  19 //!     foo: i32,
  20 //!     bar: f32,
  21 //! }
  22 //! ```
  23 //!
  24 //! How can we define some default values? You can use `Default`:
  25 //!
  26 //! ```
  27 //! #[derive(Default)]
  28 //! struct SomeOptions {
  29 //!     foo: i32,
  30 //!     bar: f32,
  31 //! }
  32 //!
  33 //!
  34 //! fn main() {
  35 //!     let options: SomeOptions = Default::default();
  36 //! }
  37 //! ```
  38 //!
  39 //! Now, you get all of the default values. Rust implements `Default` for various primitives types.
  40 //! If you have your own type, you need to implement `Default` yourself:
  41 //!
  42 //! ```
  43 //! enum Kind {
  44 //!     A,
  45 //!     B,
  46 //!     C,
  47 //! }
  48 //!
  49 //! impl Default for Kind {
  50 //!     fn default() -> Kind { Kind::A }
  51 //! }
  52 //!
  53 //! #[derive(Default)]
  54 //! struct SomeOptions {
  55 //!     foo: i32,
  56 //!     bar: f32,
  57 //!     baz: Kind,
  58 //! }
  59 //!
  60 //!
  61 //! fn main() {
  62 //!     let options: SomeOptions = Default::default();
  63 //! }
  64 //! ```
  65 //!
  66 //! If you want to override a particular option, but still retain the other defaults:
  67 //!
  68 //! ```
  69 //! # #[derive(Default)]
  70 //! # struct SomeOptions {
  71 //! #     foo: i32,
  72 //! #     bar: f32,
  73 //! # }
  74 //! fn main() {
  75 //!     let options = SomeOptions { foo: 42, ..Default::default() };
  76 //! }
  77 //! ```
  78
  79 #![stable(feature = "rust1", since = "1.0.0")]
  80
  81 /// A trait that types which have a useful default value should implement.
  82 ///
  83 /// A struct can derive default implementations of `Default` for basic types using
  84 /// `#[derive(Default)]`.
  85 ///
  86 /// # Examples
  87 ///
  88 /// ```
  89 /// #[derive(Default)]
  90 /// struct SomeOptions {
  91 ///     foo: i32,
  92 ///     bar: f32,
  93 /// }
  94 /// ```
  95 #[stable(feature = "rust1", since = "1.0.0")]
  96 pub trait Default {
  97     /// Returns the "default value" for a type.
  98     ///
  99     /// Default values are often some kind of initial value, identity value, or anything else that
 100     /// may make sense as a default.
 101     ///
 102     /// # Examples
 103     ///
 104     /// Using built-in default values:
 105     ///
 106     /// ```
 107     /// let i: i8 = Default::default();
 108     /// let (x, y): (Option<String>, f64) = Default::default();
 109     /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default();
 110     /// ```
 111     ///
 112     /// Making your own:
 113     ///
 114     /// ```
 115     /// enum Kind {
 116     ///     A,
 117     ///     B,
 118     ///     C,
 119     /// }
 120     ///
 121     /// impl Default for Kind {
 122     ///     fn default() -> Kind { Kind::A }
 123     /// }
 124     /// ```
 125     #[stable(feature = "rust1", since = "1.0.0")]
 126     fn default() -> Self;
 127 }
 128
 129 macro_rules! default_impl {
 130     ($t:ty, $v:expr) => {
 131         #[stable(feature = "rust1", since = "1.0.0")]
 132         impl Default for $t {
 133             #[inline]
 134             #[stable(feature = "rust1", since = "1.0.0")]
 135             fn default() -> $t { $v }
 136         }
 137     }
 138 }
 139
 140 default_impl! { (), () }
 141 default_impl! { bool, false }
 142 default_impl! { char, '\x00' }
 143
 144 default_impl! { usize, 0 }
 145 default_impl! { u8, 0 }
 146 default_impl! { u16, 0 }
 147 default_impl! { u32, 0 }
 148 default_impl! { u64, 0 }
 149
 150 default_impl! { isize, 0 }
 151 default_impl! { i8, 0 }
 152 default_impl! { i16, 0 }
 153 default_impl! { i32, 0 }
 154 default_impl! { i64, 0 }
 155
 156 default_impl! { f32, 0.0f32 }
 157 default_impl! { f64, 0.0f64 }