Mnemonix v0.5.0 Mnemonix.Features.Map

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

Summary

Functions

Removes the entry under key in store

Retrievs the value of the entry under key in store

Fetches the value for specific key

Gets the value for a specific key

Gets the value for a specific key with default

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

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

Gets the value for a specific key

Returns whether a given key exists in the given store

Returns and removes the value associated with key in store

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

Lazily returns and removes the value associated with key in store

Creates a new entry for value under key in store

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

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

Updates the key in store with the given function

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
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)

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)

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

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)

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)

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)

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)

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
update(store, key, initial, fun)

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)

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