mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Methods for option::Option

Browse Source
This commit is contained in:
Jonas Hietala 2014-09-16 17:20:03 +02:00
parent e53db0b5c9
commit 0d94d787a7
1 changed files with 217 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
src/libcore/option.rs
View File

@ -175,6 +175,16 @@ impl<T> Option<T> {
/////////////////////////////////////////////////////////////////////////
/// Returns `true` if the option is a `Some` value
///
/// # Example
///
/// ```
/// let x: Option<uint> = Some(2);
/// assert_eq!(x.is_some(), true);
///
/// let x: Option<uint> = None;
/// assert_eq!(x.is_some(), false);
/// ```
#[inline]
#[stable]
pub fn is_some(&self) -> bool {
@ -185,6 +195,16 @@ impl<T> Option<T> {
}
/// Returns `true` if the option is a `None` value
///
/// # Example
///
/// ```
/// let x: Option<uint> = Some(2);
/// assert_eq!(x.is_none(), false);
///
/// let x: Option<uint> = None;
/// assert_eq!(x.is_none(), true);
/// ```
#[inline]
#[stable]
pub fn is_none(&self) -> bool {
@ -218,6 +238,17 @@ impl<T> Option<T> {
}
/// Convert from `Option<T>` 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<T> Option<T> {
}
/// Convert from `Option<T>` 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<T> Option<T> {
///
/// 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<T> Option<T> {
/// 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<T> Option<T> {
}
/// 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<T> Option<T> {
}
/// 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<T> Option<T> {
}
/// 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<U>(self, def: U, f: |T| -> U) -> U {
@ -328,6 +421,18 @@ impl<T> Option<T> {
}
/// 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<U>(self, def: || -> U, f: |T| -> U) -> U {
@ -366,6 +471,16 @@ impl<T> Option<T> {
/////////////////////////////////////////////////////////////////////////
/// Returns an iterator over the possibly contained value.
///
/// # Example
///
/// ```
/// let x = Some(4u);
/// assert_eq!(x.iter().next(), Some(&4));
///
/// let x: Option<uint> = 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<T> Option<T> {
}
/// 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<uint> = 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<T> Option<T> {
}
/// 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<T> {
@ -403,6 +544,26 @@ impl<T> Option<T> {
/////////////////////////////////////////////////////////////////////////
/// 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<uint> = 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<uint> = None;
/// let y: Option<&str> = None;
/// assert_eq!(x.and(y), None);
/// ```
#[inline]
#[stable]
pub fn and<U>(self, optb: Option<U>) -> Option<U> {
@ -414,6 +575,18 @@ impl<T> Option<T> {
/// Returns `None` if the option is `None`, otherwise calls `f` with the
/// wrapped value and returns the result.
///
/// # Example
///
/// ```
/// fn sq(x: uint) -> Option<uint> { Some(x * x) }
/// fn nope(_: uint) -> Option<uint> { 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<U>(self, f: |T| -> Option<U>) -> Option<U> {
@ -424,6 +597,26 @@ impl<T> Option<T> {
}
/// 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<uint> = None;
/// let y = None;
/// assert_eq!(x.or(y), None);
/// ```
#[inline]
#[stable]
pub fn or(self, optb: Option<T>) -> Option<T> {
@ -435,6 +628,17 @@ impl<T> Option<T> {
/// 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<T>) -> Option<T> {
@ -449,6 +653,18 @@ impl<T> Option<T> {
/////////////////////////////////////////////////////////////////////////
/// 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<uint> = None;
/// x.take();
/// assert_eq!(x, None);
/// ```
#[inline]
#[stable]
pub fn take(&mut self) -> Option<T> {
@ -613,7 +829,7 @@ impl<T> Default for Option<T> {
/// 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"]