From a2d92dff3a8acc534daeeb3dea5edda406a6ab0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Fri, 16 Dec 2016 12:50:28 +0100
Subject: Add take/2 to all dictionary modules

Similar to maps:take/2, add take/2 to the other dictionary
modules in STDLIB:

  orddict:take(Key, Dict) -> {Val,NewDict} | 'error'.
  dict:take(Key, Dict) -> {Val,NewDict} | 'error'.
  gb_trees:take(Key, Dict) -> {Val,NewDict}.

For gb_trees also add:

  gb_trees:take_any(Key, Dict) -> {Val,NewDict} | 'error'.

gb_trees already has delete() and delete_any(), so we will
follow that design pattern.

Suggested by Boris Bochkaryov in https://github.com/erlang/otp/pull/1209.
---
 lib/stdlib/doc/src/dict.xml     | 10 ++++++++++
 lib/stdlib/doc/src/gb_trees.xml | 22 ++++++++++++++++++++++
 lib/stdlib/doc/src/orddict.xml  |  9 +++++++++
 3 files changed, 41 insertions(+)

(limited to 'lib/stdlib/doc/src')

diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml
index c926ff1b5b..c229a18721 100644
--- a/lib/stdlib/doc/src/dict.xml
+++ b/lib/stdlib/doc/src/dict.xml
@@ -105,6 +105,16 @@
       </desc>
     </func>
 
+    <func>
+      <name name="take" arity="2"/>
+      <fsummary>Return value and new dictionary without element with this value.</fsummary>
+      <desc>
+        <p>This function returns value from dictionary and a
+        new dictionary without this value.
+        Returns <c>error</c> if the key is not present in the dictionary.</p>
+      </desc>
+    </func>
+
     <func>
       <name name="filter" arity="2"/>
       <fsummary>Select elements that satisfy a predicate.</fsummary>
diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml
index 790d4b8bf1..5cfff021c1 100644
--- a/lib/stdlib/doc/src/gb_trees.xml
+++ b/lib/stdlib/doc/src/gb_trees.xml
@@ -108,6 +108,28 @@
       </desc>
     </func>
 
+    <func>
+      <name name="take" arity="2"/>
+      <fsummary>Returns a value and new tree without node with key <c>Key</c>.</fsummary>
+      <desc>
+        <p>Returns a value <c><anno>Value</anno></c> from node with key <c><anno>Key</anno></c>
+          and new <c><anno>Tree2</anno></c> without the node with this value.
+          Assumes that the node with key is present in the tree,
+         crashes otherwise.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="take_any" arity="2"/>
+      <fsummary>Returns a value and new tree without node with key <c>Key</c>.</fsummary>
+      <desc>
+        <p>Returns a value <c><anno>Value</anno></c> from node with key <c><anno>Key</anno></c>
+          and new <c><anno>Tree2</anno></c> without the node with this value.
+          Returns <c>error</c> if the node with the key is not present in
+          the tree.</p>
+      </desc>
+    </func>
+
     <func>
       <name name="empty" arity="0"/>
       <fsummary>Return an empty tree.</fsummary>
diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml
index 109b038cb5..26bbf499c6 100644
--- a/lib/stdlib/doc/src/orddict.xml
+++ b/lib/stdlib/doc/src/orddict.xml
@@ -112,6 +112,15 @@
       </desc>
     </func>
 
+    <func>
+      <name name="take" arity="2"/>
+      <fsummary>Return value and new dictionary without element with this value.</fsummary>
+      <desc>
+        <p>This function returns value from dictionary and new dictionary without this value.
+            Returns <c>error</c> if the key is not present in the dictionary.</p>
+      </desc>
+    </func>
+
     <func>
       <name name="filter" arity="2"/>
       <fsummary>Select elements that satisfy a predicate.</fsummary>
-- 
cgit v1.2.3