檢視原始碼 orddict (stdlib v6.2)
以有序列表呈現的鍵值字典。
此模組提供一個 Key-Value 字典。orddict 是字典的一種表示形式，其中使用配對列表來儲存鍵和值。該列表會依據 Erlang 項順序，按照鍵進行排序。
此模組提供與 dict 模組相同的介面，但具有定義的表示形式。一個不同之處在於，dict 在兩個鍵不匹配 (=:=) 時會將其視為不同，而此模組僅在兩個鍵不相等 (==) 時才會將其視為不同。
注意事項
包含 append/3 和 append_list/3 函數，以便將鍵控值儲存在列表累加器中，例如：
> 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]這樣就省去了先獲取鍵控值、將新值附加到已儲存值列表，然後再儲存結果的麻煩。
如果已知鍵存在於字典中，則使用 fetch/2 函數，否則使用 find/2 函數。
另請參閱
摘要
函數
將新的 Value 附加到與 Key 關聯的目前值列表中。如果與 Key 關聯的初始值不是值列表，則會產生例外。
將值列表 ValList 附加到與 Key 關聯的目前值列表中。如果與 Key 關聯的初始值不是值列表，則會產生例外。
從字典中刪除所有具有指定鍵的項目。
傳回字典 Orddict 中與 Key 關聯的值。此函數假設 Key 存在於字典中。如果 Key 不在字典中，則會產生例外。
傳回字典中所有鍵的列表。
Orddict2 是一個字典，其中包含 Orddict1 中所有 Pred(Key, Value) 為 true 的鍵和值。
在字典中搜尋鍵。如果鍵存在於字典中，則傳回 {ok, Value}，其中 Value 是與 Key 關聯的值；如果鍵不存在，則傳回 error。
依序呼叫 Orddict 的鍵和值上的 Fun，並帶有一個額外的引數 Acc（累加器的縮寫）。Fun 必須傳回一個新的累加器，該累加器會傳遞到下一次呼叫。如果列表為空，則傳回 Acc0。
將 Key-Value 列表 List 轉換為字典。
如果 Orddict 沒有元素，則傳回 true，否則傳回 false。
測試 Key 是否包含在字典 Orddict 中。
依序呼叫 Orddict1 的鍵和值上的 Fun，為每個鍵傳回一個新值。
合併兩個字典 Orddict1 和 Orddict2，以建立一個新的字典。兩個字典中的所有 Key-Value 配對都會包含在新字典中。
建立一個新的字典。
傳回 Orddict 中的元素數量。
在字典中儲存 Key-Value 配對。如果 Key 已存在於 Orddict1 中，則關聯的值會被 Value 取代。
此函數會從字典中傳回值，並傳回不含此值的新字典。如果鍵不存在於字典中，則傳回 error。
將字典轉換為列表表示法。
透過呼叫值上的 Fun 來取得新值，以更新字典中的值。如果 Key 不存在於字典中，則會產生例外。
透過呼叫值上的 Fun 來取得新值，以更新字典中的值。如果 Key 不存在於字典中，則會將 Initial 儲存為第一個值。
將 Increment 加到與 Key 關聯的值，並儲存此值。如果 Key 不存在於字典中，則會將 Increment 儲存為第一個值。
類型
函數
-spec append(Key, Value, Orddict1) -> Orddict2 when Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value).
將新的 Value 附加到與 Key 關聯的目前值列表中。如果與 Key 關聯的初始值不是值列表，則會產生例外。
另請參閱 注意事項 區段。
範例 1
1> OrdDict1 = orddict:from_list([{x, []}]).
[{x,[]}]
2> OrdDict2 = orddict:append(x, 1, OrdDict1).
[{x,[1]}]
3> OrdDict3 = orddict:append(x, 2, OrdDict2).
[{x,[1,2]}]
4> orddict:append(y, 3, OrdDict3).
[{x,[1,2]},{y,[3]}]範例 2
1> OrdDict1 = orddict:from_list([{a, no_list}]).
[{a,no_list}]
2> orddict:append(a, 1, OrdDict1).
** exception error: bad argument
in operator ++/2
called as no_list ++ [1]-spec append_list(Key, ValList, Orddict1) -> Orddict2 when ValList :: [Value], Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value).
將值列表 ValList 附加到與 Key 關聯的目前值列表中。如果與 Key 關聯的初始值不是值列表，則會產生例外。
另請參閱 注意事項 區段。
範例
1> OrdDict1 = orddict:from_list([{x, []}]).
[{x,[]}]
2> OrdDict2 = orddict:append_list(x, [1,2], OrdDict1).
[{x,[1,2]}]
3> OrdDict3 = orddict:append_list(y, [3,4], OrdDict2).
[{x,[1,2]},{y,[3,4]}]-spec erase(Key, Orddict1) -> Orddict2 when Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value).
從字典中刪除所有具有指定鍵的項目。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:erase(a, OrdDict1).
[{b,2}]-spec fetch(Key, Orddict) -> Value when Orddict :: orddict(Key, Value).
傳回字典 Orddict 中與 Key 關聯的值。此函數假設 Key 存在於字典中。如果 Key 不在字典中，則會產生例外。
另請參閱 注意事項 區段。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:fetch(a, OrdDict1).
1
3> orddict:fetch(missing, OrdDict1).
** exception error: no function clause matching orddict:fetch(missing,[])傳回字典中所有鍵的列表。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:fetch_keys(OrdDict1).
[a,b]-spec filter(Pred, Orddict1) -> Orddict2 when Pred :: fun((Key, Value) -> boolean()), Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value).
Orddict2 是一個字典，其中包含 Orddict1 中所有 Pred(Key, Value) 為 true 的鍵和值。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:filter(fun (K, V) -> V > 1 end, OrdDict1).
[{b,2}]-spec find(Key, Orddict) -> {ok, Value} | error when Orddict :: orddict(Key, Value).
在字典中搜尋鍵。如果鍵存在於字典中，則傳回 {ok, Value}，其中 Value 是與 Key 關聯的值；如果鍵不存在，則傳回 error。
另請參閱 注意事項 區段。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:find(a, OrdDict1).
{ok,1}
3> orddict:find(c, OrdDict1).
error-spec fold(Fun, Acc0, Orddict) -> Acc1 when Fun :: fun((Key, Value, AccIn) -> AccOut), Orddict :: orddict(Key, Value), Acc0 :: Acc, Acc1 :: Acc, AccIn :: Acc, AccOut :: Acc.
依序呼叫 Orddict 的鍵和值上的 Fun，並帶有一個額外的引數 Acc（累加器的縮寫）。Fun 必須傳回一個新的累加器，該累加器會傳遞到下一次呼叫。如果列表為空，則傳回 Acc0。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:fold(fun (K, V, Acc) -> [{K, V+100} | Acc] end, [], OrdDict1).
[{b,102},{a,101}]-spec from_list(List) -> Orddict when List :: [{Key, Value}], Orddict :: orddict(Key, Value).
將 Key-Value 列表 List 轉換為字典。
如果 Orddict 沒有元素，則傳回 true，否則傳回 false。
測試 Key 是否包含在字典 Orddict 中。
-spec map(Fun, Orddict1) -> Orddict2 when Fun :: fun((Key, Value1) -> Value2), Orddict1 :: orddict(Key, Value1), Orddict2 :: orddict(Key, Value2).
依序呼叫 Orddict1 的鍵和值上的 Fun，為每個鍵傳回一個新值。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:map(fun (_K, V) -> V + 100 end, OrdDict1).
[{a,101},{b,102}]-spec merge(Fun, Orddict1, Orddict2) -> Orddict3 when Fun :: fun((Key, Value1, Value2) -> Value), Orddict1 :: orddict(Key, Value1), Orddict2 :: orddict(Key, Value2), Orddict3 :: orddict(Key, Value).
合併兩個字典 Orddict1 和 Orddict2，以建立一個新的字典。兩個字典中的所有 Key-Value 配對都會包含在新字典中。
如果兩個字典中都出現某個鍵，則會呼叫 Fun 並傳入鍵和兩個值，以傳回一個新值。
merge/3 可以定義如下，但速度更快
merge(Fun, D1, D2) ->
fold(fun (K, V1, D) ->
update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
end, D2, D1).範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> OrdDict2 = orddict:from_list([{b, 7}, {c, 8}]).
[{b,7},{c,8}]
3> orddict:merge(fun (K, V1, V2) -> V1 * V2 end, OrdDict1, OrdDict2).
[{a,1},{b,14},{c,8}]建立一個新的字典。
-spec size(Orddict) -> non_neg_integer() when Orddict :: orddict().
傳回 Orddict 中的元素數量。
-spec store(Key, Value, Orddict1) -> Orddict2 when Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value).
在字典中儲存 Key-Value 配對。如果 Key 已存在於 Orddict1 中，則關聯的值會被 Value 取代。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:store(a, 99, OrdDict1).
[{a,99},{b,2}]
3> orddict:store(c, 100, OrdDict1).
[{a,1},{b,2},{c,100}]-spec take(Key, Orddict) -> {Value, Orddict1} | error when Orddict :: orddict(Key, Value), Orddict1 :: orddict(Key, Value), Key :: term(), Value :: term().
此函數會從字典中傳回值，並傳回不含此值的新字典。如果鍵不存在於字典中，則傳回 error。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:take(a, OrdDict1).
{1,[{b,2}]}
3> orddict:take(missing, OrdDict1).
error-spec to_list(Orddict) -> List when Orddict :: orddict(Key, Value), List :: [{Key, Value}].
將字典轉換為列表表示法。
-spec update(Key, Fun, Orddict1) -> Orddict2 when Fun :: fun((Value1 :: Value) -> Value2 :: Value), Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value).
透過呼叫值上的 Fun 來取得新值，以更新字典中的值。如果 Key 不存在於字典中，則會產生例外。
範例
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:update(a, fun (V) -> V + 100 end, OrdDict1).
[{a,101},{b,2}]-spec update(Key, Fun, Initial, Orddict1) -> Orddict2 when Initial :: Value, Fun :: fun((Value1 :: Value) -> Value2 :: Value), Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value).
透過呼叫值上的 Fun 來取得新值，以更新字典中的值。如果 Key 不存在於字典中，則會將 Initial 儲存為第一個值。
例如，append/3 可以定義如下：
append(Key, Val, D) ->
update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).範例 1
1> OrdDict1 = orddict:from_list([{a, 1}, {b, 2}]).
[{a,1},{b,2}]
2> orddict:update(c, fun (V) -> V + 100 end, 99, OrdDict1).
[{a,1},{b,2},{c,99}]範例 2
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}]-spec update_counter(Key, Increment, Orddict1) -> Orddict2 when Orddict1 :: orddict(Key, Value), Orddict2 :: orddict(Key, Value), Increment :: number().
將 Increment 加到與 Key 關聯的值，並儲存此值。如果 Key 不存在於字典中，則會將 Increment 儲存為第一個值。
這可以定義如下，但速度更快：
update_counter(Key, Incr, D) ->
update(Key, fun (Old) -> Old + Incr end, Incr, D).