Skip to content

Commit 738bc2a

Browse files
tlyutlyu
committed
method overviews for option and result
1 parent 0a538af commit 738bc2a

File tree

2 files changed

+240
-0
lines changed

2 files changed

+240
-0
lines changed

‎core/src/option.rs

+199
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,205 @@
9090
//! from `Some::<T>(_)` to `T` (but transmuting `None::<T>` to `T`
9191
//! is undefined behaviour).
9292
//!
93+
//! # Method overview
94+
//!
95+
//! In addition to working with pattern matching, [`Option`] provides a wide
96+
//! variety of different methods.
97+
//!
98+
//! ## Querying the variant
99+
//!
100+
//! The [`is_some`] and [`is_none`] methods return [`true`] if the [`Option`]
101+
//! is [`Some`] or [`None`], respectively.
102+
//!
103+
//! [`is_some`]: Option::is_some
104+
//! [`is_none`]: Option::is_none
105+
//!
106+
//! ## Adapters for working with references
107+
//!
108+
//! * [`as_ref`] converts from `&Option<T>` to `Option<&T>`
109+
//! * [`as_mut`] converts from `&mut Option<T>` to `Option<&mut T>`
110+
//! * [`as_deref`] converts from `&Option<T>` to `Option<&T::Target>`
111+
//! * [`as_deref_mut`] converts from `&mut Option<T>` to `Option<&mut T::Target>`
112+
//! * [`as_pin_ref`] converts from [`&Pin`]`<Option<T>>` to `Option<`[`Pin`]`<&T>>`
113+
//! * [`as_pin_mut`] converts from [`&mut Pin`]`<Option<T>>` to `Option<`[`Pin`]`<&mut T>>`
114+
//!
115+
//! [`&mut Pin`]: crate::pin::Pin
116+
//! [`&Pin`]: crate::pin::Pin
117+
//! [`as_deref`]: Option::as_deref
118+
//! [`as_deref_mut`]: Option::as_deref_mut
119+
//! [`as_mut`]: Option::as_mut
120+
//! [`as_pin_ref`]: Option::as_pin_ref
121+
//! [`as_pin_mut`]: Option::as_pin_mut
122+
//! [`as_ref`]: Option::as_ref
123+
//! [`Pin`]: crate::pin::Pin
124+
//!
125+
//! ## Extracting the contained value
126+
//!
127+
//! These methods extract the contained value in an [`Option`] when it is
128+
//! the [`Some`] variant. If the [`Option`] is [`None`]:
129+
//!
130+
//! * [`expect`] panics with a provided custom message
131+
//! * [`unwrap`] panics with a generic message
132+
//! * [`unwrap_or`] returns the provided default value
133+
//! * [`unwrap_or_default`] returns the default value of the type `T`
134+
//! (which must implement the [`Default`] trait)
135+
//! * [`unwrap_or_else`] evaluates a provided function
136+
//!
137+
//! [`Default`]: crate::default::Default
138+
//! [`expect`]: Option::expect
139+
//! [`unwrap`]: Option::unwrap
140+
//! [`unwrap_or`]: Option::unwrap_or
141+
//! [`unwrap_or_default`]: Option::unwrap_or_default
142+
//! [`unwrap_or_else`]: Option::unwrap_or_else
143+
//!
144+
//! ## Transforming contained values
145+
//!
146+
//! * [`map`] transforms [`Some<T>`] to [`Some<U>`] using the provided
147+
//! function
148+
//! * [`map_or`] transforms [`Some<T>`] to a value of `U` using the
149+
//! provided function, or transforms [`None`] to a provided default value
150+
//! of `U`
151+
//! * [`map_or_else`] transforms [`Some<T>`] to [`Some<U>`] using the
152+
//! provided function, or transforms [`None`] to a value of `U` using
153+
//! another provided function
154+
//! * [`ok_or`] transforms [`Some(v)`] to [`Ok(v)`], and [`None`] to
155+
//! [`Err(err)`] using the provided default `err` value
156+
//! * [`ok_or_else`] transforms [`Some(v)`] to [`Ok(v)`], and [`None`] to
157+
//! a value of [`Err<E>`] using the provided function
158+
//!
159+
//! [`Err(err)`]: Err
160+
//! [`map`]: Option::map
161+
//! [`map_or`]: Option::map_or
162+
//! [`map_or_else`]: Option::map_or_else
163+
//! [`Ok(v)`]: Ok
164+
//! [`ok_or`]: Option::ok_or
165+
//! [`ok_or_else`]: Option::ok_or_else
166+
//! [`Some(v)`]: Some
167+
//!
168+
//! ## Boolean operators
169+
//!
170+
//! These methods treat the [`Option`] as a boolean value, where [`Some`]
171+
//! acts like [`true`] and [`None`] acts like [`false`]. There are two
172+
//! categories of these methods: ones that take an [`Option`] as input, and
173+
//! ones that take a function as input (to be lazily evaluated).
174+
//!
175+
//! The [`and`], [`or`], and [`xor`] methods take another [`Option`] as
176+
//! input, and produce an [`Option`] as output. Only the [`and`] method can
177+
//! produce an [`Option<U>`] value having a different inner type `U` than
178+
//! [`Option<T>`].
179+
//!
180+
//! | method | self | input | output |
181+
//! |---------|-----------|-----------|-----------|
182+
//! | [`and`] | N/A | `None` | `None` |
183+
//! | [`and`] | `Some(x)` | `Some(y)` | `Some(y)` |
184+
//! | [`or`] | `None` | `None` | `None` |
185+
//! | [`or`] | `None` | `Some(y)` | `Some(y)` |
186+
//! | [`or`] | `Some(x)` | N/A | `Some(x)` |
187+
//! | [`xor`] | `None` | `None` | `None` |
188+
//! | [`xor`] | `None` | `Some(y)` | `Some(y)` |
189+
//! | [`xor`] | `Some(x)` | `None` | `Some(x)` |
190+
//! | [`xor`] | `Some(x)` | `Some(y)` | `None` |
191+
//!
192+
//! The [`and_then`], [`filter`], and [`or_else`] methods take a function
193+
//! as input, and only evaluate the function when they need to produce a
194+
//! new value. [`and_then`] and [`or_else`] take a function that produces
195+
//! another [`Option`] value, while [`filter`] takes a predicate that is
196+
//! used to decide whether to pass the [`Some`] value through. Only the
197+
//! [`and_then`] method can produce an [`Option<U>`] value having a
198+
//! different inner type `U` than [`Option<T>`].
199+
//!
200+
//! | method | self | function input | function result | output |
201+
//! |--------------|-----------|----------------|-----------------|-----------|
202+
//! | [`and_then`] | `None` | N/A | (not evaluated) | `None` |
203+
//! | [`and_then`] | `Some(x)` | `x` | `None` | `None` |
204+
//! | [`and_then`] | `Some(x)` | `x` | `Some(y)` | `Some(y)` |
205+
//! | [`filter`] | `None` | N/A | (not evaluated) | `None` |
206+
//! | [`filter`] | `Some(x)` | `x` | `false` | `None` |
207+
//! | [`filter`] | `Some(x)` | `x` | `true` | `Some(x)` |
208+
//! | [`or_else`] | `None` | N/A | `None` | `None` |
209+
//! | [`or_else`] | `None` | N/A | `Some(y)` | `Some(y)` |
210+
//! | [`or_else`] | `Some(x)` | N/A | (not evaluated) | `Some(x)` |
211+
//!
212+
//! [`and`]: Option::and
213+
//! [`and_then`]: Option::and_then
214+
//! [`filter`]: Option::filter
215+
//! [`or`]: Option::or
216+
//! [`or_else`]: Option::or_else
217+
//! [`xor`]: Option::xor
218+
//!
219+
//! ## Iterators
220+
//!
221+
//! An [`Option`] can be iterated over. This can be helpful if you need an
222+
//! iterator that is conditionally empty. The iterator will either produce
223+
//! a single value (when the [`Option`] is [`Some`]), or produce no values
224+
//! (when the [`Option`] is [`None`]). For example, [`into_iter`] acts like
225+
//! [`once(v)`] if the [`Option`] is [`Some(v)`], and like [`empty()`] if
226+
//! the [`Option`] is [`None`].
227+
//!
228+
//! Iterators over [`Option`] come in three types:
229+
//!
230+
//! * [`into_iter`] consumes the [`Option`] and produces the contained
231+
//! value
232+
//! * [`iter`] produces an immutable reference of type `&T` to the
233+
//! contained value
234+
//! * [`iter_mut`] produces a mutable reference of type `&mut T` to the
235+
//! contained value
236+
//!
237+
//! [`Option`] implements the [`FromIterator`] trait, which allows an
238+
//! iterator over [`Option`] values to be collected into an [`Option`] of a
239+
//! collection of each contained value of the original [`Option`] values,
240+
//! or [`None`] if any of the elements was [`None`].
241+
//!
242+
//! [`empty()`]: crate::iter::empty
243+
//! [`FromIterator`]: Option#impl-FromIterator%3COption%3CA%3E%3E
244+
//! [`into_iter`]: Option::into_iter
245+
//! [`iter`]: Option::iter
246+
//! [`iter_mut`]: Option::iter_mut
247+
//! [`once(v)`]: crate::iter::once
248+
//! [`Some(v)`]: Some
249+
//!
250+
//! An iterator over [`Option`] can be useful when chaining iterators:
251+
//!
252+
//! ```
253+
//! let yep = Some(42);
254+
//! let nope = None;
255+
//! let nums: Vec<i32> = (0..4).chain(yep.into_iter()).chain(4..8).collect();
256+
//! assert_eq!(nums, [0, 1, 2, 3, 42, 4, 5, 6, 7]);
257+
//! let nums: Vec<i32> = (0..4).chain(nope.into_iter()).chain(4..8).collect();
258+
//! assert_eq!(nums, [0, 1, 2, 3, 4, 5, 6, 7]);
259+
//! ```
260+
//!
261+
//! One reason to chain iterators in this way is that a function returning
262+
//! `impl Iterator` must have all possible return values be of the same
263+
//! concrete type. Chaining an iterated [`Option`] can help with that.
264+
//!
265+
//! ```
266+
//! let yep = Some(42);
267+
//! let nope = None;
268+
//!
269+
//! fn makeiter(opt: Option<i32>) -> impl Iterator<Item = i32> {
270+
//! (0..4).chain(opt.into_iter()).chain(4..8)
271+
//! }
272+
//! println!("{:?}", makeiter(yep).collect::<Vec<_>>());
273+
//! println!("{:?}", makeiter(nope).collect::<Vec<_>>());
274+
//! ```
275+
//!
276+
//! If we try to do the same thing, but using pattern matching, we can't
277+
//! return `impl Iterator` anymore because the concrete types of the return
278+
//! values differ.
279+
//!
280+
//! ```compile_fail,E0308
281+
//! # use std::iter::{empty, once};
282+
//! // This won't compile because all possible returns from the function
283+
//! // must have the same concrete type.
284+
//! fn makeiter(opt: Option<i32>) -> impl Iterator<Item = i32> {
285+
//! match opt {
286+
//! Some(x) => return (0..4).chain(once(x)).chain(4..8),
287+
//! None => return (0..4).chain(empty()).chain(4..8)
288+
//! }
289+
//! }
290+
//! ```
291+
//!
93292
//! # Examples
94293
//!
95294
//! Basic pattern matching on [`Option`]:

‎core/src/result.rs

+41
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,47 @@
224224
//! [`Ok(T)`]: Ok
225225
//! [`Err(E)`]: Err
226226
//! [`io::Error`]: ../../std/io/struct.Error.html
227+
//!
228+
//! # Method overview
229+
//!
230+
//! ## Boolean operators
231+
//!
232+
//! These methods treat the [`Result`] as a boolean value, where [`Ok`]
233+
//! acts like [`true`] and [`Err`] acts like [`false`]. There are two
234+
//! categories of these methods: ones that take a [`Result`] as input, and
235+
//! ones that take a function as input (to be lazily evaluated).
236+
//!
237+
//! The [`and`] and [`or`] methods take another [`Result`] as input, and
238+
//! produce an [`Result`] as output. Only the [`and`] method can produce a
239+
//! [`Result<U, E>`] value having a different inner type `U` than
240+
//! [`Result<T, E>`].
241+
//!
242+
//! | method | self | input | output |
243+
//! |---------|----------|----------|----------|
244+
//! | [`and`] | N/A | `Err(e)` | `Err(e)` |
245+
//! | [`and`] | `Ok(x)` | `Ok(y)` | `Ok(y)` |
246+
//! | [`or`] | `Err(e)` | `Err(d)` | `Err(d)` |
247+
//! | [`or`] | `Err(e)` | `Ok(y)` | `Ok(y)` |
248+
//! | [`or`] | `Ok(x)` | N/A | `Ok(x)` |
249+
//!
250+
//! The [`and_then`] and [`or_else`] methods take a function as input, and
251+
//! only evaluate the function when they need to produce a new value. Only
252+
//! the [`and_then`] method can produce an [`Result<U, E>`] value having a
253+
//! different inner type `U` than [`Result<T, E>`].
254+
//!
255+
//! | method | self | function input | function result | output |
256+
//! |--------------|----------|----------------|-----------------|----------|
257+
//! | [`and_then`] | `Err(e)` | N/A | (not evaluated) | `Err(e)` |
258+
//! | [`and_then`] | `Ok(x)` | `x` | `Err(d)` | `Err(d)` |
259+
//! | [`and_then`] | `Ok(x)` | `x` | `Ok(y)` | `Ok(y)` |
260+
//! | [`or_else`] | `Err(e)` | `e` | `Err(d)` | `Err(d)` |
261+
//! | [`or_else`] | `Err(e)` | `e` | `Ok(y)` | `Ok(y)` |
262+
//! | [`or_else`] | `Ok(x)` | N/A | (not evaluated) | `Ok(x)` |
263+
//!
264+
//! [`and`]: Result::and
265+
//! [`and_then`]: Result::and_then
266+
//! [`or`]: Result::or
267+
//! [`or_else`]: Result::or_else
227268
228269
#![stable(feature = "rust1", since = "1.0.0")]
229270

0 commit comments

Comments
 (0)