From f61cff7c0889365029176ba7f0de7b84f3579e4e Mon Sep 17 00:00:00 2001
From: Martin Leitner-Ankerl <martin.ankerl@gmail.com>
Date: Sat, 23 Dec 2023 08:56:50 +0100
Subject: [PATCH] update README with extract() api

---
 README.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index a5f94c5c..3d022446 100644
--- a/README.md
+++ b/README.md
@@ -28,8 +28,9 @@ Additionally, there are `ankerl::unordered_dense::segmented_map` and `ankerl::un
     - [3.2.6. Hash the Whole Memory](#326-hash-the-whole-memory)
   - [3.3. Container API](#33-container-api)
     - [3.3.1. `auto extract() && -> value_container_type`](#331-auto-extract----value_container_type)
-    - [3.3.2. `[[nodiscard]] auto values() const noexcept -> value_container_type const&`](#332-nodiscard-auto-values-const-noexcept---value_container_type-const)
-    - [3.3.3. `auto replace(value_container_type&& container)`](#333-auto-replacevalue_container_type-container)
+    - [3.3.2. `extract()` single Elements](#332-extract-single-elements)
+    - [3.3.3. `[[nodiscard]] auto values() const noexcept -> value_container_type const&`](#333-nodiscard-auto-values-const-noexcept---value_container_type-const)
+    - [3.3.4. `auto replace(value_container_type&& container)`](#334-auto-replacevalue_container_type-container)
   - [3.4. Custom Container Types](#34-custom-container-types)
   - [3.5. Custom Bucket Types](#35-custom-bucket-types)
     - [3.5.1. `ankerl::unordered_dense::bucket_type::standard`](#351-ankerlunordered_densebucket_typestandard)
@@ -257,11 +258,17 @@ In addition to the standard `std::unordered_map` API (see https://en.cppreferenc
 
 Extracts the internally used container. `*this` is emptied.
 
-#### 3.3.2. `[[nodiscard]] auto values() const noexcept -> value_container_type const&`
+#### 3.3.2. `extract()` single Elements
+
+Similar to `erase()` I have an API call `extract()`. It behaves exactly the same as `erase`, except that the return value is the moved element that is removed from the container:
+
+Note that the iterator interface `auto extract(const_iterator) -> value_type` differs from the key interface which returns an optional: `auto extract(Key const& key) -> std::optional<value_type>`.
+
+#### 3.3.3. `[[nodiscard]] auto values() const noexcept -> value_container_type const&`
 
 Exposes the underlying values container.
 
-#### 3.3.3. `auto replace(value_container_type&& container)`
+#### 3.3.4. `auto replace(value_container_type&& container)`
 
 Discards the internally held container and replaces it with the one passed. Non-unique elements are
 removed, and the container will be partly reordered when non-unique elements are found.