Add a warning about extract invalidating iterators (not just the iterator of the…

Add a warning about extract invalidating iterators (not just the iterator of the element being extracted).

PiperOrigin-RevId: 485120182
Change-Id: Ic54d538721678bed0a748dacbf33c319e62b93b8

absl/container/btree_map.h

@@ -44,8 +44,8 @@
 // an issue if insertion and deletion operations are interleaved with the use of
 // an issue if insertion and deletion operations are interleaved with the use of
 // more than one iterator, pointer, or reference simultaneously. For this
 // more than one iterator, pointer, or reference simultaneously. For this
 // reason, `insert()` and `erase()` return a valid iterator at the current
 // reason, `insert()` and `erase()` return a valid iterator at the current
-// position. Another important difference is that key-types must be
-// copy-constructible.
+// position (and `extract()` cannot be used in this way). Another important
+// difference is that key-types must be copy-constructible.
 //
 //
 // Another API difference is that btree iterators can be subtracted, and this
 // Another API difference is that btree iterators can be subtracted, and this
 // is faster than using std::distance.
 // is faster than using std::distance.
@@ -325,7 +325,8 @@ class btree_map
   // btree_map::extract()
   // btree_map::extract()
   //
   //
   // Extracts the indicated element, erasing it in the process, and returns it
   // Extracts the indicated element, erasing it in the process, and returns it
-  // as a C++17-compatible node handle. Overloads are listed below.
+  // as a C++17-compatible node handle. Any references, pointers, or iterators
+  // are invalidated. Overloads are listed below.
   //
   //
   // node_type extract(const_iterator position):
   // node_type extract(const_iterator position):
   //
   //

absl/container/btree_set.h

@@ -44,7 +44,7 @@
 // an issue if insertion and deletion operations are interleaved with the use of
 // an issue if insertion and deletion operations are interleaved with the use of
 // more than one iterator, pointer, or reference simultaneously. For this
 // more than one iterator, pointer, or reference simultaneously. For this
 // reason, `insert()` and `erase()` return a valid iterator at the current
 // reason, `insert()` and `erase()` return a valid iterator at the current
-// position.
+// position (and `extract()` cannot be used in this way).
 //
 //
 // Another API difference is that btree iterators can be subtracted, and this
 // Another API difference is that btree iterators can be subtracted, and this
 // is faster than using std::distance.
 // is faster than using std::distance.
@@ -272,7 +272,8 @@ class btree_set
   // btree_set::extract()
   // btree_set::extract()
   //
   //
   // Extracts the indicated element, erasing it in the process, and returns it
   // Extracts the indicated element, erasing it in the process, and returns it
-  // as a C++17-compatible node handle. Overloads are listed below.
+  // as a C++17-compatible node handle. Any references, pointers, or iterators
+  // are invalidated. Overloads are listed below.
   //
   //
   // node_type extract(const_iterator position):
   // node_type extract(const_iterator position):
   //
   //