File 5884-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
