Mnemonix v0.8.0 Mnemonix.Features.Map

Functions to operate on key/value pairs within a Mnemonix.Store.Server.

All of these functions are available on the main Mnemonix module.

Summary

Functions

delete(store, key)

Removes the entry under key in store

drop(store, keys)

Drops the given keys from the store

fetch(store, key)

Retrievs the value of the entry under key in store

fetch!(store, key)

Fetches the value for specific key

get(store, key)

Gets the value for a specific key

get(store, key, default)

Gets the value for a specific key with default

get_and_update(store, key, fun)

Gets the value from key and updates it, all in one pass

get_and_update!(store, key, fun)

Gets the value from key and updates it. Raises if there is no key

get_lazy(store, key, fun)

Gets the value for a specific key

has_key?(store, key)

Returns whether a given key exists in the given store

pop(store, key)

Returns and removes the value associated with key in store

pop(store, key, default)

Returns and removes the value associated with key in store with default

pop_lazy(store, key, fun)

Lazily returns and removes the value associated with key in store

put(store, key, value)

Creates a new entry for value under key in store

put_new(store, key, value)

Puts the given value under key unless the entry key already exists

put_new_lazy(store, key, fun)

Evaluates fun and puts the result under key in store unless key is already present

split(store, keys)

Takes all entries corresponding to the given keys and removes them from the store into a separate map

take(store, keys)

Returns a map of all key/value pairs in store where the key is in keys

update(store, key, initial, fun)

Updates the key in store with the given function

update!(store, key, fun)

Updates the key with the given function

Functions

delete(store, key)

delete(Mnemonix.store, Mnemonix.key) ::
  Mnemonix.store |
  no_return

Removes the entry under key in store.

If the key does not exist, the contents of store will be unaffected.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.get(store, :a)
1
iex> Mnemonix.delete(store, :a)
iex> Mnemonix.get(store, :a)
nil

drop(store, keys)

drop(Mnemonix.store, Enumerable.t) ::
  %{optional(Mnemonix.key) => Mnemonix.value} |
  no_return

Drops the given keys from the store.

If keys contains keys that are not in the store, they’re simply ignored.

Examples

iex> store = Mnemonix.drop Mnemonix.new(%{a: 1, b: 2, d: 4}), [:a, :b, :c]
iex> Mnemonix.get store, :a
nil
iex> Mnemonix.get store, :d
4

fetch(store, key)

fetch(Mnemonix.store, Mnemonix.key) ::
  {:ok, Mnemonix.value} |
  :error |
  no_return

Retrievs the value of the entry under key in store.

If the key does not exist, returns :error, otherwise returns {:ok, value}.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.fetch(store, :a)
{:ok, 1}
iex> Mnemonix.fetch(store, :b)
:error

fetch!(store, key)

fetch!(Mnemonix.store, Mnemonix.key) ::
  {:ok, Mnemonix.value} |
  :error |
  no_return

Fetches the value for specific key.

If key does not exist, a KeyError is raised.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.fetch!(store, :a)
1
iex> Mnemonix.fetch!(store, :b)
** (KeyError) key :b not found in: Mnemonix.Stores.Map

get(store, key)

get(Mnemonix.store, Mnemonix.key) ::
  Mnemonix.value |
  no_return

Gets the value for a specific key.

If key does not exist, returns nil.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.get(store, :a)
1
iex> Mnemonix.get(store, :b)
nil

get(store, key, default)

get(Mnemonix.store, Mnemonix.key, Mnemonix.value) ::
  Mnemonix.value |
  no_return

Gets the value for a specific key with default.

If key does not exist, returns default.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.get(store, :a, 2)
1
iex> Mnemonix.get(store, :b, 2)
2

get_and_update(store, key, fun)

get_and_update(Mnemonix.store, Mnemonix.key, (Mnemonix.value -> {get, Mnemonix.value} | :pop)) ::
  {get, Mnemonix.store} |
  no_return when get: term

Gets the value from key and updates it, all in one pass.

This fun argument receives the value of key (or nil if key is not present) and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under key. The fun may also return :pop, implying the current value shall be removed from store and returned.

The returned value is a tuple with the “get” value returned by fun and a reference to the store with the updated value under key.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> {value, ^store} = Mnemonix.get_and_update(store, :a, fn current ->
...>   {current, "new value!"}
...> end)
iex> value
1
iex> Mnemonix.get(store, :a)
"new value!"

iex> store = Mnemonix.new(%{a: 1})
iex> {value, ^store} = Mnemonix.get_and_update(store, :b, fn current ->
...>   {current, "new value!"}
...> end)
iex> value
nil
iex> Mnemonix.get(store, :b)
"new value!"

iex> store = Mnemonix.new(%{a: 1})
iex> {value, ^store} = Mnemonix.get_and_update(store, :a, fn _ -> :pop end)
iex> value
1
iex> Mnemonix.get(store, :a)
nil

iex> store = Mnemonix.new(%{a: 1})
iex> {value, ^store} = Mnemonix.get_and_update(store, :b, fn _ -> :pop end)
iex> value
nil
iex> Mnemonix.get(store, :b)
nil

get_and_update!(store, key, fun)

get_and_update!(Mnemonix.store, Mnemonix.key, (Mnemonix.value -> {get, Mnemonix.value})) ::
  {get, Mnemonix.store} |
  no_return when get: term

Gets the value from key and updates it. Raises if there is no key.

This fun argument receives the value of key and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under key.

The returned value is a tuple with the “get” value returned by fun and a a reference to the store with the updated value under key.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> {value, ^store} = Mnemonix.get_and_update!(store, :a, fn current ->
...>   {current, "new value!"}
...> end)
iex> value
1
iex> Mnemonix.get(store, :a)
"new value!"

iex> store = Mnemonix.new(%{a: 1})
iex> {_value, ^store} = Mnemonix.get_and_update!(store, :b, fn current ->
...>   {current, "new value!"}
...> end)
** (KeyError) key :b not found in: Mnemonix.Stores.Map

iex> store = Mnemonix.new(%{a: 1})
iex> {value, ^store} = Mnemonix.get_and_update!(store, :a, fn _ -> :pop end)
iex> value
1
iex> Mnemonix.get(store, :a)
nil

iex> store = Mnemonix.new(%{a: 1})
iex> {_value, ^store} = Mnemonix.get_and_update!(store, :b, fn _ -> :pop end)
** (KeyError) key :b not found in: Mnemonix.Stores.Map

get_lazy(store, key, fun)

get_lazy(Mnemonix.store, Mnemonix.key, (() -> Mnemonix.value)) ::
  Mnemonix.value |
  no_return

Gets the value for a specific key.

If key does not exist, lazily evaluates fun and returns its result.

This is useful if the default value is very expensive to calculate or generally difficult to setup and teardown again.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Mnemonix.get_lazy(store, :a, fun)
1
iex> Mnemonix.get_lazy(store, :b, fun)
13

has_key?(store, key)

has_key?(Mnemonix.store, Mnemonix.key) :: boolean

Returns whether a given key exists in the given store.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.has_key?(store, :a)
true
iex> Mnemonix.has_key?(store, :b)
false

pop(store, key)

pop(Mnemonix.store, Mnemonix.key) :: {Mnemonix.value, Mnemonix.store}

Returns and removes the value associated with key in store.

If no value is associated with the key, nil is returned.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> {value, ^store} = Mnemonix.pop(store, :a)
iex> value
1
iex> Mnemonix.get(store, :a)
nil
iex> {value, ^store} = Mnemonix.pop(store, :b)
iex> value
nil

pop(store, key, default)

pop(Mnemonix.store, Mnemonix.key, default :: term) :: {Mnemonix.value, Mnemonix.store}

Returns and removes the value associated with key in store with default.

If no value is associated with the key but default is given, that will be returned instead without touching the store.

Examples

iex> store = Mnemonix.new()
iex> {value, ^store} = Mnemonix.pop(store, :a)
iex> value
nil
iex> {value, ^store} = Mnemonix.pop(store, :b, 2)
iex> value
2

pop_lazy(store, key, fun)

pop_lazy(Mnemonix.store, Mnemonix.key, (() -> Mnemonix.value)) :: {Mnemonix.value, Mnemonix.store}

Lazily returns and removes the value associated with key in store.

This is useful if the default value is very expensive to calculate or generally difficult to setup and teardown again.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> {value, ^store} = Mnemonix.pop_lazy(store, :a, fun)
iex> value
1
iex> {value, ^store} = Mnemonix.pop_lazy(store, :b, fun)
iex> value
13

put(store, key, value)

put(Mnemonix.store, Mnemonix.key, Mnemonix.value) ::
  Mnemonix.store |
  no_return

Creates a new entry for value under key in store.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.get(store, :b)
nil
iex> Mnemonix.put(store, :b, 2)
iex> Mnemonix.get(store, :b)
2

put_new(store, key, value)

put_new(Mnemonix.store, Mnemonix.key, Mnemonix.value) :: Mnemonix.store

Puts the given value under key unless the entry key already exists.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.put_new(store, :b, 2)
iex> Mnemonix.get(store, :b)
2
iex> Mnemonix.put_new(store, :b, 3)
iex> Mnemonix.get(store, :b)
2

put_new_lazy(store, key, fun)

put_new_lazy(Mnemonix.store, Mnemonix.key, (() -> Mnemonix.value)) ::
  Mnemonix.store |
  no_return

Evaluates fun and puts the result under key in store unless key is already present.

This is useful if the value is very expensive to calculate or generally difficult to setup and teardown again.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Mnemonix.put_new_lazy(store, :b, fun)
iex> Mnemonix.get(store, :b)
13
iex> Mnemonix.put_new_lazy(store, :a, fun)
iex> Mnemonix.get(store, :a)
1

split(store, keys)

split(Mnemonix.store, Enumerable.t) ::
  {%{optional(Mnemonix.key) => Mnemonix.value}, Mnemonix.store} |
  no_return

Takes all entries corresponding to the given keys and removes them from the store into a separate map.

Returns a tuple with the new map and the store updated with removed keys.

If keys contains keys that are not in the store, they’re simply ignored.

Examples

iex> {removed, store} = Mnemonix.split Mnemonix.new(%{a: 1, b: 2, d: 4}), [:a, :b, :c]
iex> removed
%{a: 1, b: 2}
iex> Mnemonix.get(store, :a)
nil
iex> Mnemonix.get(store, :c)
nil
iex> Mnemonix.get(store, :d)
4

iex> {removed, store} = Mnemonix.split Mnemonix.new, [:a, :b, :c]
iex> removed
%{}

take(store, keys)

take(Mnemonix.store, Enumerable.t) ::
  %{optional(Mnemonix.key) => Mnemonix.value} |
  no_return

Returns a map of all key/value pairs in store where the key is in keys.

If keys contains keys that are not in the store, they’re simply ignored.

Examples

iex> Mnemonix.take Mnemonix.new(%{a: 1, b: 2, d: 4}), [:a, :b, :c]
%{a: 1, b: 2}

iex> Mnemonix.take Mnemonix.new, [:a, :b, :c]
%{}

update(store, key, initial, fun)

update(Mnemonix.store, Mnemonix.key, Mnemonix.value, (Mnemonix.value -> Mnemonix.value)) :: Mnemonix.store

Updates the key in store with the given function.

If the key does not exist, inserts the given initial value.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.update(store, :a, 13, &(&1 * 2))
iex> Mnemonix.get(store, :a)
2
iex> Mnemonix.update(store, :b, 13, &(&1 * 2))
iex> Mnemonix.get(store, :b)
13

update!(store, key, fun)

update!(Mnemonix.store, Mnemonix.key, (Mnemonix.value -> Mnemonix.value)) ::
  Mnemonix.store |
  no_return

Updates the key with the given function.

If the key does not exist, raises KeyError.

Examples

iex> store = Mnemonix.new(%{a: 1})
iex> Mnemonix.update!(store, :a, &(&1 * 2))
iex> Mnemonix.get(store, :a)
2
iex> Mnemonix.update!(store, :b, &(&1 * 2))
** (KeyError) key :b not found in: Mnemonix.Stores.Map