BiMap (BiMap v1.2.1) View Source

Bi-directional map implementation backed by two maps.

In computer science, a bidirectional map, or hash bag, is an associative data structure in which the (key, value) pairs form a one-to-one correspondence. Thus the binary relation is functional in each direction: value can also act as a key to key. A pair (a, b) thus provides a unique coupling between a a and b so that b can be found when a is used as a key and a can be found when b is used as a key.
~Wikipedia

Entries in bimap do not follow any order.

BiMaps 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. As a bidirectional key-value structure, bimaps do not allow duplicated keys and values. This means it is not possible to store [(A, B), (A, C)] or [(X, Z), (Y, Z)] in the bimap. If you need to lift this restriction to only not allowing duplicated key-value pairs, check out BiMultiMap.

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

Example

iex> bm = BiMap.new(a: 1, b: 2)
#BiMap<[a: 1, b: 2]>
iex> BiMap.get(bm, :a)
1
iex> BiMap.get_key(bm, 2)
:b
iex> BiMap.put(bm, :a, 3)
#BiMap<[a: 3, b: 2]>
iex> BiMap.put(bm, :c, 2)
#BiMap<[a: 1, c: 2]>

Protocols

BiMap implements Enumerable, Collectable and Inspect protocols.

Link to this section Summary

Types

k()

Key type

t()

t(k, v)

v()

Value type

Functions

delete(bimap, kv)

Convenience shortcut for delete/3.

delete(bimap, key, value)

Deletes {key, value} pair from bimap.

delete_key(bimap, key)

Deletes {key, _} pair from bimap.

delete_value(bimap, value)

Deletes {_, value} pair from bimap.

equal?(bimap1, bimap2)

Checks if two bimaps are equal.

fetch(bimap, key)

Fetches the value for specific key in bimap

fetch!(bimap, key)

Fetches the value for specific key in bimap.

fetch_key(bimap, value)

Fetches the key for specific value in bimap

fetch_key!(bimap, value)

Fetches the key for specific value in bimap.

get(bimap, key, default \\ nil)

Gets the value for specific key in bimap

get_key(bimap, value, default \\ nil)

Gets the key for specific value in bimap

has_key?(bimap, key)

Checks if bimap contains key.

has_value?(bimap, value)

Checks if bimap contains value.

keys(bimap)

Returns all keys from bimap.

left(bimap)

Returns key ➜ value mapping of bimap.

member?(bimap, kv)

Convenience shortcut for member?/3.

member?(bimap, key, value)

Checks if bimap contains {key, value} pair.

new()

Creates a new bimap.

new(enumerable)

Creates a bimap from enumerable of key-value pairs.

new(enumerable, transform)

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

put(bimap, kv)

Convenience shortcut for put/3

put(bimap, key, value)

Inserts {key, value} pair into bimap.

put_new_key(bimap, key, value)

Inserts {key, value} pair into bimap if key is not already in bimap.

put_new_value(bimap, key, value)

Inserts {key, value} pair into bimap if value is not already in bimap.

right(bimap)

Returns value ➜ key mapping of bimap.

size(bimap)

Returns the number of elements in bimap.

to_list(bimap)

Returns list of unique key-value pairs in bimap.

values(bimap)

Returns all values from bimap.

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(bimap, kv)

Specs

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

Convenience shortcut for delete/3.

delete(bimap, key, value)

Specs

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

Deletes {key, value} pair from bimap.

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

Examples

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

delete_key(bimap, key)

Specs

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

Deletes {key, _} pair from bimap.

If the key does not exist, returns bimap unchanged.

Examples

iex> bimap = BiMap.new([a: 1, b: 2])
iex> BiMap.delete_key(bimap, :b)
#BiMap<[a: 1]>
iex> BiMap.delete_key(bimap, :c)
#BiMap<[a: 1, b: 2]>

delete_value(bimap, value)

Specs

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

Deletes {_, value} pair from bimap.

If the value does not exist, returns bimap unchanged.

Examples

iex> bimap = BiMap.new([a: 1, b: 2])
iex> BiMap.delete_value(bimap, 2)
#BiMap<[a: 1]>
iex> BiMap.delete_value(bimap, 3)
#BiMap<[a: 1, b: 2]>

equal?(bimap1, bimap2)

Specs

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

Checks if two bimaps are equal.

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

Examples

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

fetch(bimap, key)

Specs

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

Fetches the value for specific key in bimap

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

Examples

iex> BiMap.fetch(BiMap.new(), :a)
:error
iex> bimap = BiMap.new([a: 1])
iex> BiMap.fetch(bimap, :a)
{:ok, 1}
iex> BiMap.fetch(bimap, :b)
:error

fetch!(bimap, key)

Specs

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

Fetches the value for specific key in bimap.

Raises ArgumentError if the key is absent.

Examples

iex> bimap = BiMap.new([a: 1])
iex> BiMap.fetch!(bimap, :a)
1

fetch_key(bimap, value)

Specs

fetch_key(t(), v()) :: {:ok, k()} | :error

Fetches the key for specific value in bimap

This function is exact mirror of fetch/2.

Examples

iex> BiMap.fetch_key(BiMap.new, 1)
:error
iex> bimap = BiMap.new([a: 1])
iex> BiMap.fetch_key(bimap, 1)
{:ok, :a}
iex> BiMap.fetch_key(bimap, 2)
:error

fetch_key!(bimap, value)

Specs

fetch_key!(t(), v()) :: k()

Fetches the key for specific value in bimap.

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

Examples

iex> bimap = BiMap.new([a: 1])
iex> BiMap.fetch_key!(bimap, 1)
:a

get(bimap, key, default \\ nil)

Specs

get(t(), k(), v()) :: v()

Gets the value for specific key in bimap

If key is present in bimap with value value, then value is returned. Otherwise, default is returned (which is nil unless specified otherwise).

Examples

iex> BiMap.get(BiMap.new(), :a)
nil
iex> bimap = BiMap.new([a: 1])
iex> BiMap.get(bimap, :a)
1
iex> BiMap.get(bimap, :b)
nil
iex> BiMap.get(bimap, :b, 3)
3

get_key(bimap, value, default \\ nil)

Specs

get_key(t(), v(), k()) :: k()

Gets the key for specific value in bimap

This function is exact mirror of get/3.

Examples

iex> BiMap.get_key(BiMap.new, 1)
nil
iex> bimap = BiMap.new([a: 1])
iex> BiMap.get_key(bimap, 1)
:a
iex> BiMap.get_key(bimap, 2)
nil
iex> BiMap.get_key(bimap, 2, :b)
:b

has_key?(bimap, key)

Specs

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

Checks if bimap contains key.

Examples

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

has_value?(bimap, value)

Specs

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

Checks if bimap contains value.

Examples

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

keys(bimap)

Specs

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

Returns all keys from bimap.

Examples

iex> bimap = BiMap.new([a: 1, b: 2])
iex> BiMap.keys(bimap)
[:a, :b]

left(bimap)

Specs

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

Returns key ➜ value mapping of bimap.

Examples

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

member?(bimap, kv)

Specs

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

Convenience shortcut for member?/3.

member?(bimap, key, value)

Specs

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

Checks if bimap contains {key, value} pair.

Examples

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

new()

Specs

new() :: t()

Creates a new bimap.

Examples

iex> BiMap.new
#BiMap<[]>

new(enumerable)

Specs

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

Creates a bimap from enumerable of key-value pairs.

Duplicated pairs are removed; the latest one prevails.

Examples

iex> BiMap.new([a: "foo", b: "bar"])
#BiMap<[a: "foo", b: "bar"]>

new(enumerable, transform)

Specs

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

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

Examples

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

put(bimap, kv)

Specs

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

Convenience shortcut for put/3

put(bimap, key, value)

Specs

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

Inserts {key, value} pair into bimap.

If either key or value is already in bimap, any overlapping bindings are deleted.

Examples

iex> bimap = BiMap.new
#BiMap<[]>
iex> bimap = BiMap.put(bimap, :a, 0)
#BiMap<[a: 0]>
iex> bimap = BiMap.put(bimap, :a, 1)
#BiMap<[a: 1]>
iex> BiMap.put(bimap, :b, 1)
#BiMap<[b: 1]>

put_new_key(bimap, key, value)

Specs

put_new_key(t(), k(), v()) :: t()

Inserts {key, value} pair into bimap if key is not already in bimap.

If key already exists in bimap, bimap is returned unchanged.

If key does not exist and value is already in bimap, any overlapping bindings are deleted.

Examples

iex> bimap = BiMap.new
#BiMap<[]>
iex> bimap = BiMap.put_new_key(bimap, :a, 0)
#BiMap<[a: 0]>
iex> bimap = BiMap.put_new_key(bimap, :a, 1)
#BiMap<[a: 0]>
iex> BiMap.put_new_key(bimap, :b, 1)
#BiMap<[a: 0, b: 1]>
iex> BiMap.put_new_key(bimap, :c, 1)
#BiMap<[a: 0, c: 1]>

put_new_value(bimap, key, value)

Specs

put_new_value(t(), k(), v()) :: t()

Inserts {key, value} pair into bimap if value is not already in bimap.

If value already exists in bimap, bimap is returned unchanged.

If value does not exist and key is already in bimap, any overlapping bindings are deleted.

Examples

iex> bimap = BiMap.new
#BiMap<[]>
iex> bimap = BiMap.put_new_value(bimap, :a, 0)
#BiMap<[a: 0]>
iex> bimap = BiMap.put_new_value(bimap, :a, 1)
#BiMap<[a: 1]>
iex> BiMap.put_new_value(bimap, :b, 1)
#BiMap<[a: 1]>
iex> BiMap.put_new_value(bimap, :c, 2)
#BiMap<[a: 1, c: 2]>

right(bimap)

Specs

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

Returns value ➜ key mapping of bimap.

Examples

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

size(bimap)

Specs

size(t()) :: non_neg_integer()

Returns the number of elements in bimap.

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

Examples

iex> BiMap.size(BiMap.new)
0

iex> bimap = BiMap.new([a: "foo", b: "bar"])
iex> BiMap.size(bimap)
2

to_list(bimap)

Specs

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

Returns list of unique key-value pairs in bimap.

Examples

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

values(bimap)

Specs

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

Returns all values from bimap.

Examples

iex> bimap = BiMap.new([a: 1, b: 2])
iex> BiMap.values(bimap)
[1, 2]