From 7265bef2e7d4320e809ca6694787925cd0d7b8cb Mon Sep 17 00:00:00 2001
From: Taylor Yu <tlyu@mit.edu>
Date: Fri, 11 Jun 2021 13:10:29 -0500
Subject: [PATCH] add modify-in-place methods to option overview

---
 library/core/src/option.rs | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/library/core/src/option.rs b/library/core/src/option.rs
index c1b9517658a..dea32872243 100644
--- a/library/core/src/option.rs
+++ b/library/core/src/option.rs
@@ -296,6 +296,35 @@
 //! }
 //! ```
 //!
+//! ## Modifying an [`Option`] in-place
+//!
+//! These methods return a mutable reference to the contained value of a
+//! [`Some`].
+//!
+//! * [`insert`] inserts a value, dropping any old contents
+//! * [`get_or_insert`] gets the current value, inserting a provided
+//!   default value if it is [`None`]
+//! * [`get_or_insert_default`] gets the current value, inserting the
+//!   default value of type `T` if it is [`None`]
+//! * [`get_or_insert_with`] gets the current value, inserting a default
+//!   computed by the provided function if it is [`None`]
+//!
+//! [`insert`]: Option::insert
+//! [`get_or_insert`]: Option::get_or_insert
+//! [`get_or_insert_default`]: Option::get_or_insert_default
+//! [`get_or_insert_with`]: Option::get_or_insert_with
+//!
+//! These methods transfer ownership of the [`Option`].
+//!
+//! * [`take`] takes ownership of the [`Option`], including any contained
+//!   value, replacing it with [`None`]
+//! * [`replace`] takes ownership of the [`Option`], including any
+//!   contained value, replacing it with a [`Some`] containing the provided
+//!   value
+//!
+//! [`take`]: Option::take
+//! [`replace`]: Option::replace
+//!
 //! # Examples
 //!
 //! Basic pattern matching on [`Option`]: