File 0188-orddict-add-examples.patch of Package erlang
From 1d6f821d6ba78b0a81e5b8d8b8f3acf205c8cb9f Mon Sep 17 00:00:00 2001
From: Kiko Fernandez-Reyes <kiko@erlang.org>
Date: Tue, 21 Mar 2023 14:38:52 +0100
Subject: [PATCH] orddict: add examples
---
lib/stdlib/doc/src/orddict.xml | 118 ++++++++++++++++++++++++++++++++-
1 file changed, 116 insertions(+), 2 deletions(-)
diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml
index 796cb42ede..216298f1d9 100644
--- a/lib/stdlib/doc/src/orddict.xml
+++ b/lib/stdlib/doc/src/orddict.xml
@@ -38,7 +38,7 @@
<p>This module provides a <c>Key</c>-<c>Value</c> dictionary.
An <c>orddict</c> is a representation of a dictionary, where a
list of pairs is used to store the keys and values. The list is
- ordered after the keys in the <em>Erlang term order</em>.</p>
+ ordered after the keys in the <em><seeguide marker="system/reference_manual:expressions#term-comparisons">Erlang term order</seeguide></em>.</p>
<p>This module provides the same interface as the
<seeerl marker="dict"><c>dict(3)</c></seeerl> module
@@ -69,6 +69,24 @@
generated if the initial value associated with <c><anno>Key</anno></c>
is not a list of values.</p>
<p>See also section <seeerl marker="#notes">Notes</seeerl>.</p>
+ <p><em>Example 1:</em></p>
+ <pre>
+1> <input>OrdDict1 = orddict:from_list([{x, []}]).</input>
+[{x,[]}]
+2> <input>OrdDict2 = orddict:append(x, 1, OrdDict1).</input>
+[{x,[1]}]
+3> <input>OrdDict3 = orddict:append(x, 2, OrdDict2).</input>
+[{x,[1,2]}]
+4> <input>orddict:append(y, 3, OrdDict3).</input>
+[{x,[1,2]},{y,[3]}]</pre>
+ <p><em>Example 2:</em></p>
+ <pre>
+1> <input>OrdDict1 = orddict:from_list([{a, no_list}]).</input>
+[{a,no_list}]
+2> <input>orddict:append(a, 1, OrdDict1).</input>
+** exception error: bad argument
+ in operator ++/2
+ called as no_list ++ [1]</pre>
</desc>
</func>
@@ -81,6 +99,14 @@
An exception is generated if the initial value associated with
<c><anno>Key</anno></c> is not a list of values.</p>
<p>See also section <seeerl marker="#notes">Notes</seeerl>.</p>
+ <p><em>Example:</em></p>
+ <pre>
+1> <input>OrdDict1 = orddict:from_list([{x, []}]).</input>
+[{x,[]}]
+2> <input>OrdDict2 = orddict:append_list(x, [1,2], OrdDict1).</input>
+[{x,[1,2]}]
+3> <input>OrdDict3 = orddict:append_list(y, [3,4], OrdDict2).</input>
+[{x,[1,2]},{y,[3,4]}]</pre>
</desc>
</func>
@@ -89,6 +115,12 @@
<fsummary>Erase a key from a dictionary.</fsummary>
<desc>
<p>Erases all items with a specified key from a dictionary.</p>
+ <p><em>Example:</em></p>
+ <pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:erase(a, OrdDict1).</input>
+[{b,2}]</pre>
</desc>
</func>
@@ -101,6 +133,14 @@
the <c><anno>Key</anno></c> is present in the dictionary. An exception
is generated if <c><anno>Key</anno></c> is not in the dictionary.</p>
<p>See also section <seeerl marker="#notes">Notes</seeerl>.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:fetch(a, OrdDict1).</input>
+1
+3> <input>orddict:fetch(missing, OrdDict1).</input>
+** exception error: no function clause matching orddict:fetch(missing,[])</pre>
</desc>
</func>
@@ -109,6 +149,12 @@
<fsummary>Return all keys in a dictionary.</fsummary>
<desc>
<p>Returns a list of all keys in a dictionary.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:fetch_keys(OrdDict1).</input>
+[a,b]</pre>
</desc>
</func>
@@ -118,6 +164,14 @@
<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>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:take(a, OrdDict1).</input>
+{1, [{b,2}]}
+3> <input>orddict:take(missing, OrdDict1).</input>
+error</pre>
</desc>
</func>
@@ -129,6 +183,12 @@
in <c><anno>Orddict1</anno></c> for which
<c><anno>Pred</anno>(<anno>Key</anno>, <anno>Value</anno>)</c> is
<c>true</c>.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:filter(fun (K, V) -> V > 1 end, OrdDict1).</input>
+[{b,2}]</pre>
</desc>
</func>
@@ -141,6 +201,14 @@
the value associated with <c><anno>Key</anno></c>, or <c>error</c> if
the key is not present in the dictionary.</p>
<p>See also section <seeerl marker="#notes">Notes</seeerl>.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:find(a, OrdDict1).</input>
+{ok,1}
+3> <input>orddict:find(c, OrdDict1).</input>
+error</pre>
</desc>
</func>
@@ -153,6 +221,12 @@
(short for accumulator). <c><anno>Fun</anno></c> must return a new
accumulator that is passed to the next call. <c><anno>Acc0</anno></c>
is returned if the list is empty.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:fold(fun (K, V, Acc) -> [{K, V+100} | Acc] end, [], OrdDict1).</input>
+[{b,102},{a,101}]</pre>
</desc>
</func>
@@ -188,7 +262,13 @@
<fsummary>Map a function over a dictionary.</fsummary>
<desc>
<p>Calls <c><anno>Fun</anno></c> on successive keys and values of
- <c><anno>Orddict1</anno></c> tvo return a new value for each key.</p>
+ <c><anno>Orddict1</anno></c> to return a new value for each key.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:map(fun (_K, V) -> V + 100 end, OrdDict1).</input>
+[{a,101},{b,102}]</pre>
</desc>
</func>
@@ -208,6 +288,14 @@ merge(Fun, D1, D2) ->
fold(fun (K, V1, D) ->
update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
end, D2, D1).</code>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>OrdDict2 = orddict:from_list([{b, 7}, {c, 8}]).</input>
+[{b,7},{c,8}]
+3> <input>orddict:merge(fun (K, V1, V2) -> V1 * V2 end, OrdDict1, OrdDict2).</input>
+[{a, 1},{b, 14},{c,8}]</pre>
</desc>
</func>
@@ -236,6 +324,14 @@ merge(Fun, D1, D2) ->
dictionary. If the <c><anno>Key</anno></c> already exists in
<c><anno>Orddict1</anno></c>,
the associated value is replaced by <c><anno>Value</anno></c>.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:store(a, 99, OrdDict1).</input>
+[{a,99},{b,2}]
+3> <input>orddict:store(c, 100, OrdDict1).</input>
+[{a,1},{b,2},{c,99}]</pre>
</desc>
</func>
@@ -254,6 +350,12 @@ merge(Fun, D1, D2) ->
<p>Updates a value in a dictionary by calling <c><anno>Fun</anno></c>
on the value to get a new value. An exception is generated if
<c><anno>Key</anno></c> is not present in the dictionary.</p>
+ <p><em>Example:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:update(a, fun (V) -> V1 + 100 end, OrdDict1).</input>
+[{a, 101}, {b, 102}]</pre>
</desc>
</func>
@@ -269,6 +371,18 @@ merge(Fun, D1, D2) ->
<code type="none">
append(Key, Val, D) ->
update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).</code>
+ <p><em>Example 1:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:update(c, fun (V) -> V1 + 100 end, 99, OrdDict1).</input>
+[{a,1},{b,2},{c,99}]</pre>
+ <p><em>Example 2:</em></p>
+<pre>
+1> <input>OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).</input>
+[{a,1},{b,2}]
+2> <input>orddict:update(a, fun (V) -> V1 + 100 end, 99, OrdDict1).</input>
+[{a,101},{b,2}]</pre>
</desc>
</func>
--
2.35.3
