From 0d94d787a7c9b027a83445f1ca9c60d82e425243 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Tue, 16 Sep 2014 17:20:03 +0200 Subject: [PATCH] doc: Methods for option::Option --- src/libcore/option.rs | 218 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 217 insertions(+), 1 deletion(-) diff --git a/src/libcore/option.rs b/src/libcore/option.rs index cd6e8f3e666e1..6020f7ce7f52c 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -175,6 +175,16 @@ impl Option { ///////////////////////////////////////////////////////////////////////// /// Returns `true` if the option is a `Some` value + /// + /// # Example + /// + /// ``` + /// let x: Option = Some(2); + /// assert_eq!(x.is_some(), true); + /// + /// let x: Option = None; + /// assert_eq!(x.is_some(), false); + /// ``` #[inline] #[stable] pub fn is_some(&self) -> bool { @@ -185,6 +195,16 @@ impl Option { } /// Returns `true` if the option is a `None` value + /// + /// # Example + /// + /// ``` + /// let x: Option = Some(2); + /// assert_eq!(x.is_none(), false); + /// + /// let x: Option = None; + /// assert_eq!(x.is_none(), true); + /// ``` #[inline] #[stable] pub fn is_none(&self) -> bool { @@ -218,6 +238,17 @@ impl Option { } /// Convert from `Option` to `Option<&mut T>` + /// + /// # Example + /// + /// ``` + /// let mut x = Some(2u); + /// match x.as_mut() { + /// Some(&ref mut v) => *v = 42, + /// None => {}, + /// } + /// assert_eq!(x, Some(42u)); + /// ``` #[inline] #[unstable = "waiting for mut conventions"] pub fn as_mut<'r>(&'r mut self) -> Option<&'r mut T> { @@ -225,6 +256,19 @@ impl Option { } /// Convert from `Option` to `&mut [T]` (without copying) + /// + /// # Example + /// + /// ``` + /// let mut x = Some("Diamonds"); + /// { + /// let v = x.as_mut_slice(); + /// assert!(v == ["Diamonds"]); + /// v[0] = "Dirt"; + /// assert!(v == ["Dirt"]); + /// } + /// assert_eq!(x, Some("Dirt")); + /// ``` #[inline] #[unstable = "waiting for mut conventions"] pub fn as_mut_slice<'r>(&'r mut self) -> &'r mut [T] { @@ -250,6 +294,18 @@ impl Option { /// /// Fails if the value is a `None` with a custom failure message provided by /// `msg`. + /// + /// # Example + /// + /// ``` + /// let x = Some("value"); + /// assert_eq!(x.expect("the world is ending"), "value"); + /// ``` + /// + /// ```{.should_fail} + /// let x: Option<&str> = None; + /// x.expect("the world is ending"); // fails with `world is ending` + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn expect(self, msg: &str) -> T { @@ -270,6 +326,18 @@ impl Option { /// In general, because this function may fail, its use is discouraged. /// Instead, prefer to use pattern matching and handle the `None` /// case explicitly. + /// + /// # Examle + /// + /// ``` + /// let x = Some("air"); + /// assert_eq!(x.unwrap(), "air"); + /// ``` + /// + /// ```{.should_fail} + /// let x: Option<&str> = None; + /// assert_eq!(x.unwrap(), "air"); // fails + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn unwrap(self) -> T { @@ -280,6 +348,13 @@ impl Option { } /// Returns the contained value or a default. + /// + /// # Example + /// + /// ``` + /// assert_eq!(Some("car").unwrap_or("bike"), "car"); + /// assert_eq!(None.unwrap_or("bike"), "bike"); + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn unwrap_or(self, def: T) -> T { @@ -290,6 +365,14 @@ impl Option { } /// Returns the contained value or computes it from a closure. + /// + /// # Example + /// + /// ``` + /// let k = 10u; + /// assert_eq!(Some(4u).unwrap_or_else(|| 2 * k), 4u); + /// assert_eq!(None.unwrap_or_else(|| 2 * k), 20u); + /// ``` #[inline] #[unstable = "waiting for conventions"] pub fn unwrap_or_else(self, f: || -> T) -> T { @@ -321,6 +404,16 @@ impl Option { } /// Applies a function to the contained value or returns a default. + /// + /// # Example + /// + /// ``` + /// let x = Some("foo"); + /// assert_eq!(x.map_or(42u, |v| v.len()), 3u); + /// + /// let x: Option<&str> = None; + /// assert_eq!(x.map_or(42u, |v| v.len()), 42u); + /// ``` #[inline] #[unstable = "waiting for unboxed closures"] pub fn map_or(self, def: U, f: |T| -> U) -> U { @@ -328,6 +421,18 @@ impl Option { } /// Applies a function to the contained value or computes a default. + /// + /// # Example + /// + /// ``` + /// let k = 21u; + /// + /// let x = Some("foo"); + /// assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 3u); + /// + /// let x: Option<&str> = None; + /// assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 42u); + /// ``` #[inline] #[unstable = "waiting for unboxed closures"] pub fn map_or_else(self, def: || -> U, f: |T| -> U) -> U { @@ -366,6 +471,16 @@ impl Option { ///////////////////////////////////////////////////////////////////////// /// Returns an iterator over the possibly contained value. + /// + /// # Example + /// + /// ``` + /// let x = Some(4u); + /// assert_eq!(x.iter().next(), Some(&4)); + /// + /// let x: Option = None; + /// assert_eq!(x.iter().next(), None); + /// ``` #[inline] #[unstable = "waiting for iterator conventions"] pub fn iter<'r>(&'r self) -> Item<&'r T> { @@ -379,6 +494,20 @@ impl Option { } /// Returns a mutable iterator over the possibly contained value. + /// + /// # Example + /// + /// ``` + /// let mut x = Some(4u); + /// match x.iter_mut().next() { + /// Some(&ref mut v) => *v = 42u, + /// None => {}, + /// } + /// assert_eq!(x, Some(42)); + /// + /// let mut x: Option = None; + /// assert_eq!(x.iter_mut().next(), None); + /// ``` #[inline] #[unstable = "waiting for iterator conventions"] pub fn iter_mut<'r>(&'r mut self) -> Item<&'r mut T> { @@ -392,6 +521,18 @@ impl Option { } /// Returns a consuming iterator over the possibly contained value. + /// + /// # Example + /// + /// ``` + /// let x = Some("string"); + /// let v: Vec<&str> = x.into_iter().collect(); + /// assert_eq!(v, vec!["string"]); + /// + /// let x = None; + /// let v: Vec<&str> = x.into_iter().collect(); + /// assert_eq!(v, vec![]); + /// ``` #[inline] #[unstable = "waiting for iterator conventions"] pub fn into_iter(self) -> Item { @@ -403,6 +544,26 @@ impl Option { ///////////////////////////////////////////////////////////////////////// /// Returns `None` if the option is `None`, otherwise returns `optb`. + /// + /// # Example + /// + /// ``` + /// let x = Some(2u); + /// let y: Option<&str> = None; + /// assert_eq!(x.and(y), None); + /// + /// let x: Option = None; + /// let y = Some("foo"); + /// assert_eq!(x.and(y), None); + /// + /// let x = Some(2u); + /// let y = Some("foo"); + /// assert_eq!(x.and(y), Some("foo")); + /// + /// let x: Option = None; + /// let y: Option<&str> = None; + /// assert_eq!(x.and(y), None); + /// ``` #[inline] #[stable] pub fn and(self, optb: Option) -> Option { @@ -414,6 +575,18 @@ impl Option { /// Returns `None` if the option is `None`, otherwise calls `f` with the /// wrapped value and returns the result. + /// + /// # Example + /// + /// ``` + /// fn sq(x: uint) -> Option { Some(x * x) } + /// fn nope(_: uint) -> Option { None } + /// + /// assert_eq!(Some(2).and_then(sq).and_then(sq), Some(16)); + /// assert_eq!(Some(2).and_then(sq).and_then(nope), None); + /// assert_eq!(Some(2).and_then(nope).and_then(sq), None); + /// assert_eq!(None.and_then(sq).and_then(sq), None); + /// ``` #[inline] #[unstable = "waiting for unboxed closures"] pub fn and_then(self, f: |T| -> Option) -> Option { @@ -424,6 +597,26 @@ impl Option { } /// Returns the option if it contains a value, otherwise returns `optb`. + /// + /// # Example + /// + /// ``` + /// let x = Some(2u); + /// let y = None; + /// assert_eq!(x.or(y), Some(2u)); + /// + /// let x = None; + /// let y = Some(100u); + /// assert_eq!(x.or(y), Some(100u)); + /// + /// let x = Some(2u); + /// let y = Some(100u); + /// assert_eq!(x.or(y), Some(2u)); + /// + /// let x: Option = None; + /// let y = None; + /// assert_eq!(x.or(y), None); + /// ``` #[inline] #[stable] pub fn or(self, optb: Option) -> Option { @@ -435,6 +628,17 @@ impl Option { /// Returns the option if it contains a value, otherwise calls `f` and /// returns the result. + /// + /// # Example + /// + /// ``` + /// fn nobody() -> Option<&'static str> { None } + /// fn vikings() -> Option<&'static str> { Some("vikings") } + /// + /// assert_eq!(Some("barbarians").or_else(vikings), Some("barbarians")); + /// assert_eq!(None.or_else(vikings), Some("vikings")); + /// assert_eq!(None.or_else(nobody), None); + /// ``` #[inline] #[unstable = "waiting for unboxed closures"] pub fn or_else(self, f: || -> Option) -> Option { @@ -449,6 +653,18 @@ impl Option { ///////////////////////////////////////////////////////////////////////// /// Takes the value out of the option, leaving a `None` in its place. + /// + /// # Example + /// + /// ``` + /// let mut x = Some(2u); + /// x.take(); + /// assert_eq!(x, None); + /// + /// let mut x: Option = None; + /// x.take(); + /// assert_eq!(x, None); + /// ``` #[inline] #[stable] pub fn take(&mut self) -> Option { @@ -613,7 +829,7 @@ impl Default for Option { /// An `Option` iterator that yields either one or zero elements /// -/// The `Item` iterator is returned by the `iter`, `mut_iter` and `move_iter` +/// The `Item` iterator is returned by the `iter`, `iter_mut` and `into_iter` /// methods on `Option`. #[deriving(Clone)] #[unstable = "waiting for iterator conventions"]