1010
1111//! Optional values.
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
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
1616//! they have a number of uses:
1717//!
1818//! * Initial values
2626//! * Nullable pointers
2727//! * Swapping things out of difficult situations
2828//!
29- //! Options are commonly paired with pattern matching to query the presence
30- //! of a value and take action, always accounting for the `None` case.
29+ //! [`Option`]s are commonly paired with pattern matching to query the presence
30+ //! of a value and take action, always accounting for the [ `None`] case.
3131//!
3232//! ```
3333//! fn divide(numerator: f64, denominator: f64) -> Option<f64> {
5757//!
5858//! Rust's pointer types must always point to a valid location; there are
5959//! no "null" pointers. Instead, Rust has *optional* pointers, like
60- //! the optional owned box, `Option< Box<T>>`.
60+ //! the optional owned box, [ `Option`]`<`[` Box<T>`]` >`.
6161//!
62- //! The following example uses `Option` to create an optional box of
63- //! `i32`. Notice that in order to use the inner `i32` value first the
62+ //! The following example uses [ `Option`] to create an optional box of
63+ //! [ `i32`] . Notice that in order to use the inner [ `i32`] value first the
6464//! `check_optional` function needs to use pattern matching to
65- //! determine whether the box has a value (i.e. it is `Some(...)`) or
66- //! not (`None`).
65+ //! determine whether the box has a value (i.e. it is [ `Some(...)`][`Some`] ) or
66+ //! not ([ `None`] ).
6767//!
6868//! ```
6969//! let optional: Option<Box<i32>> = None;
8080//! }
8181//! ```
8282//!
83- //! This usage of `Option` to create safe nullable pointers is so
83+ //! This usage of [ `Option`] to create safe nullable pointers is so
8484//! common that Rust does special optimizations to make the
85- //! representation of `Option< Box<T>>` a single pointer. Optional pointers
85+ //! representation of [ `Option`]`<`[` Box<T>`]` >` a single pointer. Optional pointers
8686//! in Rust are stored as efficiently as any other pointer type.
8787//!
8888//! # Examples
8989//!
90- //! Basic pattern matching on `Option`:
90+ //! Basic pattern matching on [ `Option`] :
9191//!
9292//! ```
9393//! let msg = Some("howdy");
101101//! let unwrapped_msg = msg.unwrap_or("default message");
102102//! ```
103103//!
104- //! Initialize a result to `None` before a loop:
104+ //! Initialize a result to [ `None`] before a loop:
105105//!
106106//! ```
107107//! enum Kingdom { Plant(u32, &'static str), Animal(u32, &'static str) }
136136//! None => println!("there are no animals :("),
137137//! }
138138//! ```
139+ //!
140+ //! [`Option`]: enum.Option.html
141+ //! [`Some`]: enum.Option.html#variant.Some
142+ //! [`None`]: enum.Option.html#variant.None
143+ //! [`Box<T>`]: ../../std/boxed/struct.Box.html
144+ //! [`i32`]: ../../std/primitive.i32.html
139145
140146#![ stable( feature = "rust1" , since = "1.0.0" ) ]
141147
@@ -156,7 +162,7 @@ pub enum Option<T> {
156162 None ,
157163 /// Some value `T`
158164#[ stable( feature = "rust1" , since = "1.0.0" ) ]
159- Some ( #[ stable( feature = "rust1" , since = "1.0.0" ) ] T )
165+ Some ( #[ stable( feature = "rust1" , since = "1.0.0" ) ] T ) ,
160166}
161167
162168/////////////////////////////////////////////////////////////////////////////
@@ -168,7 +174,7 @@ impl<T> Option<T> {
168174 // Querying the contained values
169175 /////////////////////////////////////////////////////////////////////////
170176
171- /// Returns `true` if the option is a `Some` value
177+ /// Returns `true` if the option is a `Some` value.
172178///
173179/// # Examples
174180///
@@ -188,7 +194,7 @@ impl<T> Option<T> {
188194 }
189195 }
190196
191- /// Returns `true` if the option is a `None` value
197+ /// Returns `true` if the option is a `None` value.
192198///
193199/// # Examples
194200///
@@ -209,15 +215,17 @@ impl<T> Option<T> {
209215 // Adapter for working with references
210216 /////////////////////////////////////////////////////////////////////////
211217
212- /// Converts from `Option<T>` to `Option<&T>`
218+ /// Converts from `Option<T>` to `Option<&T>`.
213219///
214220/// # Examples
215221///
216222/// Convert an `Option<String>` into an `Option<usize>`, preserving the original.
217- /// The `map` method takes the `self` argument by value, consuming the original,
223+ /// The [ `map`] method takes the `self` argument by value, consuming the original,
218224/// so this technique uses `as_ref` to first take an `Option` to a reference
219225/// to the value inside the original.
220226///
227+ /// [`map`]: enum.Option.html#method.map
228+ ///
221229/// ```
222230/// let num_as_str: Option<String> = Some("10".to_string());
223231/// // First, cast `Option<String>` to `Option<&String>` with `as_ref`,
@@ -234,7 +242,7 @@ impl<T> Option<T> {
234242 }
235243 }
236244
237- /// Converts from `Option<T>` to `Option<&mut T>`
245+ /// Converts from `Option<T>` to `Option<&mut T>`.
238246///
239247/// # Examples
240248///
@@ -357,7 +365,7 @@ impl<T> Option<T> {
357365 // Transforming contained values
358366 /////////////////////////////////////////////////////////////////////////
359367
360- /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value
368+ /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value.
361369///
362370/// # Examples
363371///
@@ -423,8 +431,12 @@ impl<T> Option<T> {
423431 }
424432 }
425433
426- /// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
427- /// `Ok(v)` and `None` to `Err(err)`.
434+ /// Transforms the `Option<T>` into a [`Result<T, E>`], mapping `Some(v)` to
435+ /// [`Ok(v)`] and `None` to [`Err(err)`][Err].
436+ ///
437+ /// [`Result<T, E>`]: ../../std/result/enum.Result.html
438+ /// [`Ok(v)`]: ../../std/result/enum.Result.html#variant.Ok
439+ /// [Err]: ../../std/result/enum.Result.html#variant.Err
428440///
429441/// # Examples
430442///
@@ -444,8 +456,12 @@ impl<T> Option<T> {
444456 }
445457 }
446458
447- /// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
448- /// `Ok(v)` and `None` to `Err(err())`.
459+ /// Transforms the `Option<T>` into a [`Result<T, E>`], mapping `Some(v)` to
460+ /// [`Ok(v)`] and `None` to [`Err(err())`][Err].
461+ ///
462+ /// [`Result<T, E>`]: ../../std/result/enum.Result.html
463+ /// [`Ok(v)`]: ../../std/result/enum.Result.html#variant.Ok
464+ /// [Err]: ../../std/result/enum.Result.html#variant.Err
449465///
450466/// # Examples
451467///
@@ -789,7 +805,9 @@ impl<A> DoubleEndedIterator for Item<A> {
789805impl < A > ExactSizeIterator for Item < A > { }
790806impl < A > FusedIterator for Item < A > { }
791807
792- /// An iterator over a reference of the contained item in an Option.
808+ /// An iterator over a reference of the contained item in an [`Option`].
809+ ///
810+ /// [`Option`]: enum.Option.html
793811#[ stable( feature = "rust1" , since = "1.0.0" ) ]
794812#[ derive( Debug ) ]
795813pub struct Iter < ' a , A : ' a > { inner : Item < & ' a A > }
@@ -823,7 +841,9 @@ impl<'a, A> Clone for Iter<'a, A> {
823841 }
824842}
825843
826- /// An iterator over a mutable reference of the contained item in an Option.
844+ /// An iterator over a mutable reference of the contained item in an [`Option`].
845+ ///
846+ /// [`Option`]: enum.Option.html
827847#[ stable( feature = "rust1" , since = "1.0.0" ) ]
828848#[ derive( Debug ) ]
829849pub struct IterMut < ' a , A : ' a > { inner : Item < & ' a mut A > }
@@ -850,7 +870,9 @@ impl<'a, A> ExactSizeIterator for IterMut<'a, A> {}
850870#[ unstable( feature = "fused" , issue = "35602" ) ]
851871impl < ' a , A > FusedIterator for IterMut < ' a , A > { }
852872
853- /// An iterator over the item contained inside an Option.
873+ /// An iterator over the item contained inside an [`Option`].
874+ ///
875+ /// [`Option`]: enum.Option.html
854876#[ derive( Clone , Debug ) ]
855877#[ stable( feature = "rust1" , since = "1.0.0" ) ]
856878pub struct IntoIter < A > { inner : Item < A > }
0 commit comments