From a8e9708aeb7907979d103f0b56eebba7706c7d0e Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Thu, 10 Feb 2022 16:09:49 +0800 Subject: [PATCH 1/8] More practical examples for `Option::and_then` --- library/core/src/option.rs | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index ec04692d3e0..f8758056db9 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -1207,13 +1207,22 @@ impl Option { /// # Examples /// /// ``` - /// fn sq(x: u32) -> Option { Some(x * x) } - /// fn nope(_: u32) -> Option { None } + /// fn squared_string(x: u32) -> Option { Some((x * x).to_string()) } /// - /// 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); + /// assert_eq!(Some(2).and_then(squared_string), Some(4.to_string())); + /// assert_eq!(None.and_then(squared_string), None); + /// ``` + /// + /// Often used to chain fallible operations that may return [`None`]. + /// + /// ``` + /// let arr_2d = [["A1", "A2"], ["B1", "B2"]]; + /// + /// let item_0_1 = arr_2d.get(0).and_then(|row| row.get(1)); + /// assert_eq!(item_0_1, Some(&"A2")); + /// + /// let item_2_0 = arr_2d.get(2).and_then(|row| row.get(0)); + /// assert_eq!(item_2_0, None); /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] From 73a5f01263ffb80d113a9afe7004d940eebb0114 Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Thu, 10 Feb 2022 16:32:53 +0800 Subject: [PATCH 2/8] Use 0-based idx for array content --- library/core/src/option.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index f8758056db9..9fe38a505ab 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -1216,10 +1216,10 @@ impl Option { /// Often used to chain fallible operations that may return [`None`]. /// /// ``` - /// let arr_2d = [["A1", "A2"], ["B1", "B2"]]; + /// let arr_2d = [["A0", "A1"], ["B0", "B1"]]; /// /// let item_0_1 = arr_2d.get(0).and_then(|row| row.get(1)); - /// assert_eq!(item_0_1, Some(&"A2")); + /// assert_eq!(item_0_1, Some(&"A1")); /// /// let item_2_0 = arr_2d.get(2).and_then(|row| row.get(0)); /// assert_eq!(item_2_0, None); From bd421e2880d3c67ce77c3286d933be8171d0aaa9 Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Thu, 10 Feb 2022 17:59:46 +0800 Subject: [PATCH 3/8] More practical examples for `Result::and_then` --- library/core/src/result.rs | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 05b4fa035b1..bd7333a33e1 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -1281,16 +1281,22 @@ impl Result { /// /// # Examples /// - /// Basic usage: + /// ``` + /// fn squared_string(x: u32) -> Result { + /// Ok((x * x).to_string()) + /// } + /// + /// assert_eq!(Ok(2).and_then(squared_string), Ok(4.to_string())); + /// assert_eq!(Err("not a number").and_then(squared_string), Err("not a number")); + /// ``` + /// + /// Often used to chain fallible operations that may return [`Err`]. /// /// ``` - /// fn sq(x: u32) -> Result { Ok(x * x) } - /// fn err(x: u32) -> Result { Err(x) } + /// use std::path::Path; /// - /// assert_eq!(Ok(2).and_then(sq).and_then(sq), Ok(16)); - /// assert_eq!(Ok(2).and_then(sq).and_then(err), Err(4)); - /// assert_eq!(Ok(2).and_then(err).and_then(sq), Err(2)); - /// assert_eq!(Err(3).and_then(sq).and_then(sq), Err(3)); + /// let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified()); + /// assert!(root_modified_time.is_ok()) /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] From 942eaa7ffcebad5592bf6865ef8c9e8959ec5b79 Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Fri, 11 Feb 2022 09:55:47 +0800 Subject: [PATCH 4/8] Add negative example for `Result::and_then` --- library/core/src/result.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index bd7333a33e1..58d58ff0f72 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -1293,10 +1293,14 @@ impl Result { /// Often used to chain fallible operations that may return [`Err`]. /// /// ``` - /// use std::path::Path; + /// use std::{io::ErrorKind, path::Path}; /// /// let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified()); - /// assert!(root_modified_time.is_ok()) + /// assert!(root_modified_time.is_ok()); + /// + /// let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified()); + /// assert!(should_fail.is_err()); + /// assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound); /// ``` #[inline] #[stable(feature = "rust1", since = "1.0.0")] From 7eaecc6508149da3a0e76982f1259f5bf3cf54a8 Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Sat, 12 Feb 2022 12:12:11 +0800 Subject: [PATCH 5/8] `Result::and_then`: improve basic example --- library/core/src/result.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 58d58ff0f72..d6a0c7dc292 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -1282,12 +1282,14 @@ impl Result { /// # Examples /// /// ``` - /// fn squared_string(x: u32) -> Result { - /// Ok((x * x).to_string()) + /// fn sq(x: u32) -> Result { + /// x.checked_mul(x).ok_or("overflowed") /// } /// - /// assert_eq!(Ok(2).and_then(squared_string), Ok(4.to_string())); - /// assert_eq!(Err("not a number").and_then(squared_string), Err("not a number")); + /// assert_eq!(Ok(2).and_then(sq), Ok(4)); + /// assert_eq!(Ok(1_000_000).and_then(sq), Err("overflowed")); + /// assert_eq!(Err("not a number").and_then(sq), Err("not a number")); + /// ``` /// /// Often used to chain fallible operations that may return [`Err`]. From adfac00f458c7b68efb759335a804949d2f64d8b Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Sat, 12 Feb 2022 12:19:03 +0800 Subject: [PATCH 6/8] `Result::and_then`: show type conversion --- library/core/src/result.rs | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index d6a0c7dc292..334a8990787 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -1282,14 +1282,13 @@ impl Result { /// # Examples /// /// ``` - /// fn sq(x: u32) -> Result { - /// x.checked_mul(x).ok_or("overflowed") + /// fn sq_then_to_string(x: u32) -> Result { + /// x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed") /// } /// - /// assert_eq!(Ok(2).and_then(sq), Ok(4)); - /// assert_eq!(Ok(1_000_000).and_then(sq), Err("overflowed")); - /// assert_eq!(Err("not a number").and_then(sq), Err("not a number")); - + /// assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string())); + /// assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed")); + /// assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number")); /// ``` /// /// Often used to chain fallible operations that may return [`Err`]. From 160faf1b30d22b6a6958267e6f7bc3fb2b03754f Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Sat, 12 Feb 2022 12:23:38 +0800 Subject: [PATCH 7/8] `Option::and_then` basic example: show failure --- library/core/src/option.rs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index 9fe38a505ab..508837f63c3 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -1207,10 +1207,13 @@ impl Option { /// # Examples /// /// ``` - /// fn squared_string(x: u32) -> Option { Some((x * x).to_string()) } + /// fn sq_then_to_string(x: u32) -> Option { + /// x.checked_mul(x).map(|sq| sq.to_string()) + /// } /// - /// assert_eq!(Some(2).and_then(squared_string), Some(4.to_string())); - /// assert_eq!(None.and_then(squared_string), None); + /// assert_eq!(Some(2).and_then(sq_then_to_string), Some(4.to_string())); + /// assert_eq!(Some(1_000_000).and_then(sq_then_to_string), None); // overflowed! + /// assert_eq!(None.and_then(sq_then_to_string), None); /// ``` /// /// Often used to chain fallible operations that may return [`None`]. From f6f93fd7ba348a4e0e2e9ca7af597d117d6337a1 Mon Sep 17 00:00:00 2001 From: cyqsimon <28627918+cyqsimon@users.noreply.github.com> Date: Sat, 12 Feb 2022 12:52:42 +0800 Subject: [PATCH 8/8] Add note on Windows path behaviour --- library/core/src/result.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 334a8990787..801e3a0b3a4 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -1296,6 +1296,7 @@ impl Result { /// ``` /// use std::{io::ErrorKind, path::Path}; /// + /// // Note: on Windows "/" maps to "C:\" /// let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified()); /// assert!(root_modified_time.is_ok()); ///