88// option. This file may not be copied, modified, or distributed
99// except according to those terms.
1010
11- //! Optional values
11+ //! Optionally nullable values (`Option` type)
1212//!
13- //! Type `Option` represents an optional value: every `Option`
14- //! is either `Some` and contains a value, or `None`, and
15- //! does not. `Option` types are very common in Rust code, as
16- //! they have a number of uses:
13+ //! Type `Option` represents an optional value.
1714//!
18- //! * Initial values
19- //! * Return values for functions that are not defined
20- //! over their entire input range (partial functions)
21- //! * Return value for otherwise reporting simple errors, where `None` is
22- //! returned on error
23- //! * Optional struct fields
24- //! * Struct fields that can be loaned or "taken"
25- //! * Optional function arguments
26- //! * Nullable pointers
27- //! * Swapping things out of difficult situations
15+ //! Every `Option<T>` value can either be `Some(T)` or `None`. Where in other
16+ //! languages you might use a nullable type, in Rust you would use an option
17+ //! type.
2818//!
29- //! Options are commonly paired with pattern matching to query the presence
19+ //! Options are most commonly used with pattern matching to query the presence
3020//! of a value and take action, always accounting for the `None` case.
3121//!
32- //! ```
33- //! # // FIXME This is not the greatest first example
34- //! // cow_says contains the word "moo"
35- //! let cow_says = Some("moo");
36- //! // dog_says does not contain a value
37- //! let dog_says: Option<&str> = None;
38- //!
39- //! // Pattern match to retrieve the value
40- //! match (cow_says, dog_says) {
41- //! (Some(cow_words), Some(dog_words)) => {
42- //! println!("Cow says {} and dog says {}!", cow_words, dog_words);
43- //! }
44- //! (Some(cow_words), None) => println!("Cow says {}", cow_words),
45- //! (None, Some(dog_words)) => println!("Dog says {}", dog_words),
46- //! (None, None) => println!("Cow and dog are suspiciously silent")
47- //! }
48- //! ```
49- //!
50- //
51- // FIXME: Show how `Option` is used in practice, with lots of methods
52- //
53- //! # Options and pointers ("nullable" pointers)
54- //!
55- //! Rust's pointer types must always point to a valid location; there are
56- //! no "null" pointers. Instead, Rust has *optional* pointers, like
57- //! the optional owned box, `Option<~T>`.
58- //!
59- //! The following example uses `Option` to create an optional box of
60- //! `int`. Notice that in order to use the inner `int` value first the
61- //! `check_optional` function needs to use pattern matching to
62- //! determine whether the box has a value (i.e. it is `Some(...)`) or
63- //! not (`None`).
64- //!
65- //! ```
66- //! let optional: Option<~int> = None;
67- //! check_optional(&optional);
22+ //! # Example
6823//!
69- //! let optional: Option<~int> = Some(~9000);
70- //! check_optional(&optional);
71- //!
72- //! fn check_optional(optional: &Option<~int>) {
73- //! match *optional {
74- //! Some(ref p) => println!("have value {}", p),
75- //! None => println!("have no value")
76- //! }
77- //! }
7824//! ```
79- //!
80- //! This usage of `Option` to create safe nullable pointers is so
81- //! common that Rust does special optimizations to make the
82- //! representation of `Option<~T>` a single pointer. Optional pointers
83- //! in Rust are stored as efficiently as any other pointer type.
84- //!
85- //! # Examples
86- //!
87- //! Basic pattern matching on `Option`:
88- //!
89- //! ```
90- //! let msg = Some("howdy");
25+ //! let msg = Some(~"howdy");
9126//!
9227//! // Take a reference to the contained string
9328//! match msg {
9833//! // Remove the contained string, destroying the Option
9934//! let unwrapped_msg = match msg {
10035//! Some(m) => m,
101- //! None => "default message"
36+ //! None => ~ "default message"
10237//! };
10338//! ```
104- //!
105- //! Initialize a result to `None` before a loop:
106- //!
107- //! ```
108- //! enum Kingdom { Plant(uint, &'static str), Animal(uint, &'static str) }
109- //!
110- //! // A list of data to search through.
111- //! let all_the_big_things = [
112- //! Plant(250, "redwood"),
113- //! Plant(230, "noble fir"),
114- //! Plant(229, "sugar pine"),
115- //! Animal(25, "blue whale"),
116- //! Animal(19, "fin whale"),
117- //! Animal(15, "north pacific right whale"),
118- //! ];
119- //!
120- //! // We're going to search for the name of the biggest animal,
121- //! // but to start with we've just got `None`.
122- //! let mut name_of_biggest_animal = None;
123- //! let mut size_of_biggest_animal = 0;
124- //! for big_thing in all_the_big_things.iter() {
125- //! match *big_thing {
126- //! Animal(size, name) if size > size_of_biggest_animal => {
127- //! // Now we've found the name of some big animal
128- //! size_of_biggest_animal = size;
129- //! name_of_biggest_animal = Some(name);
130- //! }
131- //! Animal(..) | Plant(..) => ()
132- //! }
133- //! }
134- //!
135- //! match name_of_biggest_animal {
136- //! Some(name) => println!("the biggest animal is {}", name),
137- //! None => println!("there are no animals :(")
138- //! }
139- //! ```
14039
14140use any:: Any ;
14241use clone:: Clone ;
@@ -147,7 +46,7 @@ use kinds::Send;
14746use mem;
14847use vec;
14948
150- /// The `Option`
49+ /// The option type
15150#[ deriving( Clone , Eq , Ord , TotalEq , TotalOrd , Show ) ]
15251pub enum Option < T > {
15352 /// No value
@@ -165,7 +64,7 @@ impl<T> Option<T> {
16564 // Querying the contained values
16665 /////////////////////////////////////////////////////////////////////////
16766
168- /// Returns ` true` if the option is a `Some` value
67+ /// Returns true if the option contains a `Some` value
16968#[ inline]
17069 pub fn is_some ( & self ) -> bool {
17170 match * self {
@@ -174,7 +73,7 @@ impl<T> Option<T> {
17473 }
17574 }
17675
177- /// Returns ` true` if the option is a `None` value
76+ /// Returns true if the option equals `None`
17877#[ inline]
17978 pub fn is_none ( & self ) -> bool {
18079 !self . is_some ( )
@@ -185,21 +84,6 @@ impl<T> Option<T> {
18584 /////////////////////////////////////////////////////////////////////////
18685
18786 /// Convert from `Option<T>` to `Option<&T>`
188- ///
189- /// # Example
190- ///
191- /// Convert an `Option<~str>` into an `Option<int>`, preserving the original.
192- /// The `map` method takes the `self` argument by value, consuming the original,
193- /// so this technique uses `as_ref` to first take an `Option` to a reference
194- /// to the value inside the original.
195- ///
196- /// ```
197- /// let num_as_str: Option<~str> = Some(~"10");
198- /// // First, cast `Option<~str>` to `Option<&~str>` with `as_ref`,
199- /// // then consume *that* with `map`, leaving `num_as_str` on the stack.
200- /// let num_as_int: Option<uint> = num_as_str.as_ref().map(|n| n.len());
201- /// println!("still can print num_as_str: {}", num_as_str);
202- /// ```
20387#[ inline]
20488 pub fn as_ref < ' r > ( & ' r self ) -> Option < & ' r T > {
20589 match * self { Some ( ref x) => Some ( x) , None => None }
@@ -234,9 +118,6 @@ impl<T> Option<T> {
234118 /////////////////////////////////////////////////////////////////////////
235119
236120 /// Unwraps an option, yielding the content of a `Some`
237- ///
238- /// # Failure
239- ///
240121/// Fails if the value is a `None` with a custom failure message provided by `msg`.
241122#[ inline]
242123 pub fn expect < M : Any + Send > ( self , msg : M ) -> T {
@@ -246,11 +127,14 @@ impl<T> Option<T> {
246127 }
247128 }
248129
249- /// Moves a value out of an option type and returns it, consuming the `Option`.
130+ /// Moves a value out of an option type and returns it.
131+ ///
132+ /// Useful primarily for getting strings, vectors and unique pointers out
133+ /// of option types without copying them.
250134///
251135/// # Failure
252136///
253- /// Fails if the self value equals `None`.
137+ /// Fails if the value equals `None`.
254138///
255139/// # Safety note
256140///
@@ -287,17 +171,7 @@ impl<T> Option<T> {
287171 // Transforming contained values
288172 /////////////////////////////////////////////////////////////////////////
289173
290- /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value
291- ///
292- /// # Example
293- ///
294- /// Convert an `Option<~str>` into an `Option<uint>`, consuming the original:
295- ///
296- /// ```
297- /// let num_as_str: Option<~str> = Some(~"10");
298- /// // `Option::map` takes self *by value*, consuming `num_as_str`
299- /// let num_as_int: Option<uint> = num_as_str.map(|n| n.len());
300- /// ```
174+ /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value.
301175#[ inline]
302176 pub fn map < U > ( self , f: |T | -> U ) -> Option < U > {
303177 match self { Some ( x) => Some ( f ( x) ) , None => None }
@@ -485,28 +359,7 @@ impl<T> Option<T> {
485359}
486360
487361impl < T : Default > Option < T > {
488- /// Returns the contained value or a default
489- ///
490- /// Consumes the `self` argument then, if `Some`, returns the contained
491- /// value, otherwise if `None`, returns the default value for that
492- /// type.
493- ///
494- /// # Example
495- ///
496- /// Convert a string to an integer, turning poorly-formed strings
497- /// into 0 (the default value for integers). `from_str` converts
498- /// a string to any other type that implements `FromStr`, returning
499- /// `None` on error.
500- ///
501- /// ```
502- /// let good_year_from_input = "1909";
503- /// let bad_year_from_input = "190blarg";
504- /// let good_year = from_str(good_year_from_input).unwrap_or_default();
505- /// let bad_year = from_str(bad_year_from_input).unwrap_or_default();
506- ///
507- /// assert_eq!(1909, good_year);
508- /// assert_eq!(0, bad_year);
509- /// ```
362+ /// Returns the contained value or default (for this type)
510363#[ inline]
511364 pub fn unwrap_or_default ( self ) -> T {
512365 match self {
@@ -529,10 +382,7 @@ impl<T> Default for Option<T> {
529382// The Option Iterator
530383/////////////////////////////////////////////////////////////////////////////
531384
532- /// An `Option` iterator that yields either one or zero elements
533- ///
534- /// The `Item` iterator is returned by the `iter`, `mut_iter` and `move_iter`
535- /// methods on `Option`.
385+ /// An iterator that yields either one or zero elements
536386#[ deriving( Clone ) ]
537387pub struct Item < A > {
538388 priv opt: Option < A >
0 commit comments