BiMultiMap (BiMap v1.2.1) View Source

Bi-directional multimap implementation backed by two multimaps.

Entries in bimap do not follow any order.

BiMultiMaps do not impose any restriction on the key and value type: anything can be a key in a bimap, and also anything can be a value.

BiMultiMaps differ from BiMaps by disallowing duplicates only among key-value pairs, not among keys and values separately. This means it is possible to store [(A, B), (A, C)] or [(X, Z), (Y, Z)] in BiMultiMap.

Keys and values are compared using the exact-equality operator (===).

Example

iex> mm = BiMultiMap.new(a: 1, b: 2, b: 1)
#BiMultiMap<[a: 1, b: 1, b: 2]>
iex> BiMultiMap.get(mm, :a)
[1]
iex> BiMultiMap.get_keys(mm, 1)
[:a, :b]
iex> BiMultiMap.put(mm, :a, 3)
#BiMultiMap<[a: 1, a: 3, b: 1, b: 2]>

Protocols

BiMultiMap implements Enumerable, Collectable and Inspect protocols.

Link to this section Summary

Types

k()

Key type

t()

t(k, v)

v()

Value type

Functions

delete(bimultimap, kv)

Convenience shortcut for delete/3.

delete(bimultimap, key, value)

Deletes {key, value} pair from bimultimap.

delete_key(bimultimap, key)

Deletes {key, _} pair from bimultimap.

delete_value(bimultimap, value)

Deletes {_, value} pair from bimultimap.

equal?(bimultimap1, bimultimap2)

Checks if two bimultimaps are equal.

fetch(bimultimap, key)

Fetches all values for specific key in bimultimap

fetch!(bimultimap, key)

Fetches all values for specific key in bimultimap

fetch_keys(bimultimap, value)

Fetches all keys for specific value in bimultimap

fetch_keys!(bimultimap, value)

Fetches all keys for specific value in bimultimap

get(bimultimap, key, default \\ [])

Gets all values for specific key in bimultimap

get_keys(bimultimap, value, default \\ [])

Gets all keys for specific value in bimultimap

has_key?(bimultimap, key)

Checks if bimultimap contains key.

has_value?(bimultimap, value)

Checks if bimultimap contains value.

keys(bimultimap)

Returns all unique keys from bimultimap.

left(bimultimap)

Returns key ➜ [value] mapping of bimultimap.

member?(bimultimap, kv)

Convenience shortcut for member?/3.

member?(bimultimap, key, value)

Checks if bimultimap contains {key, value} pair.

new()

Creates a new bimultimap.

new(enumerable)

Creates a bimultimap from enumerable of key-value pairs.

new(enumerable, transform)

Creates a bimultimap from enumerable via transform function returning key-value pairs.

put(bimultimap, kv)

Convenience shortcut for put/3

put(bimultimap, key, value)

Inserts {key, value} pair into bimultimap.

right(bimultimap)

Returns value ➜ key mapping of bimultimap.

size(bimultimap)

Returns the number of elements in bimultimap.

to_list(bimultimap)

Returns list of unique key-value pairs in bimultimap.

values(bimultimap)

Returns all unique values from bimultimap.

Link to this section Types

k()

Specs

k() :: any()

Key type

t()

Specs

t() :: t(any(), any())

t(k, v)

(opaque)

Specs

t(k, v)

v()

Specs

v() :: any()

Value type

Link to this section Functions

delete(bimultimap, kv)

Specs

delete(t(), {k(), v()}) :: t()

Convenience shortcut for delete/3.

delete(bimultimap, key, value)

Specs

delete(t(), k(), v()) :: t()

Deletes {key, value} pair from bimultimap.

If the key does not exist, or value does not match, returns bimultimap unchanged.

Examples

iex> bimultimap = BiMultiMap.new([a: 1, b: 2, c: 2])
iex> BiMultiMap.delete(bimultimap, :b, 2)
#BiMultiMap<[a: 1, c: 2]>
iex> BiMultiMap.delete(bimultimap, :c, 3)
#BiMultiMap<[a: 1, b: 2, c: 2]>

delete_key(bimultimap, key)

Specs

delete_key(t(), k()) :: t()

Deletes {key, _} pair from bimultimap.

If the key does not exist, returns bimultimap unchanged.

Examples

iex> bimultimap = BiMultiMap.new([a: 1, b: 2, b: 3])
iex> BiMultiMap.delete_key(bimultimap, :b)
#BiMultiMap<[a: 1]>
iex> BiMultiMap.delete_key(bimultimap, :c)
#BiMultiMap<[a: 1, b: 2, b: 3]>

delete_value(bimultimap, value)

Specs

delete_value(t(), v()) :: t()

Deletes {_, value} pair from bimultimap.

If the value does not exist, returns bimultimap unchanged.

Examples

iex> bimultimap = BiMultiMap.new([a: 1, b: 2, c: 1])
iex> BiMultiMap.delete_value(bimultimap, 1)
#BiMultiMap<[b: 2]>
iex> BiMultiMap.delete_value(bimultimap, 3)
#BiMultiMap<[a: 1, b: 2, c: 1]>

equal?(bimultimap1, bimultimap2)

Specs

equal?(t(), t()) :: boolean()

Checks if two bimultimaps are equal.

Two bimultimaps are considered to be equal if they contain the same keys and those keys are bound with the same values.

Examples

iex> Map.equal?(BiMultiMap.new([a: 1, b: 2, b: 3]), BiMultiMap.new([b: 2, b: 3, a: 1]))
true
iex> Map.equal?(BiMultiMap.new([a: 1, b: 2, b: 3]), BiMultiMap.new([b: 1, b: 3, a: 2]))
false

fetch(bimultimap, key)

Specs

fetch(t(), k()) :: {:ok, [v()]} | :error

Fetches all values for specific key in bimultimap

If key is present in bimultimap with values values, then {:ok, values} is returned. Otherwise, :error is returned.

Examples

iex> BiMultiMap.fetch(BiMultiMap.new(), :a)
:error
iex> bimultimap = BiMultiMap.new([a: 1, c: 1, c: 2])
iex> BiMultiMap.fetch(bimultimap, :a)
{:ok, [1]}
iex> BiMultiMap.fetch(bimultimap, :b)
:error
iex> BiMultiMap.fetch(bimultimap, :c)
{:ok, [1, 2]}

fetch!(bimultimap, key)

Specs

fetch!(t(), k()) :: [v()]

Fetches all values for specific key in bimultimap

Raises ArgumentError if the key is absent.

Examples

iex> bimultimap = BiMultiMap.new([a: 1, c: 1, c: 2])
iex> BiMultiMap.fetch!(bimultimap, :a)
[1]
iex> BiMultiMap.fetch!(bimultimap, :c)
[1, 2]

fetch_keys(bimultimap, value)

Specs

fetch_keys(t(), v()) :: {:ok, [k()]} | :error

Fetches all keys for specific value in bimultimap

This function is exact mirror of fetch/2.

Examples

iex> BiMultiMap.fetch_keys(BiMultiMap.new, 1)
:error
iex> bimultimap = BiMultiMap.new([a: 1, c: 3, d: 3])
iex> BiMultiMap.fetch_keys(bimultimap, 1)
{:ok, [:a]}
iex> BiMultiMap.fetch_keys(bimultimap, 2)
:error
iex> BiMultiMap.fetch_keys(bimultimap, 3)
{:ok, [:c, :d]}

fetch_keys!(bimultimap, value)

Specs

fetch_keys!(t(), v()) :: [k()]

Fetches all keys for specific value in bimultimap

Raises ArgumentError if the key is absent. This function is exact mirror of fetch!/2.

Examples

iex> bimultimap = BiMultiMap.new([a: 1, c: 3, d: 3])
iex> BiMultiMap.fetch_keys!(bimultimap, 1)
[:a]
iex> BiMultiMap.fetch_keys!(bimultimap, 3)
[:c, :d]

get(bimultimap, key, default \\ [])

Specs

get(t(), k(), any()) :: [v()] | any()

Gets all values for specific key in bimultimap

If key is present in bimultimap with values values, then values are returned. Otherwise, default is returned (which is [] unless specified otherwise).

Examples

iex> BiMultiMap.get(BiMultiMap.new(), :a)
[]
iex> bimultimap = BiMultiMap.new([a: 1, c: 1, c: 2])
iex> BiMultiMap.get(bimultimap, :a)
[1]
iex> BiMultiMap.get(bimultimap, :b)
[]
iex> BiMultiMap.get(bimultimap, :b, 3)
3
iex> BiMultiMap.get(bimultimap, :c)
[1, 2]

get_keys(bimultimap, value, default \\ [])

Specs

get_keys(t(), v(), any()) :: [k()] | any()

Gets all keys for specific value in bimultimap

This function is exact mirror of get/3.

Examples

iex> BiMultiMap.get_keys(BiMultiMap.new, 1)
[]
iex> bimultimap = BiMultiMap.new([a: 1, c: 3, d: 3])
iex> BiMultiMap.get_keys(bimultimap, 1)
[:a]
iex> BiMultiMap.get_keys(bimultimap, 2)
[]
iex> BiMultiMap.get_keys(bimultimap, 2, :b)
:b
iex> BiMultiMap.get_keys(bimultimap, 3)
[:c, :d]

has_key?(bimultimap, key)

Specs

has_key?(t(), k()) :: boolean()

Checks if bimultimap contains key.

Examples

iex> bimultimap = BiMultiMap.new([a: "foo", b: "bar"])
iex> BiMultiMap.has_key?(bimultimap, :a)
true
iex> BiMultiMap.has_key?(bimultimap, :x)
false

has_value?(bimultimap, value)

Specs

has_value?(t(), v()) :: boolean()

Checks if bimultimap contains value.

Examples

iex> bimultimap = BiMultiMap.new([a: "foo", b: "bar"])
iex> BiMultiMap.has_value?(bimultimap, "foo")
true
iex> BiMultiMap.has_value?(bimultimap, "moo")
false

keys(bimultimap)

Specs

keys(t()) :: [k()]

Returns all unique keys from bimultimap.

Examples

iex> bimultimap = BiMultiMap.new([a: 1, b: 2, b: 3])
iex> BiMultiMap.keys(bimultimap)
[:a, :b]

left(bimultimap)

Specs

left(t()) :: %{required(k()) => [v()]}

Returns key ➜ [value] mapping of bimultimap.

Examples

iex> bimultimap = BiMultiMap.new([a: "foo", b: "bar", b: "moo"])
iex> BiMultiMap.left(bimultimap)
%{a: ["foo"], b: ["bar", "moo"]}

member?(bimultimap, kv)

Specs

member?(t(), {k(), v()}) :: boolean()

Convenience shortcut for member?/3.

member?(bimultimap, key, value)

Specs

member?(t(), k(), v()) :: boolean()

Checks if bimultimap contains {key, value} pair.

Examples

iex> bimultimap = BiMultiMap.new([a: "foo", a: "moo", b: "bar"])
iex> BiMultiMap.member?(bimultimap, :a, "foo")
true
iex> BiMultiMap.member?(bimultimap, :a, "moo")
true
iex> BiMultiMap.member?(bimultimap, :a, "bar")
false

new()

Specs

new() :: t()

Creates a new bimultimap.

Examples

iex> BiMultiMap.new
#BiMultiMap<[]>

new(enumerable)

Specs

new(Enum.t()) :: t()

Creates a bimultimap from enumerable of key-value pairs.

Duplicated pairs are removed; the latest one prevails.

Examples

iex> BiMultiMap.new([a: 1, a: 2])
#BiMultiMap<[a: 1, a: 2]>

new(enumerable, transform)

Specs

new(Enum.t(), (term() -> {k(), v()})) :: t()

Creates a bimultimap from enumerable via transform function returning key-value pairs.

Examples

iex> BiMultiMap.new([1, 2, 1], fn x -> {x, x * 2} end)
#BiMultiMap<[{1, 2}, {2, 4}]>

put(bimultimap, kv)

Specs

put(t(), {k(), v()}) :: t()

Convenience shortcut for put/3

put(bimultimap, key, value)

Specs

put(t(), k(), v()) :: t()

Inserts {key, value} pair into bimultimap.

If {key, value} is already in bimultimap, it is deleted.

Examples

iex> bimultimap = BiMultiMap.new
#BiMultiMap<[]>
iex> bimultimap = BiMultiMap.put(bimultimap, :a, 1)
#BiMultiMap<[a: 1]>
iex> bimultimap = BiMultiMap.put(bimultimap, :a, 2)
#BiMultiMap<[a: 1, a: 2]>
iex> BiMultiMap.put(bimultimap, :b, 2)
#BiMultiMap<[a: 1, a: 2, b: 2]>

right(bimultimap)

Specs

right(t()) :: %{required(v()) => [k()]}

Returns value ➜ key mapping of bimultimap.

Examples

iex> bimultimap = BiMultiMap.new([a: "foo", b: "bar", c: "bar"])
iex> BiMultiMap.right(bimultimap)
%{"foo" => [:a], "bar" => [:b, :c]}

size(bimultimap)

Specs

size(t()) :: non_neg_integer()

Returns the number of elements in bimultimap.

The size of a bimultimap is the number of key-value pairs that the map contains.

Examples

iex> BiMultiMap.size(BiMultiMap.new)
0

iex> bimultimap = BiMultiMap.new([a: "foo", a: "bar"])
iex> BiMultiMap.size(bimultimap)
2

to_list(bimultimap)

Specs

to_list(t()) :: [{k(), v()}]

Returns list of unique key-value pairs in bimultimap.

Examples

iex> bimultimap = BiMultiMap.new([a: "foo", b: "bar"])
iex> BiMultiMap.to_list(bimultimap)
[a: "foo", b: "bar"]

values(bimultimap)

Specs

values(t()) :: [v()]

Returns all unique values from bimultimap.

Examples

iex> bimultimap = BiMultiMap.new([a: 1, b: 2, c: 2])
iex> BiMultiMap.values(bimultimap)
[1, 2]