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 //! # #[allow(dead_code)]
  19 //! struct SomeOptions {
  20 //!     foo: i32,
  21 //!     bar: f32,
  22 //! }
  23 //! ```
  24 //!
  25 //! How can we define some default values? You can use `Default`:
  26 //!
  27 //! ```
  28 //! # #[allow(dead_code)]
  29 //! #[derive(Default)]
  30 //! struct SomeOptions {
  31 //!     foo: i32,
  32 //!     bar: f32,
  33 //! }
  34 //!
  35 //!
  36 //! fn main() {
  37 //!     let options: SomeOptions = Default::default();
  38 //! }
  39 //! ```
  40 //!
  41 //! Now, you get all of the default values. Rust implements `Default` for various primitives types.
  42 //! If you have your own type, you need to implement `Default` yourself:
  43 //!
  44 //! ```
  45 //! # #![allow(dead_code)]
  46 //! enum Kind {
  47 //!     A,
  48 //!     B,
  49 //!     C,
  50 //! }
  51 //!
  52 //! impl Default for Kind {
  53 //!     fn default() -> Kind { Kind::A }
  54 //! }
  55 //!
  56 //! #[derive(Default)]
  57 //! struct SomeOptions {
  58 //!     foo: i32,
  59 //!     bar: f32,
  60 //!     baz: Kind,
  61 //! }
  62 //!
  63 //!
  64 //! fn main() {
  65 //!     let options: SomeOptions = Default::default();
  66 //! }
  67 //! ```
  68 //!
  69 //! If you want to override a particular option, but still retain the other defaults:
  70 //!
  71 //! ```
  72 //! # #[allow(dead_code)]
  73 //! # #[derive(Default)]
  74 //! # struct SomeOptions {
  75 //! #     foo: i32,
  76 //! #     bar: f32,
  77 //! # }
  78 //! fn main() {
  79 //!     let options = SomeOptions { foo: 42, ..Default::default() };
  80 //! }
  81 //! ```
  82
  83 #![stable(feature = "rust1", since = "1.0.0")]
  84
  85 use marker::Sized;
  86
  87 /// A trait for giving a type a useful default value.
  88 ///
  89 /// A struct can derive default implementations of `Default` for basic types using
  90 /// `#[derive(Default)]`.
  91 ///
  92 /// # Examples
  93 ///
  94 /// ```
  95 /// # #[allow(dead_code)]
  96 /// #[derive(Default)]
  97 /// struct SomeOptions {
  98 ///     foo: i32,
  99 ///     bar: f32,
 100 /// }
 101 /// ```
 102 #[stable(feature = "rust1", since = "1.0.0")]
 103 pub trait Default: Sized {
 104     /// Returns the "default value" for a type.
 105     ///
 106     /// Default values are often some kind of initial value, identity value, or anything else that
 107     /// may make sense as a default.
 108     ///
 109     /// # Examples
 110     ///
 111     /// Using built-in default values:
 112     ///
 113     /// ```
 114     /// let i: i8 = Default::default();
 115     /// let (x, y): (Option<String>, f64) = Default::default();
 116     /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default();
 117     /// ```
 118     ///
 119     /// Making your own:
 120     ///
 121     /// ```
 122     /// # #[allow(dead_code)]
 123     /// enum Kind {
 124     ///     A,
 125     ///     B,
 126     ///     C,
 127     /// }
 128     ///
 129     /// impl Default for Kind {
 130     ///     fn default() -> Kind { Kind::A }
 131     /// }
 132     /// ```
 133     #[stable(feature = "rust1", since = "1.0.0")]
 134     fn default() -> Self;
 135 }
 136
 137 macro_rules! default_impl {
 138     ($t:ty, $v:expr) => {
 139         #[stable(feature = "rust1", since = "1.0.0")]
 140         impl Default for $t {
 141             #[inline]
 142             fn default() -> $t { $v }
 143         }
 144     }
 145 }
 146
 147 default_impl! { (), () }
 148 default_impl! { bool, false }
 149 default_impl! { char, '\x00' }
 150
 151 default_impl! { usize, 0 }
 152 default_impl! { u8, 0 }
 153 default_impl! { u16, 0 }
 154 default_impl! { u32, 0 }
 155 default_impl! { u64, 0 }
 156
 157 default_impl! { isize, 0 }
 158 default_impl! { i8, 0 }
 159 default_impl! { i16, 0 }
 160 default_impl! { i32, 0 }
 161 default_impl! { i64, 0 }
 162
 163 default_impl! { f32, 0.0f32 }
 164 default_impl! { f64, 0.0f64 }