File 3932-Polish-documentation-for-the-dict-modules.patch of Package erlang
From 3ae523b78cd5ede7e2717a892525c1f5d9e1aff7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Tue, 18 Feb 2025 11:43:59 +0100
Subject: [PATCH 2/2] Polish documentation for the dict modules
Ensure that the first sentence describing each function makes sense
by itself when shown in the Summary part of the documentation.
Add examples for all functions.
While at it, also remove comments for documented functions, and
remove out-commented code, and do some other minor clean ups.
---
lib/stdlib/src/dict.erl | 403 +++++++++++++++---------
lib/stdlib/src/gb_trees.erl | 542 +++++++++++++++++++++++----------
lib/stdlib/src/orddict.erl | 224 ++++++++------
lib/stdlib/test/dict_SUITE.erl | 23 +-
4 files changed, 800 insertions(+), 392 deletions(-)
diff --git a/lib/stdlib/src/dict.erl b/lib/stdlib/src/dict.erl
index 3f351a5f5f..477095791f 100644
--- a/lib/stdlib/src/dict.erl
+++ b/lib/stdlib/src/dict.erl
@@ -43,36 +43,17 @@ A Key-value dictionary.
The representation of a dictionary is not defined.
This module provides the same interface as the `m:orddict` module. One
-difference is that while this module considers two keys as different if they do
-not match (`=:=`), `orddict` considers two keys as different if and only if they
-do not compare equal (`==`).
+difference is that while this module considers two keys as different
+if they do not match (`=:=`), `orddict` considers two keys as
+different if and only if they do not compare equal (`==`).
-## Notes
-
-[](){: #notes }
-
-Functions `append` and `append_list` are included so that keyed values can be
-stored in a list _accumulator_, for example:
-
-```erlang
-> D0 = dict:new(),
- D1 = dict:store(files, [], D0),
- D2 = dict:append(files, f1, D1),
- D3 = dict:append(files, f2, D2),
- D4 = dict:append(files, f3, D3),
- dict:fetch(files, D4).
-[f1,f2,f3]
-```
-
-This saves the trouble of first fetching a keyed value, appending a new value to
-the list of stored values, and storing the result.
-
-Function `fetch` is to be used if the key is known to be in the dictionary,
-otherwise function `find`.
+> #### Note {: .info }
+>
+> For new code, prefer `m:maps` over this module.
## See Also
-`m:gb_trees`, `m:orddict`
+`m:gb_trees`, `m:orddict`, `m:maps`
""".
-compile([{nowarn_deprecated_function, [{erlang,phash,2}]}]).
@@ -84,10 +65,6 @@ otherwise function `find`.
-export_type([dict/0, dict/2]).
-%% Low-level interface.
-%%-export([get_slot/2,get_bucket/2,on_bucket/3,fold_dict/3,
-%% maybe_expand/2,maybe_contract/2]).
-
%% Note: mk_seg/1 must be changed too if seg_size is changed.
-define(seg_size, 16).
-define(max_seg, 32).
@@ -117,16 +94,35 @@ otherwise function `find`.
-opaque dict(Key, Value) :: #dict{segs :: segs(Key, Value)}.
-define(kv(K,V), [K|V]). % Key-Value pair format
-%%-define(kv(K,V), {K,V}). % Key-Value pair format
--doc "Creates a new dictionary.".
+-doc """
+Creates a new dictionary.
+
+## Examples
+
+```erlang
+1> dict:new().
+```
+""".
-spec new() -> dict().
new() ->
Empty = mk_seg(?seg_size),
#dict{empty=Empty,segs={Empty}}.
--doc "Tests if `Key` is contained in dictionary `Dict`.".
+-doc """
+Tests whether `Key` is contained in dictionary `Dict`.
+
+## Examples
+
+```erlang
+1> Dict = dict:from_list([{count,0}]).
+2> dict:is_key(count, Dict).
+true
+3> dict:is_key(table, Dict).
+false
+```
+""".
-spec is_key(Key, Dict) -> boolean() when
Dict :: dict(Key, Value :: term()).
@@ -139,7 +135,17 @@ find_key(K, [?kv(K,_Val)|_]) -> true;
find_key(K, [_|Bkt]) -> find_key(K, Bkt);
find_key(_, []) -> false.
--doc "Converts dictionary `Dict` to a list representation.".
+-doc """
+Converts a dictionary to a list representation.
+
+## Examples
+
+```erlang
+1> Dict = dict:from_list([{2,b},{1,a}]).
+2> lists:sort(dict:to_list(Dict)).
+[{1,a},{2,b}]
+```
+""".
-spec to_list(Dict) -> List when
Dict :: dict(Key, Value),
List :: [{Key, Value}].
@@ -147,7 +153,17 @@ find_key(_, []) -> false.
to_list(D) ->
fold(fun (Key, Val, List) -> [{Key,Val}|List] end, [], D).
--doc "Converts the `Key`-`Value` list `List` to dictionary `Dict`.".
+-doc """
+Converts the `Key`-`Value` list `List` to dictionary `Dict`.
+
+## Examples
+
+```erlang
+1> Dict = dict:from_list([{2,b},{1,a}]).
+2> lists:sort(dict:to_list(Dict)).
+[{1,a},{2,b}]
+```
+""".
-spec from_list(List) -> Dict when
Dict :: dict(Key, Value),
List :: [{Key, Value}].
@@ -155,13 +171,34 @@ to_list(D) ->
from_list(L) ->
lists:foldl(fun ({K,V}, D) -> store(K, V, D) end, new(), L).
--doc "Returns the number of elements in dictionary `Dict`.".
+-doc """
+Returns the number of elements in dictionary `Dict`.
+
+## Examples
+
+```erlang
+1> Dict = dict:from_list([{2,b},{1,a}]).
+2> dict:size(Dict)
+2
+```
+""".
-spec size(Dict) -> non_neg_integer() when
Dict :: dict().
-size(#dict{size=N}) when is_integer(N), N >= 0 -> N.
+size(#dict{size=N}) when is_integer(N), N >= 0 -> N.
+
+-doc """
+Returns `true` if dictionary `Dict` has no elements; otherwise
+returns `false`.
--doc "Returns `true` if dictionary `Dict` has no elements, otherwise `false`.".
+## Examples
+
+```erlang
+1> Dict = dict:new().
+2> dict:is_empty(Dict).
+true
+```
+""".
-doc(#{since => <<"OTP 17.0">>}).
-spec is_empty(Dict) -> boolean() when
Dict :: dict().
@@ -169,11 +206,18 @@ size(#dict{size=N}) when is_integer(N), N >= 0 -> N.
is_empty(#dict{size=N}) -> N =:= 0.
-doc """
-Returns the value associated with `Key` in dictionary `Dict`. This function
-assumes that `Key` is present in dictionary `Dict`, and an exception is
-generated if `Key` is not in the dictionary.
+Returns the value associated with `Key` in dictionary `Dict`.
+
+This function assumes that `Key` is present in dictionary `Dict`, and
+an exception is generated if `Key` is not in the dictionary.
-See also section [Notes](`m:dict#module-notes`).
+## Examples
+
+```erlang
+1> Dict = dict:from_list([{2,b},{1,a}]).
+2> dict:fetch(1, Dict).
+a
+```
""".
-spec fetch(Key, Dict) -> Value when
Dict :: dict(Key, Value).
@@ -191,11 +235,20 @@ fetch_val(K, [_|Bkt]) -> fetch_val(K, Bkt);
fetch_val(_, []) -> throw(badarg).
-doc """
-Searches for a key in dictionary `Dict`. Returns `{ok, Value}`, where `Value` is
-the value associated with `Key`, or `error` if the key is not present in the
-dictionary.
+Searches for a key in dictionary `Dict`.
+
+Returns `{ok, Value}`, where `Value` is the value associated with
+`Key`, or `error` if the key is not present in the dictionary.
+
+## Examples
-See also section [Notes](`m:dict#module-notes`).
+```erlang
+1> Dict = dict:from_list([{2,b},{1,a}]).
+2> dict:find(1, Dict).
+{ok,a}
+3> dict:find(99, Dict).
+error
+```
""".
-spec find(Key, Dict) -> {'ok', Value} | 'error' when
Dict :: dict(Key, Value).
@@ -209,7 +262,17 @@ find_val(K, [?kv(K,Val)|_]) -> {ok,Val};
find_val(K, [_|Bkt]) -> find_val(K, Bkt);
find_val(_, []) -> error.
--doc "Returns a list of all keys in dictionary `Dict`.".
+-doc """
+Returns a list of all keys in dictionary `Dict`.
+
+## Examples
+
+```erlang
+1> Dict = dict:from_list([{2,b},{1,a}]).
+2> lists:sort(dict:fetch_keys(Dict)).
+[1,2]
+```
+""".
-spec fetch_keys(Dict) -> Keys when
Dict :: dict(Key, Value :: term()),
Keys :: [Key].
@@ -217,14 +280,24 @@ find_val(_, []) -> error.
fetch_keys(D) ->
fold(fun (Key, _Val, Keys) -> [Key|Keys] end, [], D).
--doc "Erases all items with a given key from a dictionary.".
+-doc """
+Erases an item with a given key from a dictionary.
+
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{2,b},{1,a}]).
+2> Dict1 = dict:erase(2, Dict0).
+3> dict:to_list(Dict1).
+[{1,a}]
+4> Dict2 = dict:erase(99, Dict0).
+```
+""".
-spec erase(Key, Dict1) -> Dict2 when
Dict1 :: dict(Key, Value),
Dict2 :: dict(Key, Value).
-%% Erase all elements with key Key.
-
-erase(Key, D0) ->
+erase(Key, D0) ->
Slot = get_slot(D0, Key),
{D1,Dc} = on_bucket(fun (B0) -> erase_key(Key, B0) end,
D0, Slot),
@@ -237,8 +310,22 @@ erase_key(Key, [E|Bkt0]) ->
erase_key(_, []) -> {[],0}.
-doc """
-This function returns value from dictionary and a new dictionary without this
-value. Returns `error` if the key is not present in the dictionary.
+
+This function returns a value from dictionary and a new dictionary
+without this value.
+
+Returns `error` if the key is not present in the dictionary.
+
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{2,b},{1,a}]).
+2> {V, Dict2} = dict:take(1, Dict0).
+3> V
+a
+4> dict:to_list(Dict2).
+[{2,b}]
+```
""".
-doc(#{since => <<"OTP 20.0">>}).
-spec take(Key, Dict) -> {Value, Dict1} | error when
@@ -263,8 +350,22 @@ take_key(Key, [E|Bkt0]) ->
take_key(_, []) -> {[],error}.
-doc """
-Stores a `Key`-`Value` pair in dictionary `Dict2`. If `Key` already exists in
-`Dict1`, the associated value is replaced by `Value`.
+Stores a `Key`-`Value` pair in dictionary `Dict2`.
+
+If `Key` already exists in `Dict1`, the associated value is replaced
+by `Value`.
+
+## Examples
+
+```erlang
+1> Dict0 = dict:new().
+2> Dict1 = dict:store(name, arne, Dict0).
+3> dict:to_list(Dict1).
+[{name,arne}]
+4> Dict2 = dict:store(name, kalle, Dict1).
+5> dict:to_list(Dict2).
+[{name,kalle}]
+```
""".
-spec store(Key, Value, Dict1) -> Dict2 when
Dict1 :: dict(Key, Value),
@@ -287,7 +388,17 @@ store_bkt_val(Key, New, []) -> {[?kv(Key,New)],1}.
-doc """
Appends a new `Value` to the current list of values associated with `Key`.
-See also section [Notes](`m:dict#module-notes`).
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{a,[]}]).
+2> Dict1 = dict:append(a, 1, Dict0).
+3> dict:to_list(Dict1).
+[{a,[1]}]
+4> Dict2 = dict:append(a, 10, Dict1).
+5> dict:to_list(Dict2).
+[{a,[1,10]}]
+```
""".
-spec append(Key, Value, Dict1) -> Dict2 when
Dict1 :: dict(Key, Value),
@@ -309,10 +420,19 @@ append_bkt(Key, Val, []) -> {[?kv(Key,[Val])],1}.
-doc """
Appends a list of values `ValList` to the current list of values associated with
-`Key`. An exception is generated if the initial value associated with `Key` is
+`Key`.
+
+An exception is generated if the initial value associated with `Key` is
not a list of values.
-See also section [Notes](`m:dict#module-notes`).
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{a,[]}]).
+2> Dict1 = dict:append_list(a, [1,2,3], Dict0).
+3> dict:to_list(Dict1).
+[{a,[1,2,3]}]
+```
""".
-spec append_list(Key, ValList, Dict1) -> Dict2 when
Dict1 :: dict(Key, Value),
@@ -333,63 +453,20 @@ app_list_bkt(Key, L, [Other|Bkt0]) ->
{[Other|Bkt1],Ic};
app_list_bkt(Key, L, []) -> {[?kv(Key,L)],1}.
-%% %% first_key(Table) -> {ok,Key} | error.
-%% %% Find the "first" key in a Table.
-
-%% first_key(T) ->
-%% case next_bucket(T, 1) of
-%% [?kv(K,Val)|Bkt] -> {ok,K};
-%% [] -> error %No elements
-%% end.
-
-%% next_bucket(T, Slot) when Slot > T#dict.n -> [];
-%% next_bucket(T, Slot) ->
-%% case get_bucket(T, Slot) of
-%% [] -> next_bucket(T, Slot+1); %Empty bucket
-%% B -> B
-%% end.
-
-%% %% next_key(Table, Key) -> {ok,NextKey} | error.
-
-%% next_key(T, Key) ->
-%% Slot = get_slot(T, Key),
-%% B = get_bucket(T, Slot),
-%% %% Find a bucket with something in it.
-%% Bkt = case bucket_after_key(Key, B) of
-%% no_key -> exit(badarg);
-%% [] -> next_bucket(T, Slot+1);
-%% Rest -> Rest
-%% end,
-%% case Bkt of
-%% [?kv(Next,Val)|_] -> {ok,Next};
-%% [] -> error %We have reached the end!
-%% end.
-
-%% bucket_after_key(Key, [?kv(Key,Val)|Bkt]) -> Bkt;
-%% bucket_after_key(Key, [Other|Bkt]) ->
-%% bucket_after_key(Key, Bkt);
-%% bucket_after_key(Key, []) -> no_key. %Key not found!
-
-%% %% on_key(Fun, Key, Dictionary) -> Dictionary.
-
-%% on_key(F, Key, D0) ->
-%% Slot = get_slot(D0, Key),
-%% {D1,Dc} = on_bucket(fun (B0) -> on_key_bkt(Key, F, B0) end,
-%% D0, Slot),
-%% maybe_contract(D1, Dc).
-
-%% on_key_bkt(Key, F, [?kv(Key,Val)|Bkt]) ->
-%% case F(Val) of
-%% {ok,New} -> {[?kv(Key,New)|Bkt],0};
-%% erase -> {Bkt,1}
-%% end;
-%% on_key_bkt(Key, F, [Other|Bkt0]) ->
-%% {Bkt1,Dc} = on_key_bkt(Key, F, Bkt0),
-%% {[Other|Bkt1],Dc}.
-
-doc """
Updates a value in a dictionary by calling `Fun` on the value to get a new
-value. An exception is generated if `Key` is not present in the dictionary.
+value.
+
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{a,10}]).
+2> Dict1 = dict:update(a, fun(N) -> N + 1 end, Dict0).
+3> dict:to_list(Dict1).
+[{a,11}]
+```
+
+An exception is generated if `Key` is not present in the dictionary.
""".
-spec update(Key, Fun, Dict1) -> Dict2 when
Dict1 :: dict(Key, Value),
@@ -415,12 +492,22 @@ update_bkt(_Key, _F, []) ->
-doc """
Updates a value in a dictionary by calling `Fun` on the value to get a new
-value. If `Key` is not present in the dictionary, `Initial` is stored as the
-first value. For example, [`append/3`](`append/3`) can be defined as:
+value.
+
+If `Key` is not present in the dictionary, `Initial` is stored as the
+first value.
+
+## Examples
```erlang
-append(Key, Val, D) ->
- update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).
+1> Dict0 = dict:new().
+2> Inc = fun(N) -> N + 1 end.
+3> Dict1 = dict:update(a, Inc, 0, Dict0).
+4> dict:to_list(Dict1).
+[{a,0}]
+5> Dict2 = dict:update(a, Inc, 0, Dict1).
+6> dict:to_list(Dict2).
+[{a,1}]
```
""".
-spec update(Key, Fun, Initial, Dict1) -> Dict2 when
@@ -443,15 +530,21 @@ update_bkt(Key, F, I, [Other|Bkt0]) ->
update_bkt(Key, F, I, []) when is_function(F, 1) -> {[?kv(Key,I)],1}.
-doc """
-Adds `Increment` to the value associated with `Key` and stores this value. If
-`Key` is not present in the dictionary, `Increment` is stored as the first
-value.
+Adds `Increment` to the value associated with `Key` and stores this value.
-This can be defined as follows, but is faster:
+If `Key` is not present in the dictionary, `Increment` is stored as
+the first value.
+
+## Examples
```erlang
-update_counter(Key, Incr, D) ->
- update(Key, fun (Old) -> Old + Incr end, Incr, D).
+1> Dict0 = dict:new().
+2> Dict1 = dict:update_counter(a, 10, Dict0).
+3> dict:to_list(Dict1).
+[{a,10}]
+4> Dict2 = dict:update_counter(a, 10, Dict1).
+5> dict:to_list(Dict2).
+[{a,20}]
```
""".
-spec update_counter(Key, Increment, Dict1) -> Dict2 when
@@ -476,9 +569,20 @@ counter_bkt(Key, I, []) -> {[?kv(Key,I)],1}.
-doc """
Calls `Fun` on successive keys and values of dictionary `Dict` together with an
-extra argument `Acc` (short for accumulator). `Fun` must return a new
-accumulator that is passed to the next call. `Acc0` is returned if the
-dictionary is empty. The evaluation order is undefined.
+extra argument `Acc` (short for accumulator).
+
+`Fun` must return a new accumulator that is passed to the next
+call. `Acc0` is returned if the dictionary is empty.
+
+The evaluation order is undefined.
+
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{a,1},{b,2},{c,3}]).
+2> dict:fold(fun(_, N, Acc) -> Acc + N end, 0, Dict0).
+6
+```
""".
-spec fold(Fun, Acc0, Dict) -> Acc1 when
Fun :: fun((Key, Value, AccIn) -> AccOut),
@@ -488,13 +592,22 @@ dictionary is empty. The evaluation order is undefined.
AccIn :: Acc,
AccOut :: Acc.
-%% Fold function Fun over all "bags" in Table and return Accumulator.
-
fold(F, Acc, D) -> fold_dict(F, Acc, D).
-doc """
Calls `Fun` on successive keys and values of dictionary `Dict1` to return a new
-value for each key. The evaluation order is undefined.
+value for each key.
+
+The evaluation order is undefined.
+
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{a,1},{b,2},{c,3}]).
+2> Dict1 = dict:map(fun(_, V) -> 2 * V end, Dict0).
+3> lists:sort(dict:to_list(Dict1)).
+[{a,2},{b,4},{c,6}]
+```
""".
-spec map(Fun, Dict1) -> Dict2 when
Fun :: fun((Key, Value1) -> Value2),
@@ -504,8 +617,17 @@ value for each key. The evaluation order is undefined.
map(F, D) -> map_dict(F, D).
-doc """
-`Dict2` is a dictionary of all keys and values in `Dict1` for which
+Returns a dictionary of all keys and values in `Dict1` for which
`Pred(Key, Value)` is `true`.
+
+## Examples
+
+```erlang
+1> Dict0 = dict:from_list([{a,1},{b,2},{c,3}]).
+2> Dict1 = dict:filter(fun(_, V) -> V rem 2 =:= 1 end, Dict0).
+3> lists:sort(dict:to_list(Dict1)).
+[{a,1},{c,3}]
+```
""".
-spec filter(Pred, Dict1) -> Dict2 when
Pred :: fun((Key , Value) -> boolean()),
@@ -515,17 +637,20 @@ map(F, D) -> map_dict(F, D).
filter(F, D) -> filter_dict(F, D).
-doc """
-Merges two dictionaries, `Dict1` and `Dict2`, to create a new dictionary. All
-the `Key`-`Value` pairs from both dictionaries are included in the new
-dictionary. If a key occurs in both dictionaries, `Fun` is called with the key
-and both values to return a new value. `merge` can be defined as follows, but is
-faster:
+Merges two dictionaries, `Dict1` and `Dict2`, to create a new dictionary.
+
+All the `Key`-`Value` pairs from both dictionaries are included in the
+new dictionary. If a key occurs in both dictionaries, `Fun` is called
+with the key and both values to return a new value.
+
+## Examples
```erlang
-merge(Fun, D1, D2) ->
- fold(fun (K, V1, D) ->
- update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
- end, D2, D1).
+1> Dict0 = dict:from_list([{a,1},{b,2}]).
+2> Dict1 = dict:from_list([{b,7},{c,99}]).
+3> Dict2 = dict:merge(fun(_, V1, V2) -> V1 + V2 end, Dict0, Dict1).
+4> lists:sort(dict:to_list(Dict2)).
+[{a,1},{b,9},{c,99}]
```
""".
-spec merge(Fun, Dict1, Dict2) -> Dict3 when
diff --git a/lib/stdlib/src/gb_trees.erl b/lib/stdlib/src/gb_trees.erl
index 56476646c3..3035bbd33e 100644
--- a/lib/stdlib/src/gb_trees.erl
+++ b/lib/stdlib/src/gb_trees.erl
@@ -28,114 +28,7 @@
%% unbalanced binary trees, and their performance is in general better
%% than AVL trees.
%% ---------------------------------------------------------------------
-%% Operations:
%%
-%% - empty(): returns empty tree.
-%%
-%% - is_empty(T): returns 'true' if T is an empty tree, and 'false'
-%% otherwise.
-%%
-%% - size(T): returns the number of nodes in the tree as an integer.
-%% Returns 0 (zero) if the tree is empty.
-%%
-%% - lookup(X, T): looks up key X in tree T; returns {value, V}, or
-%% `none' if the key is not present.
-%%
-%% - get(X, T): retreives the value stored with key X in tree T. Assumes
-%% that the key is present in the tree.
-%%
-%% - insert(X, V, T): inserts key X with value V into tree T; returns
-%% the new tree. Assumes that the key is *not* present in the tree.
-%%
-%% - update(X, V, T): updates key X to value V in tree T; returns the
-%% new tree. Assumes that the key is present in the tree.
-%%
-%% - enter(X, V, T): inserts key X with value V into tree T if the key
-%% is not present in the tree, otherwise updates key X to value V in
-%% T. Returns the new tree.
-%%
-%% - delete(X, T): removes key X from tree T; returns new tree. Assumes
-%% that the key is present in the tree.
-%%
-%% - delete_any(X, T): removes key X from tree T if the key is present
-%% in the tree, otherwise does nothing; returns new tree.
-%%
-%% - take(X, T): removes element with key X from tree T; returns new tree
-%% without removed element. Assumes that the key is present in the tree.
-%%
-%% - take_any(X, T): removes element with key X from tree T and returns
-%% a new tree if the key is present; otherwise does nothing and returns
-%% 'error'.
-%%
-%% - balance(T): rebalances tree T. Note that this is rarely necessary,
-%% but may be motivated when a large number of entries have been
-%% deleted from the tree without further insertions. Rebalancing could
-%% then be forced in order to minimise lookup times, since deletion
-%% only does not rebalance the tree.
-%%
-%% - is_defined(X, T): returns `true' if key X is present in tree T, and
-%% `false' otherwise.
-%%
-%% - keys(T): returns an ordered list of all keys in tree T.
-%%
-%% - values(T): returns the list of values for all keys in tree T,
-%% sorted by their corresponding keys. Duplicates are not removed.
-%%
-%% - to_list(T): returns an ordered list of {Key, Value} pairs for all
-%% keys in tree T.
-%%
-%% - from_orddict(L): turns an ordered list L of {Key, Value} pairs into
-%% a tree. The list must not contain duplicate keys.
-%%
-%% - smallest(T): returns {X, V}, where X is the smallest key in tree T,
-%% and V is the value associated with X in T. Assumes that the tree T
-%% is nonempty.
-%%
-%% - largest(T): returns {X, V}, where X is the largest key in tree T,
-%% and V is the value associated with X in T. Assumes that the tree T
-%% is nonempty.
-%%
-%% - take_smallest(T): returns {X, V, T1}, where X is the smallest key
-%% in tree T, V is the value associated with X in T, and T1 is the
-%% tree T with key X deleted. Assumes that the tree T is nonempty.
-%%
-%% - take_largest(T): returns {X, V, T1}, where X is the largest key
-%% in tree T, V is the value associated with X in T, and T1 is the
-%% tree T with key X deleted. Assumes that the tree T is nonempty.
-%%
-%% - smaller(K, T): returns {Key, Value} pair, where Key is the
-%% greatest key strictly less than K, or `none' if no such key exists.
-%%
-%% - larger(K, T): returns {Key, Value} pair, where Key is the
-%% least key strictly greater than K, or `none' if no such key exists.
-%%
-%% - iterator(T): returns an iterator that can be used for traversing
-%% the entries of tree T; see `next'. Equivalent to iterator(T, ordered).
-%%
-%% - iterator(T, Order): returns an iterator that can be used for traversing
-%% the entries of tree T in either ordered or reversed direction; see `next'.
-%% The implementation of this is very efficient; traversing the whole tree
-%% using `next' is only slightly slower than getting the list of all elements
-%% using `to_list' and traversing that. The main advantage of the iterator
-%% approach is that it does not require the complete list of all
-%% elements to be built in memory at one time.
-%%
-%% - iterator_from(K, T): returns an iterator that can be used for
-%% traversing the entries of tree T with key greater than or
-%% equal to K; see `next'. Equivalent to iterator_from(K, T, ordered).
-%%
-%% - iterator_from(K, T, Order): returns an iterator that can be used for
-%% traversing the entries of tree T in either ordered or reversed direction,
-%% starting from the key equal to or closest to K; see `next'.
-%%
-%% - next(S): returns {X, V, S1} where X is the next key referred to
-%% by the iterator S, and S1 is the new iterator to be used for
-%% traversing the remaining entries, or the atom `none' if no entries
-%% remain.
-%%
-%% - map(F, T): maps the function F(K, V) -> V' to all key-value pairs
-%% of the tree T and returns a new tree T' with the same set of keys
-%% as T and the new set of values V'.
-module(gb_trees).
-moduledoc """
@@ -162,7 +55,7 @@ should also be OK.
## See Also
-`m:dict`, `m:gb_sets`
+`m:dict`, `m:gb_sets`, `m:maps`
""".
-export([empty/0, is_empty/1, size/1, lookup/2, get/2, insert/3,
@@ -219,13 +112,33 @@ should also be OK.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
--doc "Returns a new empty tree.".
+-doc """
+Returns a new empty tree.
+
+## Examples
+
+```erlang
+1> gb_trees:to_list(gb_trees:empty()).
+[]
+```
+""".
-spec empty() -> tree(none(), none()).
empty() ->
{0, nil}.
--doc "Returns `true` if `Tree` is an empty tree, othwewise `false`.".
+-doc """
+Returns `true` if `Tree` is an empty tree; otherwise, returns `false`.
+
+## Examples
+
+```erlang
+1> gb_trees:is_empty(gb_trees:empty()).
+true
+2> gb_trees:is_empty(gb_trees:from_orddict([{a,99}])).
+false
+```
+""".
-spec is_empty(Tree) -> boolean() when
Tree :: tree().
@@ -234,7 +147,19 @@ is_empty({0, nil}) ->
is_empty(_) ->
false.
--doc "Returns the number of nodes in `Tree`.".
+-doc """
+Returns the number of nodes in `Tree`.
+
+## Examples
+
+```erlang
+1> gb_trees:size(gb_trees:empty()).
+0
+2> gb_trees:size(gb_trees:from_orddict([{a,1},{b,2}])).
+2
+```
+
+""".
-spec size(Tree) -> non_neg_integer() when
Tree :: tree().
@@ -244,8 +169,17 @@ size({Size, _}) when is_integer(Size), Size >= 0 ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Looks up `Key` in `Tree`. Returns `{value, Value}`, or `none` if `Key` is not
-present.
+Looks up `Key` in `Tree` and returns `{value, Value}` if found, or `none` if not present.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:lookup(a, Tree).
+{value,1}
+3> gb_trees:lookup(z, Tree).
+none
+```
""".
-spec lookup(Key, Tree) -> 'none' | {'value', Value} when
Tree :: tree(Key, Value).
@@ -273,7 +207,20 @@ lookup_1(_, nil) ->
%% This is a specialized version of `lookup'.
--doc "Returns `true` if `Key` is present in `Tree`, otherwise `false`.".
+-doc """
+Returns `true` if `Key` is present in `Tree`; otherwise, returns
+`false`.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:is_defined(a, Tree).
+true
+3> gb_trees:is_defined(x, Tree).
+false
+```
+""".
-spec is_defined(Key, Tree) -> boolean() when
Tree :: tree(Key, Value :: term()).
@@ -294,8 +241,16 @@ is_defined_1(_, nil) ->
%% This is a specialized version of `lookup'.
-doc """
-Retrieves the value stored with `Key` in `Tree`. Assumes that the key is present
-in the tree, crashes otherwise.
+Retrieves the value stored with `Key` in `Tree`; raises an exception
+if `Key` is not present.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2}]).
+2> gb_trees:get(b, Tree).
+2
+```
""".
-spec get(Key, Tree) -> Value when
Tree :: tree(Key, Value).
@@ -313,8 +268,18 @@ get_1(_, {_, Value, _, _}) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Updates `Key` to value `Value` in `Tree1` and returns the new tree. Assumes that
-the key is present in the tree.
+Updates `Key` to value `Value` in `Tree1` and returns the new tree.
+
+Assumes that the key is present in the tree.
+
+## Examples
+
+```erlang
+1> Tree1 = gb_trees:from_orddict([{a,1},{b,2}]).
+2> Tree2 = gb_trees:update(a, 99, Tree1).
+3> gb_trees:to_list(Tree2).
+[{a,99},{b,2}]
+```
""".
-spec update(Key, Value, Tree1) -> Tree2 when
Tree1 :: tree(Key, Value),
@@ -336,8 +301,17 @@ update_1(Key, Value, {_, _, Smaller, Bigger}) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Inserts `Key` with value `Value` into `Tree1` and returns the new tree. Assumes
-that the key is not present in the tree, crashes otherwise.
+Inserts `Key` with value `Value` into `Tree1`, returning the new
+tree; raises an exception if `Key` is already present.
+
+## Examples
+
+```erlang
+1> Tree1 = gb_trees:from_orddict([{a,1},{b,2}]).
+2> Tree2 = gb_trees:insert(c, 10, Tree1).
+3> gb_trees:to_list(Tree2).
+[{a,1},{b,2},{c,10}]
+```
""".
-spec insert(Key, Value, Tree1) -> Tree2 when
Tree1 :: tree(Key, Value),
@@ -391,8 +365,19 @@ insert_1(Key, _, _, _) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Inserts `Key` with value `Value` into `Tree1` if the key is not present in the
-tree, otherwise updates `Key` to value `Value` in `Tree1`. Returns the new tree.
+Inserts `Key` with value `Value` into `Tree1` if not present, or
+updates the value for `Key` to `Value` if present; returns the new
+tree.
+
+## Examples
+
+```erlang
+1> Tree1 = gb_trees:from_orddict([{a,1},{b,2}]).
+2> Tree2 = gb_trees:enter(c, 10, Tree1).
+3> Tree3 = gb_trees:enter(a, 100, Tree2).
+4> gb_trees:to_list(Tree3).
+[{a,100},{b,2},{c,10}]
+```
""".
-spec enter(Key, Value, Tree1) -> Tree2 when
Tree1 :: tree(Key, Value),
@@ -422,10 +407,21 @@ count(nil) ->
-doc """
Rebalances `Tree1`.
-Notice that this is rarely necessary, but can be motivated
+Note that this is rarely necessary, but can be motivated
when many nodes have been deleted from the tree without further insertions.
Rebalancing can then be forced to minimize lookup times, as deletion does not
rebalance the tree.
+
+## Examples
+
+```erlang
+1> Tree1 = gb_trees:from_orddict([{I,2*I} || I <- lists:seq(1, 100)]).
+2> Delete = fun gb_trees:delete/2.
+3> Tree2 = lists:foldl(Delete, Tree1, lists:seq(1, 50)).
+4> gb_sets:size(Tree2).
+50
+5> Tree3 = gb_trees:balance(Tree2).
+```
""".
-spec balance(Tree1) -> Tree2 when
Tree1 :: tree(Key, Value),
@@ -455,8 +451,17 @@ balance_list_1(L, 0) ->
{nil, L}.
-doc """
-Turns an ordered list `List` of key-value tuples into a tree. The list must not
-contain duplicate keys.
+Turns an ordered list `List` of key-value tuples into a tree.
+
+The list must not contain duplicate keys.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2}]).
+2> gb_trees:to_list(Tree).
+[{a,1},{b,2}]
+```
""".
-spec from_orddict(List) -> Tree when
List :: [{Key, Value}],
@@ -469,8 +474,20 @@ from_orddict(L) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Removes the node with key `Key` from `Tree1` if the key is present in the tree,
-otherwise does nothing. Returns the new tree.
+Removes the node with key `Key` from `Tree1` if present and returns the
+resulting tree; otherwise, returns `Tree1` unchanged.
+
+## Examples
+
+```erlang
+1> Tree1 = gb_trees:from_orddict([{a,1},{b,2}]).
+2> Tree2 = gb_trees:delete_any(a, Tree1).
+3> gb_trees:to_list(Tree2).
+[{b,2}]
+4> Tree3 = gb_trees:delete_any(z, Tree2).
+5> Tree2 == Tree3.
+true
+```
""".
-spec delete_any(Key, Tree1) -> Tree2 when
Tree1 :: tree(Key, Value),
@@ -484,11 +501,18 @@ delete_any(Key, T) ->
T
end.
-%%% delete. Assumes that key is present.
-
-doc """
-Removes the node with key `Key` from `Tree1` and returns the new tree. Assumes
-that the key is present in the tree, crashes otherwise.
+Removes the node with key `Key` from `Tree1`, returning the new tree;
+raises an exception if `Key` is not present.
+
+## Examples
+
+```erlang
+1> Tree1 = gb_trees:from_orddict([{a,1},{b,2}]).
+2> Tree2 = gb_trees:delete(a, Tree1).
+3> gb_trees:to_list(Tree2).
+[{b,2}]
+```
""".
-spec delete(Key, Tree1) -> Tree2 when
Tree1 :: tree(Key, Value),
@@ -519,9 +543,21 @@ merge(Smaller, Larger) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Returns a value `Value` from node with key `Key` and new `Tree2` without the
-node with this value. Returns `error` if the node with the key is not present in
-the tree.
+Removes the node with key Key from Tree1 if present; otherwise,
+returns the tree unchanged.
+
+## Examples
+
+```erlang
+1> Tree0 = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> {Value,Tree1} = gb_trees:take_any(b, Tree0).
+3> Value.
+2
+4> gb_trees:to_list(Tree1).
+[{a,1},{c,3}]
+5> gb_trees:take_any(x, Tree0).
+error
+```
""".
-doc(#{since => <<"OTP 20.0">>}).
-spec take_any(Key, Tree1) -> {Value, Tree2} | 'error' when
@@ -539,9 +575,21 @@ take_any(Key, Tree) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Returns a value `Value` from node with key `Key` and new `Tree2` without the
-node with this value. Assumes that the node with key is present in the tree,
-crashes otherwise.
+Returns a value `Value` from node with key `Key` and new `Tree2`
+with that node removed.
+
+Assumes that the node with key is present in the tree.
+
+## Examples
+
+```erlang
+1> Tree0 = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> {Value,Tree1} = gb_trees:take(b, Tree0).
+3> Value.
+2
+4> gb_trees:to_list(Tree1).
+[{a,1},{c,3}]
+```
""".
-doc(#{since => <<"OTP 20.0">>}).
-spec take(Key, Tree1) -> {Value, Tree2} when
@@ -566,9 +614,25 @@ take_1(_, {_Key, Value, Smaller, Larger}) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Returns `{Key, Value, Tree2}`, where `Key` is the smallest key in `Tree1`,
-`Value` is the value associated with this key, and `Tree2` is this tree with the
-corresponding node deleted. Assumes that the tree is not empty.
+
+Returns `{Key, Value, Tree2}`, where Key is the smallest key in `Tree1`,
+`Value` is the value associated with that key, and `Tree2` is the tree
+with the corresponding node removed.
+
+Assumes that the tree is not empty.
+
+## Examples
+
+```erlang
+1> Tree0 = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> {Key,Value,Tree1} = gb_trees:take_smallest(Tree0).
+3> Key.
+a
+4> Value.
+1
+5> gb_trees:to_list(Tree1).
+[{b,2},{c,3}]
+```
""".
-spec take_smallest(Tree1) -> {Key, Value, Tree2} when
Tree1 :: tree(Key, Value),
@@ -586,7 +650,17 @@ take_smallest1({Key, Value, Smaller, Larger}) ->
-doc """
Returns `{Key, Value}`, where `Key` is the smallest key in `Tree`, and `Value`
-is the value associated with this key. Assumes that the tree is not empty.
+is the value associated with this key.
+
+Assumes that the tree is not empty.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:smallest(Tree).
+{a,1}
+```
""".
-spec smallest(Tree) -> {Key, Value} when
Tree :: tree(Key, Value).
@@ -600,9 +674,24 @@ smallest_1({_Key, _Value, Smaller, _Larger}) ->
smallest_1(Smaller).
-doc """
-Returns `{Key, Value, Tree2}`, where `Key` is the largest key in `Tree1`,
-`Value` is the value associated with this key, and `Tree2` is this tree with the
-corresponding node deleted. Assumes that the tree is not empty.
+Returns `{Key, Value, Tree2}`, where `Key` is the largest key in
+`Tree1`, `Value` is the value associated with this key, and `Tree2` is
+this tree with the corresponding node deleted.
+
+Assumes that the tree is not empty.
+
+## Examples
+
+```erlang
+1> Tree0 = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> {Key,Value,Tree1} = gb_trees:take_largest(Tree0).
+3> Key.
+c
+4> Value.
+3
+5> gb_trees:to_list(Tree1).
+[{a,1},{b,2}]
+```
""".
-spec take_largest(Tree1) -> {Key, Value, Tree2} when
Tree1 :: tree(Key, Value),
@@ -620,7 +709,17 @@ take_largest1({Key, Value, Smaller, Larger}) ->
-doc """
Returns `{Key, Value}`, where `Key` is the largest key in `Tree`, and `Value` is
-the value associated with this key. Assumes that the tree is not empty.
+the value associated with this key.
+
+Assumes that the tree is not empty.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:largest(Tree).
+{c,3}
+```
""".
-spec largest(Tree) -> {Key, Value} when
Tree :: tree(Key, Value).
@@ -637,9 +736,21 @@ largest_1({_Key, _Value, _Smaller, Larger}) ->
-doc """
Returns `{Key2, Value}`, where `Key2` is the greatest key strictly less than
-`Key1`, `Value` is the value associated with this key.
+`Key1`, and `Value` is the value associated with this key.
Returns `none` if no such pair exists.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:smaller(c, Tree).
+{b,2}
+3> gb_trees:smaller(bb, Tree).
+{b,2}
+4> gb_trees:smaller(a, Tree).
+none
+```
""".
-doc(#{since => <<"OTP 27.0">>}).
-spec smaller(Key1, Tree) -> none | {Key2, Value} when
@@ -666,6 +777,18 @@ Returns `{Key2, Value}`, where `Key2` is the least key strictly greater than
`Key1`, `Value` is the value associated with this key.
Returns `none` if no such pair exists.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:larger(c, Tree).
+none
+3> gb_trees:larger(bb, Tree).
+{c,3}
+4> gb_trees:larger(a, Tree).
+{b,2}
+```
""".
-doc(#{since => <<"OTP 27.0">>}).
-spec larger(Key1, Tree) -> none | {Key2, Value} when
@@ -689,10 +812,22 @@ larger_1(Key, {_Key, _Value, _Smaller, Larger}) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
--doc "Converts a tree into an ordered list of key-value tuples.".
+-doc """
+Converts a tree into an ordered list of key-value tuples.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:to_list(Tree).
+[{a,1},{b,2},{c,3}]
+3> gb_trees:to_list(gb_trees:empty()).
+[]
+```
+""".
-spec to_list(Tree) -> [{Key, Value}] when
Tree :: tree(Key, Value).
-
+
to_list({_, T}) ->
to_list(T, []).
@@ -704,7 +839,19 @@ to_list(nil, L) -> L.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
--doc "Returns the keys in `Tree` as an ordered list.".
+-doc """
+Returns the keys in `Tree` as an ordered list.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> gb_trees:keys(Tree).
+[a,b,c]
+3> gb_trees:keys(gb_trees:empty()).
+[]
+```
+""".
-spec keys(Tree) -> [Key] when
Tree :: tree(Key, Value :: term()).
@@ -718,8 +865,18 @@ keys(nil, L) -> L.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Returns the values in `Tree` as an ordered list, sorted by their corresponding
-keys. Duplicates are not removed.
+Returns the values in `Tree` as an ordered list, sorted by their
+corresponding keys.
+
+Duplicates are not removed.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3},{d,1}]).
+2> gb_trees:values(Tree).
+[1,2,3,1]
+```
""".
-spec values(Tree) -> [Value] when
Tree :: tree(Key :: term(), Value).
@@ -734,10 +891,18 @@ values(nil, L) -> L.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Returns an iterator that can be used for traversing the entries of `Tree`; see
-`next/1`.
+Returns an iterator that can be used for traversing the entries of
+`Tree`; see `next/1`.
Equivalent to [`iterator(Tree, ordered)`](`iterator/2`).
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> Iter0 = gb_trees:iterator(Tree).
+3> {a,1,Iter1} = gb_trees:next(Iter0).
+```
""".
-spec iterator(Tree) -> Iter when
Tree :: tree(Key, Value),
@@ -755,6 +920,16 @@ The implementation of this is very efficient; traversing the whole tree using
elements using `to_list/1` and traversing that. The main advantage of the
iterator approach is that it does not require the complete list of all elements
to be built in memory at one time.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> Iter0 = gb_trees:iterator(Tree, ordered).
+3> {a,1,Iter1} = gb_trees:next(Iter0).
+4> RevIter0 = gb_trees:iterator(Tree, reversed).
+5> {c,3,RevIter1} = gb_trees:next(RevIter0).
+```
""".
-doc(#{since => <<"OTP 27.0">>}).
-spec iterator(Tree, Order) -> Iter when
@@ -787,11 +962,23 @@ iterator_r(nil, As) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Returns an iterator that can be used for traversing the entries of `Tree`; see
-`next/1`. The difference as compared to the iterator returned by `iterator/1` is
+
+Returns an iterator that can be used for traversing the entries of
+`Tree` starting from `Key`; see `next/1`.
+
+The difference as compared to the iterator returned by `iterator/1` is
that the iterator starts with the first key greater than or equal to `Key`.
Equivalent to [`iterator_from(Key, Tree, ordered)`](`iterator_from/3`).
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3},{d,4}]).
+2> Iter0 = gb_trees:iterator_from(aa, Tree).
+3> {b,2,Iter1} = gb_trees:next(Iter0).
+4> {c,3,Iter2} = gb_trees:next(Iter1).
+```
""".
-doc(#{since => <<"OTP 18.0">>}).
-spec iterator_from(Key, Tree) -> Iter when
@@ -803,9 +990,21 @@ iterator_from(Key, Tree) ->
-doc """
Returns an iterator that can be used for traversing the entries of `Tree` in
-either `ordered` or `reversed` direction; see `next/1`. The difference as
-compared to the iterator returned by `iterator/2` is that the iterator starts
-with the first key next to or equal to `Key`.
+either `ordered` or `reversed` direction starting from `Key`; see `next/1`.
+
+The difference as compared to the iterator returned by `iterator/2` is
+that the iterator starts with the first key next to or equal to `Key`.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3},{d,4}]).
+2> Iter0 = gb_trees:iterator_from(aa, Tree, ordered).
+3> {b,2,Iter1} = gb_trees:next(Iter0).
+4> RevIter0 = gb_trees:iterator_from(c, Tree, reversed).
+5> {c,3,RevIter1} = gb_trees:next(RevIter0).
+6> {b,2,RevIter2} = gb_trees:next(RevIter1).
+```
""".
-doc(#{since => <<"OTP 27.0">>}).
-spec iterator_from(Key, Tree, Order) -> Iter when
@@ -842,6 +1041,17 @@ iterator_from_r(_, nil, As) ->
Returns `{Key, Value, Iter2}`, where `Key` is the next key referred to by
iterator `Iter1`, and `Iter2` is the new iterator to be used for traversing the
remaining nodes, or the atom `none` if no nodes remain.
+
+## Examples
+
+```erlang
+1> Tree = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> Iter0 = gb_trees:iterator(Tree).
+3> {a,1,Iter1} = gb_trees:next(Iter0).
+4> {b,2,Iter2} = gb_trees:next(Iter1).
+5> {c,3,Iter3} = gb_trees:next(Iter2).
+6> none = gb_trees:next(Iter3).
+```
""".
-spec next(Iter1) -> 'none' | {Key, Value, Iter2} when
Iter1 :: iter(Key, Value),
@@ -857,9 +1067,19 @@ next({_, []}) ->
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-doc """
-Maps function F(K, V1) -> V2 to all key-value pairs of tree `Tree1`. Returns a
-new tree `Tree2` with the same set of keys as `Tree1` and the new set of values
-`V2`.
+
+Maps function F(K, V1) -> V2 to all key-value pairs of tree `Tree1`,
+returning a new tree `Tree2` with the same set of keys as
+`Tree1` and the new set of values `V2`.
+
+## Examples
+
+```erlang
+1> Tree0 = gb_trees:from_orddict([{a,1},{b,2},{c,3}]).
+2> Tree1 = gb_trees:map(fun(_, V) -> 2 * V end, Tree0).
+3> gb_trees:to_list(Tree1).
+[{a,2},{b,4},{c,6}]
+```
""".
-spec map(Function, Tree1) -> Tree2 when
Function :: fun((K :: Key, V1 :: Value1) -> V2 :: Value2),
diff --git a/lib/stdlib/src/orddict.erl b/lib/stdlib/src/orddict.erl
index 4ad6335f5b..31974d26e4 100644
--- a/lib/stdlib/src/orddict.erl
+++ b/lib/stdlib/src/orddict.erl
@@ -34,33 +34,9 @@ defined representation. One difference is that while `dict` considers two keys
as different if they do not match (`=:=`), this module considers two keys as
different if and only if they do not compare equal (`==`).
-## Notes
-
-[](){: #notes }
-
-Functions [`append/3`](`append/3`) and [`append_list/3`](`append_list/3`) are
-included so that keyed values can be stored in a list _accumulator_, for
-example:
-
-```erlang
-> D0 = orddict:new(),
- D1 = orddict:store(files, [], D0),
- D2 = orddict:append(files, f1, D1),
- D3 = orddict:append(files, f2, D2),
- D4 = orddict:append(files, f3, D3),
- orddict:fetch(files, D4).
-[f1,f2,f3]
-```
-
-This saves the trouble of first fetching a keyed value, appending a new value to
-the list of stored values, and storing the result.
-
-Function [`fetch/2`](`fetch/2`) is to be used if the key is known to be in the
-dictionary, otherwise function [`find/2`](`find/2`).
-
## See Also
-`m:dict`, `m:gb_trees`
+`m:dict`, `m:gb_trees`, `m:maps`
""".
%% Standard interface.
@@ -80,12 +56,35 @@ dictionary, otherwise function [`find/2`](`find/2`).
%%---------------------------------------------------------------------------
--doc "Creates a new dictionary.".
+-doc """
+Creates a new dictionary.
+
+## Examples
+
+```erlang
+1> orddict:new().
+[]
+```
+""".
-spec new() -> orddict(none(), none()).
new() -> [].
--doc "Tests if `Key` is contained in dictionary `Orddict`.".
+-doc """
+Returns `true` if `Key` is contained in dictionary `Orddict`;
+otherwise, returns `false`.
+
+## Examples
+
+```erlang
+1> OrdDict = orddict:from_list([{1,a},{2,b},{3,c}]).
+[{1,a},{2,b},{3,c}]
+2> orddict:is_key(2, OrdDict).
+true
+3> orddict:is_key(aa, OrdDict).
+false
+```
+""".
-spec is_key(Key, Orddict) -> boolean() when
Orddict :: orddict(Key, Value :: term()).
@@ -94,14 +93,34 @@ is_key(Key, [{K,_}|Dict]) when Key > K -> is_key(Key, Dict);
is_key(_Key, [{_K,_Val}|_]) -> true; %Key == K
is_key(_, []) -> false.
--doc "Converts a dictionary to a list representation.".
+-doc """
+Converts a dictionary to a list representation.
+
+## Examples
+
+```erlang
+1> OrdDict = orddict:from_list([{2,b},{1,a}]).
+[{1,a},{2,b}]
+2> orddict:to_list(OrdDict).
+[{1,a},{2,b}]
+```
+""".
-spec to_list(Orddict) -> List when
Orddict :: orddict(Key, Value),
List :: [{Key, Value}].
to_list(Dict) -> Dict.
--doc "Converts the `Key`-`Value` list `List` to a dictionary.".
+-doc """
+Converts the `Key`-`Value` list `List` to a dictionary.
+
+## Examples
+
+```erlang
+1> OrdDict = orddict:from_list([{2,b},{1,a},{3,c}]).
+[{1,a},{2,b},{3,c}]
+```
+""".
-spec from_list(List) -> Orddict when
List :: [{Key, Value}],
Orddict :: orddict(Key, Value).
@@ -111,13 +130,35 @@ from_list([{_,_}]=Pair) -> Pair;
from_list(Pairs) ->
lists:ukeysort(1, reverse_pairs(Pairs, [])).
--doc "Returns the number of elements in an `Orddict`.".
+-doc """
+Returns the number of elements in an `Orddict`.
+
+## Examples
+
+```erlang
+1> orddict:size(orddict:new()).
+0
+2> orddict:size(orddict:from_list([{a,1},{b,2},{c,3}])).
+3
+```
+""".
-spec size(Orddict) -> non_neg_integer() when
Orddict :: orddict().
size(D) -> length(D).
--doc "Returns `true` if `Orddict` has no elements, otherwise `false`.".
+-doc """
+Returns `true` if `Orddict` has no elements; otherwise, returns `false`.
+
+## Examples
+
+```erlang
+1> orddict:is_empty(orddict:new()).
+true
+2> orddict:is_empty(orddict:from_list([{a,1}])).
+false
+```
+""".
-doc(#{since => <<"OTP 17.0">>}).
-spec is_empty(Orddict) -> boolean() when
Orddict :: orddict().
@@ -126,13 +167,12 @@ is_empty([]) -> true;
is_empty([_|_]) -> false.
-doc """
-Returns the value associated with `Key` in dictionary `Orddict`. This function
-assumes that the `Key` is present in the dictionary. An exception is generated
-if `Key` is not in the dictionary.
+Returns the value associated with `Key` in dictionary `Orddict`.
-See also section [Notes](`m:orddict#module-notes`).
+This function assumes that the `Key` is present in the dictionary. An
+exception is generated if `Key` is not in the dictionary.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -150,13 +190,12 @@ fetch(Key, [{K,_}|D]) when Key > K -> fetch(Key, D);
fetch(Key, [{K,Value}|_]) when Key == K -> Value.
-doc """
-Searches for a key in a dictionary. Returns `{ok, Value}`, where `Value` is the
-value associated with `Key`, or `error` if the key is not present in the
-dictionary.
+Searches for a key in a dictionary.
-See also section [Notes](`m:orddict#module-notes`).
+Returns `{ok, Value}`, where `Value` is the value associated with
+`Key`, or `error` if the key is not present in the dictionary.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -178,7 +217,7 @@ find(_, []) -> error.
-doc """
Returns a list of all keys in a dictionary.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -196,15 +235,17 @@ fetch_keys([{Key,_}|Dict]) ->
fetch_keys([]) -> [].
-doc """
-Erases all items with a specified key from a dictionary.
+Removes the item with key `Key` from dictionary `OrdDict1`.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:erase(a, OrdDict1).
[{b,2}]
+3> orddict:erase(z, OrdDict1).
+[{a,1},{b,2}]
```
""".
-spec erase(Key, Orddict1) -> Orddict2 when
@@ -219,9 +260,11 @@ erase(_, []) -> [].
-doc """
This function returns value from dictionary and new dictionary without this
-value. Returns `error` if the key is not present in the dictionary.
+value.
-_Example:_
+Returns `error` if the key is not present in the dictionary.
+
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -251,10 +294,12 @@ take_1(_Key, [{_K,Value}|D], Acc) ->
take_1(_, [], _) -> error.
-doc """
-Stores a `Key`-`Value` pair in a dictionary. If the `Key` already exists in
-`Orddict1`, the associated value is replaced by `Value`.
+Stores a `Key`-`Value` pair in a dictionary.
+
+If the `Key` already exists in `Orddict1`, the associated value is
+replaced by `Value`.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -278,13 +323,12 @@ store(Key, New, [{_K,_Old}|Dict]) -> %Key == K
store(Key, New, []) -> [{Key,New}].
-doc """
-Appends a new `Value` to the current list of values associated with `Key`. An
-exception is generated if the initial value associated with `Key` is not a list
-of values.
+Appends a new `Value` to the current list of values associated with `Key`.
-See also section [Notes](`m:orddict#module-notes`).
+An exception is generated if the initial value associated with `Key`
+is not a list of values.
-_Example 1:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{x, []}]).
@@ -297,8 +341,6 @@ _Example 1:_
[{x,[1,2]},{y,[3]}]
```
-_Example 2:_
-
```erlang
1> OrdDict1 = orddict:from_list([{a, no_list}]).
[{a,no_list}]
@@ -306,6 +348,7 @@ _Example 2:_
** exception error: bad argument
in operator ++/2
called as no_list ++ [1]
+ in call from orddict:append/3
```
""".
-spec append(Key, Value, Orddict1) -> Orddict2 when
@@ -322,12 +365,12 @@ append(Key, New, []) -> [{Key,[New]}].
-doc """
Appends a list of values `ValList` to the current list of values associated with
-`Key`. An exception is generated if the initial value associated with `Key` is
-not a list of values.
+`Key`.
-See also section [Notes](`m:orddict#module-notes`).
+An exception is generated if the initial value associated with `Key`
+is not a list of values.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{x, []}]).
@@ -354,9 +397,11 @@ append_list(Key, NewList, []) ->
-doc """
Updates a value in a dictionary by calling `Fun` on the value to get a new
-value. An exception is generated if `Key` is not present in the dictionary.
+value.
-_Example:_
+An exception is generated if `Key` is not present in the dictionary.
+
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -377,7 +422,9 @@ update(Key, Fun, [{K,Val}|Dict]) when Key == K ->
-doc """
Updates a value in a dictionary by calling `Fun` on the value to get a new
-value. If `Key` is not present in the dictionary, `Initial` is stored as the
+value.
+
+If `Key` is not present in the dictionary, `Initial` is stored as the
first value.
For example, [`append/3`](`append/3`) can be defined as follows:
@@ -387,22 +434,15 @@ append(Key, Val, D) ->
update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).
```
-_Example 1:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
-2> orddict:update(c, fun (V) -> V + 100 end, 99, OrdDict1).
+2> OrdDict2 = orddict:update(c, fun (V) -> V + 100 end, 99, OrdDict1).
[{a,1},{b,2},{c,99}]
-```
-
-_Example 2:_
-
-```erlang
-1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
-[{a,1},{b,2}]
-2> orddict:update(a, fun (V) -> V + 100 end, 99, OrdDict1).
-[{a,101},{b,2}]
+3> orddict:update(a, fun (V) -> V + 100 end, 99, OrdDict2).
+[{a,101},{b,2},{c,99}]
```
""".
-spec update(Key, Fun, Initial, Orddict1) -> Orddict2 when
@@ -420,15 +460,22 @@ update(Key, Fun, _Init, [{_K,Val}|Dict]) -> %Key == K
update(Key, _, Init, []) -> [{Key,Init}].
-doc """
-Adds `Increment` to the value associated with `Key` and store this value. If
-`Key` is not present in the dictionary, `Increment` is stored as the first
-value.
+Adds `Increment` to the value associated with `Key` and store this value.
-This can be defined as follows, but is faster:
+If `Key` is not present in the dictionary, `Increment` is stored as
+the first value.
+
+## Examples
-```erlang
-update_counter(Key, Incr, D) ->
- update(Key, fun (Old) -> Old + Incr end, Incr, D).
+```
+1> OrdDict1 = orddict:from_list([{a,0},{b,0}]).
+[{a,0},{b,0}]
+2> OrdDict2 = orddict:update_counter(a, 1, OrdDict1).
+[{a,1},{b,0}]
+3> OrdDict3 = orddict:update_counter(b, 2, OrdDict2).
+[{a,1},{b,2}]
+4> orddict:update_counter(z, 7, OrdDict3).
+[{a,1},{b,2},{z,7}]
```
""".
-spec update_counter(Key, Increment, Orddict1) -> Orddict2 when
@@ -446,10 +493,12 @@ update_counter(Key, Incr, []) -> [{Key,Incr}].
-doc """
Calls `Fun` on successive keys and values of `Orddict` together with an extra
-argument `Acc` (short for accumulator). `Fun` must return a new accumulator that
-is passed to the next call. `Acc0` is returned if the list is empty.
+argument `Acc` (short for accumulator).
-_Example:_
+`Fun` must return a new accumulator that is passed to the next
+call. `Acc0` is returned if the list is empty.
+
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -474,7 +523,7 @@ fold(F, Acc, []) when is_function(F, 3) -> Acc.
Calls `Fun` on successive keys and values of `Orddict1` to return a new value
for each key.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -496,7 +545,7 @@ map(F, []) when is_function(F, 2) -> [].
`Orddict2` is a dictionary of all keys and values in `Orddict1` for which
`Pred(Key, Value)` is `true`.
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
@@ -519,6 +568,7 @@ filter(F, []) when is_function(F, 2) -> [].
-doc """
Merges two dictionaries, `Orddict1` and `Orddict2`, to create a new dictionary.
+
All the `Key`-`Value` pairs from both dictionaries are included in the new
dictionary.
@@ -534,7 +584,7 @@ merge(Fun, D1, D2) ->
end, D2, D1).
```
-_Example:_
+## Examples
```erlang
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
diff --git a/lib/stdlib/test/dict_SUITE.erl b/lib/stdlib/test/dict_SUITE.erl
index 23b9c573f6..a8e6ddfb96 100644
--- a/lib/stdlib/test/dict_SUITE.erl
+++ b/lib/stdlib/test/dict_SUITE.erl
@@ -28,7 +28,8 @@
-export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1,
init_per_group/2,end_per_group/2,
init_per_testcase/2,end_per_testcase/2,
- create/1,store/1,iterate/1,remove/1]).
+ create/1,store/1,iterate/1,remove/1,
+ doctests_dict/1,doctests_gb_trees/1,doctests_orddict/1]).
-include_lib("common_test/include/ct.hrl").
@@ -38,11 +39,14 @@ suite() ->
[{ct_hooks,[ts_install_cth]},
{timetrap,{minutes,5}}].
-all() ->
- [create, store, remove, iterate].
+all() ->
+ [{group,p}].
-groups() ->
- [].
+groups() ->
+ [{p,[parallel],
+ [create, store, remove, iterate,
+ doctests_dict, doctests_gb_trees, doctests_orddict
+ ]}].
init_per_suite(Config) ->
Config.
@@ -115,6 +119,15 @@ remove_2([], D, M) ->
true = M(is_empty, D),
D.
+doctests_dict(_Config) ->
+ shell_docs:test(dict, []).
+
+doctests_gb_trees(_Config) ->
+ shell_docs:test(gb_trees, []).
+
+doctests_orddict(_Config) ->
+ shell_docs:test(orddict, []).
+
%%%
%%% Test specifics for gb_trees.
%%%
--
2.51.0
