View Source BiMap (BiMap v1.2.2)

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

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

Protocols

BiMap implements Enumerable, Collectable and Inspect protocols.

Link to this section Summary

Types

k()

Key type

t()
v()

Value type

Functions

Convenience shortcut for delete/3.

Deletes {key, value} pair from bimap.

Deletes {key, _} pair from bimap.

Deletes {_, value} pair from bimap.

Checks if two bimaps are equal.

Fetches the value for specific key in bimap.

Fetches the value for specific key in bimap

Fetches the key for specific value in bimap.

Fetches the key for specific value in bimap

Gets the value for specific key in bimap

Gets the key for specific value in bimap

Checks if bimap contains key.

Checks if bimap contains value.

Returns all keys from bimap.

Returns key ➜ value mapping of bimap.

Convenience shortcut for member?/3.

Checks if bimap contains {key, value} pair.

Creates a new bimap.

Creates a bimap from enumerable of key-value pairs.

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

Convenience shortcut for put/3

Inserts {key, value} pair into bimap.

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

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

Returns value ➜ key mapping of bimap.

Returns the number of elements in bimap.

Returns list of unique key-value pairs in bimap.

Returns all values from bimap.

Link to this section Types

@type k() :: term()

Key type

@type t() :: t(term(), term())
@type t(k, v) :: %BiMap{keys: internal_keys(k, v), values: internal_values(k, v)}
@type v() :: term()

Value type

Link to this section Functions

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

Convenience shortcut for delete/3.

Link to this function

delete(bimap, key, value)

View Source
@spec 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

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]>
@spec delete_key(t(), k()) :: t()

Deletes {key, _} pair from bimap.

If the key does not exist, returns bimap unchanged.

examples

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]>
Link to this function

delete_value(bimap, value)

View Source
@spec delete_value(t(), v()) :: t()

Deletes {_, value} pair from bimap.

If the value does not exist, returns bimap unchanged.

examples

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]>
@spec 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

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
@spec fetch!(t(), k()) :: v()

Fetches the value for specific key in bimap.

Raises ArgumentError if the key is absent.

examples

Examples

iex> bimap = BiMap.new([a: 1])
iex> BiMap.fetch!(bimap, :a)
1
@spec 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

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
Link to this function

fetch_key!(bimap, value)

View Source
@spec 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

Examples

iex> bimap = BiMap.new([a: 1])
iex> BiMap.fetch_key!(bimap, 1)
:a
@spec fetch_key(t(), v()) :: {:ok, k()} | :error

Fetches the key for specific value in bimap

This function is exact mirror of fetch/2.

examples

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
Link to this function

get(bimap, key, default \\ nil)

View Source
@spec 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

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
Link to this function

get_key(bimap, value, default \\ nil)

View Source
@spec get_key(t(), v(), k()) :: k()

Gets the key for specific value in bimap

This function is exact mirror of get/3.

examples

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
@spec has_key?(t(), k()) :: boolean()

Checks if bimap contains key.

examples

Examples

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

has_value?(bimap, value)

View Source
@spec has_value?(t(), v()) :: boolean()

Checks if bimap contains value.

examples

Examples

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

Returns all keys from bimap.

examples

Examples

iex> bimap = BiMap.new([a: 1, b: 2])
iex> BiMap.keys(bimap)
[:a, :b]
@spec left(t()) :: %{required(k()) => v()}

Returns key ➜ value mapping of bimap.

examples

Examples

iex> bimap = BiMap.new([a: "foo", b: "bar"])
iex> BiMap.left(bimap)
%{a: "foo", b: "bar"}
@spec member?(
  t(),
  {k(), v()}
) :: boolean()

Convenience shortcut for member?/3.

Link to this function

member?(bimap, key, value)

View Source
@spec member?(t(), k(), v()) :: boolean()

Checks if bimap contains {key, value} pair.

examples

Examples

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

Creates a new bimap.

examples

Examples

iex> BiMap.new
#BiMap<[]>
@spec new(Enum.t()) :: t()

Creates a bimap from enumerable of key-value pairs.

Duplicated pairs are removed; the latest one prevails.

examples

Examples

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

new(enumerable, transform)

View Source
@spec new(Enum.t(), (term() -> {k(), v()})) :: t()

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

examples

Examples

iex> BiMap.new([1, 2, 1], fn x -> {x, x * 2} end)
#BiMap<[{1, 2}, {2, 4}]>
@spec put(
  t(),
  {k(), v()}
) :: t()

Convenience shortcut for put/3

@spec 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

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]>
Link to this function

put_new_key(bimap, key, value)

View Source
@spec 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

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]>
Link to this function

put_new_value(bimap, key, value)

View Source
@spec 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

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]>
@spec right(t()) :: %{required(v()) => k()}

Returns value ➜ key mapping of bimap.

examples

Examples

iex> bimap = BiMap.new([a: "foo", b: "bar"])
iex> BiMap.right(bimap)
%{"foo" => :a, "bar" => :b}
@spec 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

Examples

iex> BiMap.size(BiMap.new)
0

iex> bimap = BiMap.new([a: "foo", b: "bar"])
iex> BiMap.size(bimap)
2
@spec to_list(t()) :: [{k(), v()}]

Returns list of unique key-value pairs in bimap.

examples

Examples

iex> bimap = BiMap.new([a: "foo", b: "bar"])
iex> BiMap.to_list(bimap)
[a: "foo", b: "bar"]
@spec values(t()) :: [v()]

Returns all values from bimap.

examples

Examples

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