File 0184-Improve-specs-and-docs-for-maps-groups_fro... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0184-Improve-specs-and-docs-for-maps-groups_from_list-2-3.patch of Package erlang

From 3eb4eea13fbd96d66c38663a581751c27253c722 Mon Sep 17 00:00:00 2001
From: Maria Scott <maria-12648430@hnc-agency.org>
Date: Mon, 19 Dec 2022 10:16:45 +0100
Subject: [PATCH] Improve specs and docs for maps:groups_from_list/2,3

---
 lib/stdlib/doc/src/maps.xml | 46 +++++++++++++++++++++++--------------
 lib/stdlib/src/maps.erl     | 29 ++++++++++++-----------
 2 files changed, 44 insertions(+), 31 deletions(-)

diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml
index ce9fbc230a..62b3d4877d 100644
--- a/lib/stdlib/doc/src/maps.xml
+++ b/lib/stdlib/doc/src/maps.xml
@@ -232,15 +232,19 @@ val1
 
     <func>
       <name name="groups_from_list" arity="2" since="OTP 25.0"/>
-      <fsummary>Splits the list into groups using a function as discriminator.</fsummary>
-      <desc>
-        <p>The result is a map where each key is given by <anno>Fun</anno>
-        and each value is a list of elements. The order of elements within
-        each list is preserved from the list.</p>
+      <fsummary>Partitions a list into groups using a function as discriminator.</fsummary>
+      <desc>
+        <p>Partitions the given <c><anno>List</anno></c> into a map of groups.</p>
+        <p>The result is a map where each key is given by <c><anno>KeyFun</anno></c>
+          and each value is a list of elements from the given <c><anno>List</anno></c>
+          for which <c><anno>KeyFun</anno></c> returned the same key.</p>
+        <p>The order of elements within each group list is preserved from the original
+          list.</p>
         <p><em>Examples:</em></p>
         <pre>
-> <input>maps:groups_from_list(fun(X) -> X rem 2 end, [1,2,3]).</input>
-#{0 => [2], 1 => [1, 3]}
+> <input>EvenOdd = fun(X) -> case X rem 2 of 0 -> even; 1 -> odd end end,</input>
+<input>maps:groups_from_list(EvenOdd, [1, 2, 3]).</input>
+#{even => [2], odd => [1, 3]}
 > <input>maps:groups_from_list(fun erlang:length/1, ["ant", "buffalo", "cat", "dingo"]).</input>
 #{3 => ["ant", "cat"], 5 => ["dingo"], 7 => ["buffalo"]}</pre>
       </desc>
@@ -248,18 +252,26 @@ val1
 
     <func>
       <name name="groups_from_list" arity="3" since="OTP 25.0"/>
-      <fsummary>Splits the list into groups using a function as discriminator.</fsummary>
-      <desc>
-        <p>The result is a map where each key is given by
-        <anno>Fun</anno> and each value is a list of elements given by
-        the <anno>ValueFun</anno>. The order of elements within each
-        list is preserved from the list.</p>
+      <fsummary>Partitions a list into groups using a function as discriminator.</fsummary>
+      <desc>
+        <p>Partitions the given <c><anno>List</anno></c> into a map of groups.</p>
+        <p>The result is a map where each key is given by <c><anno>KeyFun</anno></c>
+          and each value is a list of elements from the given <c><anno>List</anno></c>,
+          mapped via <c><anno>ValueFun</anno></c>, for which <c><anno>KeyFun</anno></c>
+          returned the same key.</p>
+        <p>The order of elements within each group list is preserved from the
+          original list.</p>
         <p><em>Examples:</em></p>
         <pre>
-> <input>maps:groups_from_list(fun(X) -> X rem 2 end, fun(X) -> X*X end, [1,2,3]).</input>
-#{0 => [4], 1 => [1, 9]}
-> <input>maps:groups_from_list(fun erlang:length/1, fun lists:reverse/1, ["ant", "buffalo", "cat", "dingo"]).</input>
-#{3 => ["tna","tac"],5 => ["ognid"],7 => ["olaffub"]}</pre>
+> <input>EvenOdd = fun(X) -> case X rem 2 of 0 -> even; 1 -> odd end end,</input>
+> <input>Square = fun(X) -> X * X end,</input>
+> <input>maps:groups_from_list(EvenOdd, Square, [1, 2, 3]).</input>
+#{even => [4], odd => [1, 9]}
+> <input>maps:groups_from_list(</input>
+<input>    fun erlang:length/1,</input>
+<input>    fun lists:reverse/1,</input>
+<input>    ["ant", "buffalo", "cat", "dingo"]).</input>
+#{3 => ["tna", "tac"],5 => ["ognid"],7 => ["olaffub"]}</pre>
       </desc>
     </func>
 
diff --git a/lib/stdlib/src/maps.erl b/lib/stdlib/src/maps.erl
index c7107031fb..5910706f95 100644
--- a/lib/stdlib/src/maps.erl
+++ b/lib/stdlib/src/maps.erl
@@ -500,12 +500,13 @@ with_1([], _Map) -> [].
 
 %% groups_from_list/2 & groups_from_list/3
 
--spec groups_from_list(Fun, List) -> MapOut when
-    Fun :: fun((Elem :: T) -> Selected),
-    MapOut :: #{Selected => List},
-    Selected :: term(),
-    List :: [T],
-    T :: term().
+-spec groups_from_list(KeyFun, List) -> GroupsMap when
+    KeyFun :: fun((Elem) -> Key),
+    GroupsMap :: #{Key => Group},
+    Key :: term(),
+    List :: [Elem],
+    Group :: [Elem],
+    Elem :: term().
 
 groups_from_list(Fun, List0) when is_function(Fun, 1) ->
     try lists:reverse(List0) of
@@ -528,15 +529,15 @@ groups_from_list_1(Fun, [H | Tail], Acc) ->
 groups_from_list_1(_Fun, [], Acc) ->
     Acc.
 
--spec groups_from_list(Fun, ValueFun, List) -> MapOut when
-    Fun :: fun((Elem :: T) -> Key),
-    ValueFun :: fun((Elem :: T) -> ValOut),
-    MapOut :: #{Key := ListOut},
+-spec groups_from_list(KeyFun, ValueFun, List) -> GroupsMap when
+    KeyFun :: fun((Elem) -> Key),
+    ValueFun :: fun((Elem) -> Value),
+    GroupsMap :: #{Key := Group},
     Key :: term(),
-    ValOut :: term(),
-    List :: [T],
-    ListOut :: [ValOut],
-    T :: term().
+    Value :: term(),
+    List :: [Elem],
+    Group :: [Value],
+    Elem :: term().
 
 groups_from_list(Fun, ValueFun, List0) when is_function(Fun, 1),
                                             is_function(ValueFun, 1) ->
-- 
2.35.3

Places

File 0184-Improve-specs-and-docs-for-maps-groups_from_list-2-3.patch of Package erlang

Places