From fc126df5a7bf6cf74a8fcf16d2f8c2902c7d9e73 Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Wed, 26 Mar 2025 08:23:43 +0800 Subject: [PATCH 1/5] Update the index.html of Option to make the summary more comprehensive --- library/core/src/option.rs | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index 7ec0ac7127142..ee755f6629e5b 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -159,11 +159,17 @@ //! //! ## Querying the variant //! -//! The [`is_some`] and [`is_none`] methods return [`true`] if the [`Option`] -//! is [`Some`] or [`None`], respectively. +//! The [`is_some`] and [`is_none`] methods take a borrow of the [`Option`] +//! and return [`true`] if the [`Option`] is [`Some`] or [`None`], respectively. +//! +//! The [`is_some_and`] and [`is_none_or`] methods take ownership of the [`Option`] +//! and apply the provided function to make a decision. +//! The methods return the same boolean value as the function returns. //! //! [`is_none`]: Option::is_none //! [`is_some`]: Option::is_some +//! [`is_some_and`]: Option::is_some_and +//! [`is_none_or`]: Option::is_none_or //! //! ## Adapters for working with references //! @@ -177,6 +183,10 @@ //! [Option]<[Pin]<[&]T>> //! * [`as_pin_mut`] converts from [Pin]<[&mut] [Option]\> to //! [Option]<[Pin]<[&mut] T>> +//! * [`as_slice`] returns a slice of the contained value, if any. +//! If this is [`None`], an empty slice is returned. +//! * [`as_mut_slice`] returns a mutable slice of the contained value, if any. +//! If this is [`None`], an empty slice is returned. //! //! [&]: reference "shared reference" //! [&mut]: reference "mutable reference" @@ -187,6 +197,8 @@ //! [`as_pin_mut`]: Option::as_pin_mut //! [`as_pin_ref`]: Option::as_pin_ref //! [`as_ref`]: Option::as_ref +//! [`as_slice`]: Option::as_slice +//! [`as_mut_slice`]: Option::as_mut_slice //! //! ## Extracting the contained value //! @@ -200,12 +212,16 @@ //! (which must implement the [`Default`] trait) //! * [`unwrap_or_else`] returns the result of evaluating the provided //! function +//! * [`unwrap_unchecked`] returns the contained value, without checking +//! calling this method on None is *[undefined behavior]* //! //! [`expect`]: Option::expect //! [`unwrap`]: Option::unwrap //! [`unwrap_or`]: Option::unwrap_or //! [`unwrap_or_default`]: Option::unwrap_or_default //! [`unwrap_or_else`]: Option::unwrap_or_else +//! [`unwrap_unchecked`]: Option::unwrap_unchecked +//! [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html //! //! ## Transforming contained values //! @@ -232,6 +248,8 @@ //! if the function returns `true`; otherwise, returns [`None`] //! * [`flatten`] removes one level of nesting from an //! [`Option>`] +//! * [`insert`] calls the provided function with a reference to +//! the contained value if [`Some`] //! * [`map`] transforms [`Option`] to [`Option`] by applying the //! provided function to the contained value of [`Some`] and leaving //! [`None`] values unchanged @@ -239,6 +257,7 @@ //! [`Some(t)`]: Some //! [`filter`]: Option::filter //! [`flatten`]: Option::flatten +//! [`insert`]: Option::insert //! [`map`]: Option::map //! //! These methods transform [`Option`] to a value of a possibly From 159ae8fcee04302d24c9d1afc077697b8f266e11 Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Wed, 26 Mar 2025 14:50:03 +0800 Subject: [PATCH 2/5] Keeps the inspect() classification the same as in Result --- library/core/src/option.rs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index ee755f6629e5b..a1f0224c7791f 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -171,6 +171,13 @@ //! [`is_some_and`]: Option::is_some_and //! [`is_none_or`]: Option::is_none_or //! +//! ## Inspecting the variant +//! +//! The [`inspect`] method takes ownership of the [`Option`] +//! and applies the provided function to the contained value by reference if [`Some`] +//! +//! [`inspect`]: Option::inspect +//! //! ## Adapters for working with references //! //! * [`as_ref`] converts from [&][][Option]\ to [Option]<[&]T> @@ -248,8 +255,6 @@ //! if the function returns `true`; otherwise, returns [`None`] //! * [`flatten`] removes one level of nesting from an //! [`Option>`] -//! * [`insert`] calls the provided function with a reference to -//! the contained value if [`Some`] //! * [`map`] transforms [`Option`] to [`Option`] by applying the //! provided function to the contained value of [`Some`] and leaving //! [`None`] values unchanged @@ -257,7 +262,6 @@ //! [`Some(t)`]: Some //! [`filter`]: Option::filter //! [`flatten`]: Option::flatten -//! [`insert`]: Option::insert //! [`map`]: Option::map //! //! These methods transform [`Option`] to a value of a possibly From ea0b6cba06b01428ada0fddff5adb922fa28370f Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Mon, 21 Apr 2025 09:54:11 +0800 Subject: [PATCH 3/5] Solved suggestions --- library/core/src/option.rs | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index a1f0224c7791f..9789912719b1c 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -159,25 +159,18 @@ //! //! ## Querying the variant //! -//! The [`is_some`] and [`is_none`] methods take a borrow of the [`Option`] +//! The [`is_some`] and [`is_none`] methods borrow of the [`Option`] //! and return [`true`] if the [`Option`] is [`Some`] or [`None`], respectively. //! -//! The [`is_some_and`] and [`is_none_or`] methods take ownership of the [`Option`] -//! and apply the provided function to make a decision. -//! The methods return the same boolean value as the function returns. +//! The [`is_some_and`] and [`is_none_or`] methods apply the provided function +//! to the contents of the [`Option`] to produce a boolean value. +//! If this is [`None`] then a default result is returned instead without executing the function. //! //! [`is_none`]: Option::is_none //! [`is_some`]: Option::is_some //! [`is_some_and`]: Option::is_some_and //! [`is_none_or`]: Option::is_none_or //! -//! ## Inspecting the variant -//! -//! The [`inspect`] method takes ownership of the [`Option`] -//! and applies the provided function to the contained value by reference if [`Some`] -//! -//! [`inspect`]: Option::inspect -//! //! ## Adapters for working with references //! //! * [`as_ref`] converts from [&][][Option]\ to [Option]<[&]T> @@ -190,9 +183,9 @@ //! [Option]<[Pin]<[&]T>> //! * [`as_pin_mut`] converts from [Pin]<[&mut] [Option]\> to //! [Option]<[Pin]<[&mut] T>> -//! * [`as_slice`] returns a slice of the contained value, if any. +//! * [`as_slice`] returns a one-element slice of the contained value, if any. //! If this is [`None`], an empty slice is returned. -//! * [`as_mut_slice`] returns a mutable slice of the contained value, if any. +//! * [`as_mut_slice`] returns a mutable one-element slice of the contained value, if any. //! If this is [`None`], an empty slice is returned. //! //! [&]: reference "shared reference" @@ -219,8 +212,7 @@ //! (which must implement the [`Default`] trait) //! * [`unwrap_or_else`] returns the result of evaluating the provided //! function -//! * [`unwrap_unchecked`] returns the contained value, without checking -//! calling this method on None is *[undefined behavior]* +//! * [`unwrap_unchecked`] produces *[undefined behavior]* //! //! [`expect`]: Option::expect //! [`unwrap`]: Option::unwrap @@ -253,8 +245,9 @@ //! * [`filter`] calls the provided predicate function on the contained //! value `t` if the [`Option`] is [`Some(t)`], and returns [`Some(t)`] //! if the function returns `true`; otherwise, returns [`None`] -//! * [`flatten`] removes one level of nesting from an -//! [`Option>`] +//! * [`flatten`] removes one level of nesting from an [`Option>`] +//! * [`inspect`] method takes ownership of the [`Option`] and applies +//! the provided function to the contained value by reference if [`Some`] //! * [`map`] transforms [`Option`] to [`Option`] by applying the //! provided function to the contained value of [`Some`] and leaving //! [`None`] values unchanged @@ -262,6 +255,7 @@ //! [`Some(t)`]: Some //! [`filter`]: Option::filter //! [`flatten`]: Option::flatten +//! [`inspect`]: Option::inspect //! [`map`]: Option::map //! //! These methods transform [`Option`] to a value of a possibly From c0446d3cbb4849dfe1e6824eb20f9fa0426e2d4b Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Thu, 24 Apr 2025 10:12:14 +0800 Subject: [PATCH 4/5] keep the original text for is_some and is_none --- 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 9789912719b1c..c0005cdee0866 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -159,8 +159,8 @@ //! //! ## Querying the variant //! -//! The [`is_some`] and [`is_none`] methods borrow of the [`Option`] -//! and return [`true`] if the [`Option`] is [`Some`] or [`None`], respectively. +//! The [`is_some`] and [`is_none`] methods return [`true`] if the [`Option`] +//! is [`Some`] or [`None`], respectively. //! //! The [`is_some_and`] and [`is_none_or`] methods apply the provided function //! to the contents of the [`Option`] to produce a boolean value. From d0ac97d64910de81cab785055428865f300a86cb Mon Sep 17 00:00:00 2001 From: Hegui Dai Date: Thu, 24 Apr 2025 10:22:49 +0800 Subject: [PATCH 5/5] add examples using .as_ref() for is_some_and and is_none_or --- library/core/src/option.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index c0005cdee0866..aed5a043c11a3 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -638,6 +638,10 @@ impl Option { /// /// let x: Option = None; /// assert_eq!(x.is_some_and(|x| x > 1), false); + /// + /// let x: Option = Some("ownership".to_string()); + /// assert_eq!(x.as_ref().is_some_and(|x| x.len() > 1), true); + /// println!("still alive {:?}", x); /// ``` #[must_use] #[inline] @@ -682,6 +686,10 @@ impl Option { /// /// let x: Option = None; /// assert_eq!(x.is_none_or(|x| x > 1), true); + /// + /// let x: Option = Some("ownership".to_string()); + /// assert_eq!(x.as_ref().is_none_or(|x| x.len() > 1), true); + /// println!("still alive {:?}", x); /// ``` #[must_use] #[inline]