10
10
11
11
//! Optional values.
12
12
//!
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
16
16
//! they have a number of uses:
17
17
//!
18
18
//! * Initial values
26
26
//! * Nullable pointers
27
27
//! * Swapping things out of difficult situations
28
28
//!
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.
31
31
//!
32
32
//! ```
33
33
//! fn divide(numerator: f64, denominator: f64) -> Option<f64> {
57
57
//!
58
58
//! Rust's pointer types must always point to a valid location; there are
59
59
//! 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>`]` >`.
61
61
//!
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
64
64
//! `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`] ).
67
67
//!
68
68
//! ```
69
69
//! let optional: Option<Box<i32>> = None;
80
80
//! }
81
81
//! ```
82
82
//!
83
- //! This usage of `Option` to create safe nullable pointers is so
83
+ //! This usage of [ `Option`] to create safe nullable pointers is so
84
84
//! 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
86
86
//! in Rust are stored as efficiently as any other pointer type.
87
87
//!
88
88
//! # Examples
89
89
//!
90
- //! Basic pattern matching on `Option`:
90
+ //! Basic pattern matching on [ `Option`] :
91
91
//!
92
92
//! ```
93
93
//! let msg = Some("howdy");
101
101
//! let unwrapped_msg = msg.unwrap_or("default message");
102
102
//! ```
103
103
//!
104
- //! Initialize a result to `None` before a loop:
104
+ //! Initialize a result to [ `None`] before a loop:
105
105
//!
106
106
//! ```
107
107
//! enum Kingdom { Plant(u32, &'static str), Animal(u32, &'static str) }
136
136
//! None => println!("there are no animals :("),
137
137
//! }
138
138
//! ```
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
139
145
140
146
#![ stable( feature = "rust1" , since = "1.0.0" ) ]
141
147
@@ -156,7 +162,7 @@ pub enum Option<T> {
156
162
None ,
157
163
/// Some value `T`
158
164
#[ 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 ) ,
160
166
}
161
167
162
168
/////////////////////////////////////////////////////////////////////////////
@@ -168,7 +174,7 @@ impl<T> Option<T> {
168
174
// Querying the contained values
169
175
/////////////////////////////////////////////////////////////////////////
170
176
171
- /// Returns `true` if the option is a `Some` value
177
+ /// Returns `true` if the option is a `Some` value.
172
178
///
173
179
/// # Examples
174
180
///
@@ -188,7 +194,7 @@ impl<T> Option<T> {
188
194
}
189
195
}
190
196
191
- /// Returns `true` if the option is a `None` value
197
+ /// Returns `true` if the option is a `None` value.
192
198
///
193
199
/// # Examples
194
200
///
@@ -209,15 +215,17 @@ impl<T> Option<T> {
209
215
// Adapter for working with references
210
216
/////////////////////////////////////////////////////////////////////////
211
217
212
- /// Converts from `Option<T>` to `Option<&T>`
218
+ /// Converts from `Option<T>` to `Option<&T>`.
213
219
///
214
220
/// # Examples
215
221
///
216
222
/// 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,
218
224
/// so this technique uses `as_ref` to first take an `Option` to a reference
219
225
/// to the value inside the original.
220
226
///
227
+ /// [`map`]: enum.Option.html#method.map
228
+ ///
221
229
/// ```
222
230
/// let num_as_str: Option<String> = Some("10".to_string());
223
231
/// // First, cast `Option<String>` to `Option<&String>` with `as_ref`,
@@ -234,7 +242,7 @@ impl<T> Option<T> {
234
242
}
235
243
}
236
244
237
- /// Converts from `Option<T>` to `Option<&mut T>`
245
+ /// Converts from `Option<T>` to `Option<&mut T>`.
238
246
///
239
247
/// # Examples
240
248
///
@@ -357,7 +365,7 @@ impl<T> Option<T> {
357
365
// Transforming contained values
358
366
/////////////////////////////////////////////////////////////////////////
359
367
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.
361
369
///
362
370
/// # Examples
363
371
///
@@ -423,8 +431,12 @@ impl<T> Option<T> {
423
431
}
424
432
}
425
433
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
428
440
///
429
441
/// # Examples
430
442
///
@@ -444,8 +456,12 @@ impl<T> Option<T> {
444
456
}
445
457
}
446
458
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
449
465
///
450
466
/// # Examples
451
467
///
@@ -789,7 +805,9 @@ impl<A> DoubleEndedIterator for Item<A> {
789
805
impl < A > ExactSizeIterator for Item < A > { }
790
806
impl < A > FusedIterator for Item < A > { }
791
807
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
793
811
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
794
812
#[ derive( Debug ) ]
795
813
pub struct Iter < ' a , A : ' a > { inner : Item < & ' a A > }
@@ -823,7 +841,9 @@ impl<'a, A> Clone for Iter<'a, A> {
823
841
}
824
842
}
825
843
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
827
847
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
828
848
#[ derive( Debug ) ]
829
849
pub struct IterMut < ' a , A : ' a > { inner : Item < & ' a mut A > }
@@ -850,7 +870,9 @@ impl<'a, A> ExactSizeIterator for IterMut<'a, A> {}
850
870
#[ unstable( feature = "fused" , issue = "35602" ) ]
851
871
impl < ' a , A > FusedIterator for IterMut < ' a , A > { }
852
872
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
854
876
#[ derive( Clone , Debug ) ]
855
877
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
856
878
pub struct IntoIter < A > { inner : Item < A > }
0 commit comments