File 0188-orddict-add-examples.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

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

Places

File 0188-orddict-add-examples.patch of Package erlang

Places