From 13303a5b8e719ef952ab9b060b67e45f74130882 Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Wed, 26 Mar 2025 14:37:06 +0800 Subject: [PATCH 1/7] Update the index of Result to make the summary more comprehensive --- library/core/src/result.rs | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 48ab9267f216c..494b3745bc234 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -256,11 +256,26 @@ //! //! ## Querying the variant //! -//! The [`is_ok`] and [`is_err`] methods return [`true`] if the [`Result`] -//! is [`Ok`] or [`Err`], respectively. +//! The [`is_ok`] and [`is_err`] methods take the borrow of the [`Result`] +//! and return [`true`] if the [`Result`] is [`Ok`] or [`Err`], respectively. +//! +//! The [`is_ok_and`] and [`is_err_and`] methods take ownership of the [`Result`] +//! and apply the provided function to make a decision. +//! The methods return the same boolean value as the function returns. //! //! [`is_err`]: Result::is_err //! [`is_ok`]: Result::is_ok +//! [`is_ok_and`]: Result::is_ok_and +//! [`is_err_and`]: Result::is_err_and +//! +//! ## Inspecting the variant +//! +//! The [`inspect`] and [`inspect_err`] methods take ownership of the [`Result`] +//! and apply the provided function to the contained value by reference if [`Ok`] +//! or [`Err`], respectively. And then, the [`Result`] is returned. +//! +//! [`inspect`]: Result::inspect +//! [`inspect_err`]: Result::inspect_err //! //! ## Adapters for working with references //! @@ -287,6 +302,7 @@ //! (which must implement the [`Default`] trait) //! * [`unwrap_or_else`] returns the result of evaluating the provided //! function +//! * [`unwrap_unchecked`] is *[undefined behavior]* //! //! The panicking methods [`expect`] and [`unwrap`] require `E` to //! implement the [`Debug`] trait. @@ -297,6 +313,8 @@ //! [`unwrap_or`]: Result::unwrap_or //! [`unwrap_or_default`]: Result::unwrap_or_default //! [`unwrap_or_else`]: Result::unwrap_or_else +//! [`unwrap_unchecked`]: Result::unwrap_unchecked +//! [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html //! //! These methods extract the contained value in a [`Result`] when it //! is the [`Err`] variant. They require `T` to implement the [`Debug`] @@ -304,10 +322,13 @@ //! //! * [`expect_err`] panics with a provided custom message //! * [`unwrap_err`] panics with a generic message +//! * [`unwrap_err_unchecked`] is *[undefined behavior]* //! //! [`Debug`]: crate::fmt::Debug //! [`expect_err`]: Result::expect_err //! [`unwrap_err`]: Result::unwrap_err +//! [`unwrap_err_unchecked`]: Result::unwrap_err_unchecked +//! [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html //! //! ## Transforming contained values //! From f8f23309ca0a77908b7d202bc5780059a86a47d9 Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Mon, 21 Apr 2025 10:14:35 +0800 Subject: [PATCH 2/7] Solved suggestions --- library/core/src/result.rs | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 494b3745bc234..1d3da72b05f3c 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -256,27 +256,18 @@ //! //! ## Querying the variant //! -//! The [`is_ok`] and [`is_err`] methods take the borrow of the [`Result`] +//! The [`is_ok`] and [`is_err`] methods borrow of the [`Result`] //! and return [`true`] if the [`Result`] is [`Ok`] or [`Err`], respectively. //! -//! The [`is_ok_and`] and [`is_err_and`] methods take ownership of the [`Result`] -//! and apply the provided function to make a decision. -//! The methods return the same boolean value as the function returns. +//! The [`is_ok_and`] and [`is_err_and`] methods apply the provided function +//! to the contents of the [`Result`] to produce a boolean value. If this is [`Err`] +//! then a default result is returned instead without executing the function. //! //! [`is_err`]: Result::is_err //! [`is_ok`]: Result::is_ok //! [`is_ok_and`]: Result::is_ok_and //! [`is_err_and`]: Result::is_err_and //! -//! ## Inspecting the variant -//! -//! The [`inspect`] and [`inspect_err`] methods take ownership of the [`Result`] -//! and apply the provided function to the contained value by reference if [`Ok`] -//! or [`Err`], respectively. And then, the [`Result`] is returned. -//! -//! [`inspect`]: Result::inspect -//! [`inspect_err`]: Result::inspect_err -//! //! ## Adapters for working with references //! //! * [`as_ref`] converts from `&Result` to `Result<&T, &E>` @@ -302,7 +293,7 @@ //! (which must implement the [`Default`] trait) //! * [`unwrap_or_else`] returns the result of evaluating the provided //! function -//! * [`unwrap_unchecked`] is *[undefined behavior]* +//! * [`unwrap_unchecked`] produces *[undefined behavior]* //! //! The panicking methods [`expect`] and [`unwrap`] require `E` to //! implement the [`Debug`] trait. @@ -322,7 +313,7 @@ //! //! * [`expect_err`] panics with a provided custom message //! * [`unwrap_err`] panics with a generic message -//! * [`unwrap_err_unchecked`] is *[undefined behavior]* +//! * [`unwrap_err_unchecked`] produces *[undefined behavior]* //! //! [`Debug`]: crate::fmt::Debug //! [`expect_err`]: Result::expect_err @@ -356,16 +347,24 @@ //! * [`map`] transforms [`Result`] into [`Result`] by applying //! the provided function to the contained value of [`Ok`] and leaving //! [`Err`] values unchanged +//! * [`inspect`] takes ownership of the [`Result`] and applies the +//! provided function to the contained value by reference, +//! and then the [`Result`] is returned //! //! [`map`]: Result::map +//! [`inspect`]: Result::inspect //! //! This method transforms the contained value of the [`Err`] variant: //! //! * [`map_err`] transforms [`Result`] into [`Result`] by //! applying the provided function to the contained value of [`Err`] and //! leaving [`Ok`] values unchanged +//! * [`inspect_err`] takes ownership of the [`Result`] and applies the +//! provided function to the contained value of [`Err`] by reference, +//! and then the [`Result`] is returned //! //! [`map_err`]: Result::map_err +//! [`inspect_err`]: Result::inspect_err //! //! These methods transform a [`Result`] into a value of a possibly //! different type `U`: From f86cd705cbae4b155ff5e94f57cde637ec0ed7fa Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Thu, 24 Apr 2025 09:56:42 +0800 Subject: [PATCH 3/7] keep original text for is_ok and is_err --- library/core/src/result.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 1d3da72b05f3c..897ac206b8a81 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -256,12 +256,12 @@ //! //! ## Querying the variant //! -//! The [`is_ok`] and [`is_err`] methods borrow of the [`Result`] -//! and return [`true`] if the [`Result`] is [`Ok`] or [`Err`], respectively. +//! The [`is_ok`] and [`is_err`] methods return [`true`] if the [`Result`] +//! is [`Ok`] or [`Err`], respectively. //! //! The [`is_ok_and`] and [`is_err_and`] methods apply the provided function -//! to the contents of the [`Result`] to produce a boolean value. If this is [`Err`] -//! then a default result is returned instead without executing the function. +//! to the contents of the [`Result`] to produce a boolean value. If the [`Result`]` does not have the expected variant +//! then `false` is returned instead without executing the function. //! //! [`is_err`]: Result::is_err //! [`is_ok`]: Result::is_ok @@ -347,9 +347,9 @@ //! * [`map`] transforms [`Result`] into [`Result`] by applying //! the provided function to the contained value of [`Ok`] and leaving //! [`Err`] values unchanged -//! * [`inspect`] takes ownership of the [`Result`] and applies the +//! * [`inspect`] takes ownership of the [`Result`], applies the //! provided function to the contained value by reference, -//! and then the [`Result`] is returned +//! and then returns the [`Result`] //! //! [`map`]: Result::map //! [`inspect`]: Result::inspect @@ -359,9 +359,9 @@ //! * [`map_err`] transforms [`Result`] into [`Result`] by //! applying the provided function to the contained value of [`Err`] and //! leaving [`Ok`] values unchanged -//! * [`inspect_err`] takes ownership of the [`Result`] and applies the +//! * [`inspect_err`] takes ownership of the [`Result`], applies the //! provided function to the contained value of [`Err`] by reference, -//! and then the [`Result`] is returned +//! and then returns the [`Result`] //! //! [`map_err`]: Result::map_err //! [`inspect_err`]: Result::inspect_err From 56d5efc68c66c144d41a792a6f55db74a737ad56 Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Thu, 24 Apr 2025 10:10:30 +0800 Subject: [PATCH 4/7] add examples using .as_ref() for is_err_and and is_ok_and --- library/core/src/result.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 897ac206b8a81..ae6afb30f1ed3 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -598,6 +598,10 @@ impl Result { /// /// let x: Result = Err("hey"); /// assert_eq!(x.is_ok_and(|x| x > 1), false); + /// + /// let x: Result = Ok("ownership".to_string()); + /// assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true); + /// println!("still alive {:?}", x); /// ``` #[must_use] #[inline] @@ -643,6 +647,10 @@ impl Result { /// /// let x: Result = Ok(123); /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false); + /// + /// let x: Result = Err("ownership"); + /// assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true); + /// println!("still alive {:?}", x); /// ``` #[must_use] #[inline] From 3a14991e77b890c6971e9d02e83d25bc281f2a70 Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Thu, 24 Apr 2025 10:31:53 +0800 Subject: [PATCH 5/7] fix example --- library/core/src/result.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index ae6afb30f1ed3..98369857933c8 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -648,7 +648,7 @@ impl Result { /// let x: Result = Ok(123); /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false); /// - /// let x: Result = Err("ownership"); + /// let x: Result = Err("ownership".to_string()); /// assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true); /// println!("still alive {:?}", x); /// ``` From 1fd928ef89f00994790a7660436db5d05ac762b7 Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Thu, 24 Apr 2025 12:23:53 +0800 Subject: [PATCH 6/7] fix doc error --- library/core/src/result.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 98369857933c8..a512c451659e8 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -260,8 +260,8 @@ //! is [`Ok`] or [`Err`], respectively. //! //! The [`is_ok_and`] and [`is_err_and`] methods apply the provided function -//! to the contents of the [`Result`] to produce a boolean value. If the [`Result`]` does not have the expected variant -//! then `false` is returned instead without executing the function. +//! to the contents of the [`Result`] to produce a boolean value. If the [`Result`] does not have the expected variant +//! then [`false`] is returned instead without executing the function. //! //! [`is_err`]: Result::is_err //! [`is_ok`]: Result::is_ok From cdc729839268c2bd80158030e32a954d56436d3c Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Fri, 25 Apr 2025 11:06:53 +0800 Subject: [PATCH 7/7] Solved suggestions --- library/core/src/result.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/result.rs b/library/core/src/result.rs index a512c451659e8..736ffb7d0caf3 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -342,7 +342,7 @@ //! [`Some(v)`]: Option::Some //! [`transpose`]: Result::transpose //! -//! This method transforms the contained value of the [`Ok`] variant: +//! These methods transform the contained value of the [`Ok`] variant: //! //! * [`map`] transforms [`Result`] into [`Result`] by applying //! the provided function to the contained value of [`Ok`] and leaving @@ -354,7 +354,7 @@ //! [`map`]: Result::map //! [`inspect`]: Result::inspect //! -//! This method transforms the contained value of the [`Err`] variant: +//! These methods transform the contained value of the [`Err`] variant: //! //! * [`map_err`] transforms [`Result`] into [`Result`] by //! applying the provided function to the contained value of [`Err`] and