---
name: "dict"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/dict/3erl"
---

# dict(3erl)

Key-value dictionary.

## NAME

dict - Key-value dictionary.

## DESCRIPTION

This module provides a *Key*-*Value* dictionary. The representation of a dictionary is not defined.

This module provides the same interface as the *[orddict(3erl)](/orddict/3erl.md)* 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 (*==*).

## DATA TYPES

```
dict(Key, Value)
```

Dictionary as returned by *new/0*.

```
dict() = dict(term(), term())
```

## EXPORTS

```
append(Key, Value, Dict1) -> Dict2
```

Types:

Dict1 = Dict2 = dict(Key, Value)\

Appends a new *Value* to the current list of values associated with *Key*.

See also section Notes.

```
append_list(Key, ValList, Dict1) -> Dict2
```

Types:

Dict1 = Dict2 = dict(Key, Value)\
 ValList = \[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.

See also section Notes.

```
erase(Key, Dict1) -> Dict2
```

Types:

Dict1 = Dict2 = dict(Key, Value)\

Erases all items with a given key from a dictionary.

```
fetch(Key, Dict) -> Value
```

Types:

Dict = dict(Key, Value)\

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.

```
fetch_keys(Dict) -> Keys
```

Types:

Dict = dict(Key, Value :: term())\
 Keys = \[Key\]\

Returns a list of all keys in dictionary *Dict*.

```
take(Key, Dict) -> {Value, Dict1} | error
```

Types:

Dict = Dict1 = dict(Key, Value)\
 Key = Value = term()\

This function returns value from dictionary and a new dictionary without this value. Returns *error* if the key is not present in the dictionary.

```
filter(Pred, Dict1) -> Dict2
```

Types:

Pred = fun((Key, Value) -\> boolean())\
 Dict1 = Dict2 = dict(Key, Value)\

*Dict2* is a dictionary of all keys and values in *Dict1* for which *Pred(Key, Value)* is *true*.

```
find(Key, Dict) -> {ok, Value} | error
```

Types:

Dict = dict(Key, Value)\

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.

See also section Notes.

```
fold(Fun, Acc0, Dict) -> Acc1
```

Types:

Fun = fun((Key, Value, AccIn) -\> AccOut)\
 Dict = dict(Key, Value)\
 Acc0 = Acc1 = AccIn = AccOut = Acc\

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.

```
from_list(List) -> Dict
```

Types:

Dict = dict(Key, Value)\
 List = \[{Key, Value}\]\

Converts the *Key*-*Value* list *List* to dictionary *Dict*.

```
is_empty(Dict) -> boolean()
```

Types:

Dict = dict()\

Returns *true* if dictionary *Dict* has no elements, otherwise *false*.

```
is_key(Key, Dict) -> boolean()
```

Types:

Dict = dict(Key, Value :: term())\

Tests if *Key* is contained in dictionary *Dict*.

```
map(Fun, Dict1) -> Dict2
```

Types:

Fun = fun((Key, Value1) -\> Value2)\
 Dict1 = dict(Key, Value1)\
 Dict2 = dict(Key, Value2)\

Calls *Fun* on successive keys and values of dictionary *Dict1* to return a new value for each key. The evaluation order is undefined.

```
merge(Fun, Dict1, Dict2) -> Dict3
```

Types:

Fun = fun((Key, Value1, Value2) -\> Value)\
 Dict1 = dict(Key, Value1)\
 Dict2 = dict(Key, Value2)\
 Dict3 = dict(Key, Value)\

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:

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

```
new() -> dict()
```

Creates a new dictionary.

```
size(Dict) -> integer() >= 0
```

Types:

Dict = dict()\

Returns the number of elements in dictionary *Dict*.

```
store(Key, Value, Dict1) -> Dict2
```

Types:

Dict1 = Dict2 = dict(Key, Value)\

Stores a *Key*-*Value* pair in dictionary *Dict2*. If *Key* already exists in *Dict1*, the associated value is replaced by *Value*.

```
to_list(Dict) -> List
```

Types:

Dict = dict(Key, Value)\
 List = \[{Key, Value}\]\

Converts dictionary *Dict* to a list representation.

```
update(Key, Fun, Dict1) -> Dict2
```

Types:

Dict1 = Dict2 = dict(Key, Value)\
 Fun = fun((Value1 :: Value) -\> Value2 :: 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.

```
update(Key, Fun, Initial, Dict1) -> Dict2
```

Types:

Dict1 = Dict2 = dict(Key, Value)\
 Fun = fun((Value1 :: Value) -\> Value2 :: Value)\
 Initial = 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:

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

```
update_counter(Key, Increment, Dict1) -> Dict2
```

Types:

Dict1 = Dict2 = dict(Key, Value)\
 Increment = number()\

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.

This can be defined as follows, but is faster:

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

## NOTES

Functions *append* and *append\_list* are included so that keyed values can be stored in a list *accumulator*, for example:

```
> 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*.

## SEE ALSO

*[gb\_trees(3erl)](/gb_trees/3erl.md)*, *[orddict(3erl)](/orddict/3erl.md)*