orddict(3erl)

orddict(3erl) ✨

okay so bestie, you know how sometimes you just need a dictionary that keeps its keys in order? that's literally this module. it's orddict from Erlang, and it's giving "organized queen" energy no cap 💅

🌸 DESCRIPTION 🌸

This module provides a Key-Value dictionary. An orddict 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 Erlang term order. periodt.

This module provides the same interface as the dict(3erl) module but with a 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 (==). iykyk — it's a whole different vibe check for equality 🔥

🎀 DATA TYPES 🎀

• orddict(Key, Value) = [{Key, Value}] — Dictionary as returned by new/0. it's literally just a list of pairs, but make it ordered ✨
• orddict() = orddict(term(), term()) — the general form, bestie 🫶

👑 EXPORTS 👑

💖 append(Key, Value, Orddict1) -> Orddict2

Types:

Orddict1 = Orddict2 = orddict(Key, Value)

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. so if it's not a list, it's gonna throw hands 😭

See also section Notes. (spoiler: it's giving list accumulator realness)

💖 append_list(Key, ValList, Orddict1) -> Orddict2

Types:

ValList = [Value]
Orddict1 = Orddict2 = orddict(Key, Value)

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. same energy as above, but with a whole list of values at once — slay 🦋

See also section Notes.

💖 erase(Key, Orddict1) -> Orddict2

Types:

Orddict1 = Orddict2 = orddict(Key, Value)

Erases all items with a specified key from a dictionary. gone. deleted. not me erasing that key 💀

💖 fetch(Key, Orddict) -> Value

Types:

Orddict = orddict(Key, Value)

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. so like, don't use this if you're not sure — it will not be gentle 😤

See also section Notes.

💖 fetch_keys(Orddict) -> Keys

Types:

Orddict = orddict(Key, Value :: term())
Keys = [Key]

Returns a list of all keys in a dictionary. all of them. the whole squad 👯‍♀️

💖 take(Key, Orddict) -> {Value, Orddict1} | error

Types:

Orddict = Orddict1 = orddict(Key, Value)
Key = Value = term()

This function returns value from dictionary and new dictionary without this value. Returns error if the key is not present in the dictionary. it's giving "I'll take that and leave the rest" main character energy 👑

💖 filter(Pred, Orddict1) -> Orddict2

Types:

Pred = fun((Key, Value) -> boolean())
Orddict1 = Orddict2 = orddict(Key, Value)

Orddict2 is a dictionary of all keys and values in Orddict1 for which Pred(Key, Value) is true. so you're filtering out the ones that don't pass the vibe check ✨

💖 find(Key, Orddict) -> {ok, Value} | error

Types:

Orddict = orddict(Key, Value)

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. this one is polite about missing keys — no exception, just a little error 🥺

See also section Notes.

💖 fold(Fun, Acc0, Orddict) -> Acc1

Types:

Fun = fun((Key, Value, AccIn) -> AccOut)
Orddict = orddict(Key, Value)
Acc0 = Acc1 = AccIn = AccOut = Acc

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. lowkey iconic — it's the reduce of the orddict world 💜

💖 from_list(List) -> Orddict

Types:

List = [{Key, Value}]
Orddict = orddict(Key, Value)

Converts the Key-Value list List to a dictionary. glow-up from list to dict 💅

💖 is_empty(Orddict) -> boolean()

Types:

Orddict = orddict()

Returns true if Orddict has no elements, otherwise false. simple vibe check 🎀

💖 is_key(Key, Orddict) -> boolean()

Types:

Orddict = orddict(Key, Value :: term())

Tests if Key is contained in dictionary Orddict. yes or no, bestie 🌸

💖 map(Fun, Orddict1) -> Orddict2

Types:

Fun = fun((Key, Value1) -> Value2)
Orddict1 = orddict(Key, Value1)
Orddict2 = orddict(Key, Value2)

Calls Fun on successive keys and values of Orddict1 tvo return a new value for each key. (yes, "tvo" is in the original — typo and all, we're keeping it fr fr 💀)

💖 merge(Fun, Orddict1, Orddict2) -> Orddict3

Types:

Fun = fun((Key, Value1, Value2) -> Value)
Orddict1 = orddict(Key, Value1)
Orddict2 = orddict(Key, Value2)
Orddict3 = orddict(Key, Value)

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. If a key occurs in both dictionaries, Fun is called with the key and both values to return a new value. merge/3 can be defined as follows, but is faster:

merge(Fun, D1, D2) ->
    fold(fun (K, V1, D) ->
                 update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
         end, D2, D1).

it's giving "two worlds collide" but make it efficient 🌈

💖 new() -> orddict()

Creates a new dictionary. fresh start, blank slate, new me ✨

💖 size(Orddict) -> integer() >= 0

Types:

Orddict = orddict()

Returns the number of elements in an Orddict. how many besties are in the squad 🔢

💖 store(Key, Value, Orddict1) -> Orddict2

Types:

Orddict1 = Orddict2 = orddict(Key, Value)

Stores a Key-Value pair in a dictionary. If the Key already exists in Orddict1, the associated value is replaced by Value. so if it's already there, it gets a glow-up 💖

💖 to_list(Orddict) -> List

Types:

Orddict = orddict(Key, Value)
List = [{Key, Value}]

Converts a dictionary to a list representation. back to basics 🦋

💖 update(Key, Fun, Orddict1) -> Orddict2

Types:

Fun = fun((Value1 :: Value) -> Value2 :: Value)
Orddict1 = Orddict2 = orddict(Key, Value)

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. so if it's not there, it's gonna be a whole thing 😭

💖 update(Key, Fun, Initial, Orddict1) -> Orddict2

Types:

Initial = Value
Fun = fun((Value1 :: Value) -> Value2 :: Value)
Orddict1 = Orddict2 = orddict(Key, Value)

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 can be defined as follows:

append(Key, Val, D) ->
    update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).

this one is the safe version — it handles the missing key with grace 💅

💖 update_counter(Key, Increment, Orddict1) -> Orddict2

Types:

Orddict1 = Orddict2 = orddict(Key, Value)
Increment = number()

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.

This can be defined as follows, but is faster:

update_counter(Key, Incr, D) ->
    update(Key, fun (Old) -> Old + Incr end, Incr, D).

math but make it a dict update 🔥

📝 NOTES 📝

Functions append/3 and append_list/3 are included so that keyed values can be stored in a list accumulator, for example:

> 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. it's the lazy girl's guide to efficient list accumulation, and we love her for it 🫶

Function fetch/2 is to be used if the key is known to be in the dictionary, otherwise function find/2. so like, know your keys before you fetch, bestie 👑

👀 SEE ALSO 👀

dict(3erl), gb_trees(3erl)

---

okay that's the whole thing! this iconic piece of Erlang was brought to you by Ericsson AB, version stdlib 4.3.1.3, and we're obsessed 💜✨ no cap, fr fr.