vebmap v0.1.0 Vebmap View Source

Documentation for Vebmap. Vebmap combines the RS-vEB data structure and the map together, providing nearly all of the interfaces in the Map module and supporting the predecessor and successor access. Now it also support the protocols of Collectable, Inspect and Enumerable.

To get the size of a vebmap, please use Enum.count/1:

iex> [{0, 0}, {1, 1}, {2, 2}] |> Vebmap.from_enum() |> Enum.count()
3

Here is an example of how a vebmap is inspected:

iex> [{0, 0}, {1, 1}, {2, 2}] |> Vebmap.from_enum()
#Vebmap<[capacity = 4, elements = [{0, 0}, {1, 1}, {2, 2}]]>

As you can see, when inspecting a vebmap, you will get the capacity and the pairs of keys and values. Note that in a vebmap, the keys must be non_neg_integers and the order of the elements is determined by the keys in the order of integers rather than the hash values of the keys in maps.

Link to this section Summary

Types

As it is said in the moduledoc, the keys are non_neg_integers

t()

Vebmap.t() is the type of vebmap

Functions

Vebmap.delete/2 will help you delete the provided key and its value from a vebmap

Drops the given value from a vebmap:

iex> [{0, 0}, {1, 1}] |> Vebmap.from_enum() |> Vebmap.drop([0])
#Vebmap<[capacity = 2, elements = [{1, 1}]]>

Check if tow given vebmap are the same one

Fetches the value for a specific key in the given vebmap, erroring out if vebmap doesn’t contain key. If vebmap contains the given key, the corresponding value is returned. If vebmap doesn’t contain key, a KeyError exception is raised

Invoked in order to access the value stored under key in the given term term

Construct a new vebmap from an enumerable. Four mode provided, :auto will automatically detect the largest key and determine the capacity. :by_max, by_u and by_logu functions the same as in Vebmap.new/2

Gets the value for a specific key in vebmap. If key is present in vebmap with value value, then value is returned. Otherwise, default is returned (which is nil unless specified otherwise)

Gets the value from key and updates it. Raises if there is no key. Behaves exactly like get_and_update/3, but raises a KeyError exception if key is not present in vebmap

Invoked in order to access the value under key and update it at the same time

Gets the value for a specific key in vebmap. If key is present in vebmap with value value, then value is returned. Otherwise, fun is evaluated and its result is returned. This is useful if the default value is very expensive to calculate or generally difficult to setup and teardown again

Returns whether the given key exists in the given vebmap

Returns all keys from map

Merges two vebmaps into one

Merges two vebmaps into one, resolving conflicts through the given fun

Vebmap.new/2 provides a way to get a grand new vebmap. The two arguments determines the capacity of the new vebmap.There are three modes: :by_max, :by_u and :by_logu and by_max is set as the default mode. When using :by_max, the limit argument should pass the maximum value of your keys, and the program will automatically determines the least adequate capacity. As for :by_u, you should provide an nth power of 2 in the limit field which is going to be your capacity. And if you use :by_logu, please pass the maximum number of the binary bits of all your keys

Link to this section Types

As it is said in the moduledoc, the keys are non_neg_integers.

Link to this type t() View Source
t() :: %Vebmap{map: %{optional(key()) => value()}, veb: Veb.t()}

Vebmap.t() is the type of vebmap.

Link to this section Functions

Link to this function capacity(vebmap) View Source
capacity(t()) :: non_neg_integer()
Link to this function delete(vebmap, key) View Source
delete(t(), key()) :: t()

Vebmap.delete/2 will help you delete the provided key and its value from a vebmap:

iex> [{0, 0}, {1, 1}] |> Vebmap.from_enum() |> Vebmap.delete(0)
#Vebmap<[capacity = 2, elements = [{1, 1}]]>
iex> [{0, 0}, {1, 1}] |> Vebmap.from_enum() |> Vebmap.delete(2)
#Vebmap<[capacity = 2, elements = [{0, 0}, {1, 1}]]>
Link to this function drop(vebmap, list) View Source
drop(t(), [key()]) :: t()

Drops the given value from a vebmap:

iex> [{0, 0}, {1, 1}] |> Vebmap.from_enum() |> Vebmap.drop([0])
#Vebmap<[capacity = 2, elements = [{1, 1}]]>
Link to this function equal?(vebmap1, vebmap2) View Source
equal?(t(), t()) :: boolean()

Check if tow given vebmap are the same one.

iex> [{0, 0}, {1, 1}] |> Vebmap.from_enum() |> Vebmap.drop([0])
#Vebmap<[capacity = 2, elements = [{1, 1}]]>
iex> a = [{0, 0}, {1, 1}] |> Vebmap.from_enum()
#Vebmap<[capacity = 2, elements = [{0, 0}, {1, 1}]]>
iex> b = [{0, 0}, {1, 2}] |> Vebmap.from_enum()
#Vebmap<[capacity = 2, elements = [{0, 0}, {1, 2}]]>
iex> Vebmap.equal?(a, a)
true
iex> Vebmap.equal?(a, b)
false
Link to this function fetch!(vebmap, key) View Source
fetch!(t(), key()) :: value() | no_return()

Fetches the value for a specific key in the given vebmap, erroring out if vebmap doesn’t contain key. If vebmap contains the given key, the corresponding value is returned. If vebmap doesn’t contain key, a KeyError exception is raised.

Link to this function fetch(vebmap, key) View Source
fetch(t(), key()) :: {:ok, value()} | :error

Invoked in order to access the value stored under key in the given term term.

This function should return {:ok, value} where value is the value under key if the key exists in the term, or :error if the key does not exist in the term.

Many of the functions defined in the Access module internally call this function. This function is also used when the square-brackets access syntax (structure[key]) is used: the fetch/2 callback implemented by the module that defines the structure struct is invoked and if it returns {:ok, value} then value is returned, or if it returns :error then nil is returned.

See the Map.fetch/2 and Keyword.fetch/2 implementations for examples of how to implement this callback.

Callback implementation for Access.fetch/2.

Link to this function from_enum(enumerable, limit \\ 2147483647, mode \\ :auto) View Source
from_enum(Enumerable.t(), non_neg_integer(), :auto | :by_max | :by_u | :by_logu) ::
  t()

Construct a new vebmap from an enumerable. Four mode provided, :auto will automatically detect the largest key and determine the capacity. :by_max, by_u and by_logu functions the same as in Vebmap.new/2

Link to this function get(vebmap, key, default \\ nil) View Source
get(t(), key(), value()) :: value()

Gets the value for a specific key in vebmap. If key is present in vebmap with value value, then value is returned. Otherwise, default is returned (which is nil unless specified otherwise).

Link to this function get_and_update!(vebmap, key, fun) View Source
get_and_update!(t(), key(), (value() -> {get, value()} | :pop)) ::
  {get, t()} | no_return()
when get: term()

Gets the value from key and updates it. Raises if there is no key. Behaves exactly like get_and_update/3, but raises a KeyError exception if key is not present in vebmap.

Link to this function get_and_update(vebmap, key, fun) View Source
get_and_update(t(), key(), (value() -> {get, value()} | :pop)) ::
  {t(), map()}
when get: term()

Invoked in order to access the value under key and update it at the same time.

The implementation of this callback should invoke fun with the value under key in the passed structure data, or with nil if key is not present in it. This function must return either {get_value, update_value} or :pop.

If the passed function returns {get_value, update_value}, the return value of this callback should be {get_value, new_data}, where:

  • get_value is the retrieved value (which can be operated on before being returned)

  • update_value is the new value to be stored under key

  • new_data is data after updating the value of key with update_value.

If the passed function returns :pop, the return value of this callback must be {value, new_data} where value is the value under key (or nil if not present) and new_data is data without key.

See the implementations of Map.get_and_update/3 or Keyword.get_and_update/3 for more examples.

Callback implementation for Access.get_and_update/3.

Link to this function get_lazy(vebmap, key, fun) View Source
get_lazy(t(), key(), (() -> value())) :: value()

Gets the value for a specific key in vebmap. If key is present in vebmap with value value, then value is returned. Otherwise, fun is evaluated and its result is returned. This is useful if the default value is very expensive to calculate or generally difficult to setup and teardown again.

Link to this function has_key?(vebmap, key) View Source
has_key?(t(), key()) :: boolean()

Returns whether the given key exists in the given vebmap.

Link to this function keys(vebmap) View Source
keys(t()) :: [key()]

Returns all keys from map.

Link to this function max_key(vebmap) View Source
max_key(t()) :: key()
Link to this function max_limit(vebmap) View Source
max_limit(t()) :: non_neg_integer()
Link to this function merge(vebmap1, vebmap2) View Source
merge(t(), t()) :: t()

Merges two vebmaps into one.

All keys in vebmap2 will be added to vebmap1, overriding any existing one (i.e., the keys in vebmap2 “have precedence” over the ones in vebmap1).

Note that if you merge two vebmaps woth different capacities then the returned vebmap will have the larger capacity.

Link to this function merge(vebmap1, vebmap2, fun) View Source
merge(t(), t(), (key(), value(), value() -> value())) :: t()

Merges two vebmaps into one, resolving conflicts through the given fun.

All keys in vebmap2 will be added to vebmap1. The given function will be invoked when there are duplicate keys; its arguments are key (the duplicate key), value1 (the value of key in vebmap1), and value2 (the value of key in vebmap2). The value returned by fun is used as the value under key in the resulting vebmap. Note that if you merge two vebmaps woth different capacities then the returned vebmap will have the larger capacity.

Link to this function min_key(vebmap) View Source
min_key(t()) :: key()
Link to this function new(limit, mode \\ :by_max) View Source
new(non_neg_integer(), :by_max | :by_u | :by_logu) :: t()

Vebmap.new/2 provides a way to get a grand new vebmap. The two arguments determines the capacity of the new vebmap.There are three modes: :by_max, :by_u and :by_logu and by_max is set as the default mode. When using :by_max, the limit argument should pass the maximum value of your keys, and the program will automatically determines the least adequate capacity. As for :by_u, you should provide an nth power of 2 in the limit field which is going to be your capacity. And if you use :by_logu, please pass the maximum number of the binary bits of all your keys.

Here are the examples:

iex> Vebmap.new(3)
#Vebmap<[capacity = 4, elements = []]>
iex> Vebmap.new(8, :by_u)
#Vebmap<[capacity = 8, elements = []]>
iex> Vebmap.new(5, :by_logu)
#Vebmap<[capacity = 32, elements = []]>
Link to this function pop(vebmap, key, default \\ nil) View Source
pop(t(), key(), value()) :: {value(), t()}
Link to this function pop_lazy(vebmap, key, fun) View Source
pop_lazy(t(), key(), (() -> value())) :: {value(), t()}
Link to this function pred_key(vebmap, key) View Source
pred_key(t(), key()) :: key()
Link to this function put(vebmap, key, value) View Source
put(t(), key(), value()) :: t() | :error
Link to this function put_new(vebmap, key, value) View Source
put_new(t(), key(), value()) :: t()
Link to this function put_new_lazy(vebmap, key, fun) View Source
put_new_lazy(t(), key(), (() -> value())) :: t()
Link to this function replace!(vebmap, key, value) View Source
replace!(t(), key(), value()) :: t() | no_return()
Link to this function replace(vebmap, key, value) View Source
replace(t(), key(), value()) :: t()
Link to this function slice(vebmap, start, nums) View Source
slice(t(), non_neg_integer(), non_neg_integer()) :: t()
Link to this function split(vebmap, keys) View Source
split(t(), [key()]) :: t()
Link to this function succ_key(vebmap, key) View Source
succ_key(t(), key()) :: key()
Link to this function take(vebmap, keys) View Source
take(t(), [key()]) :: t()
Link to this function to_list(vebmap) View Source
to_list(t()) :: [{key(), value()}]
Link to this function to_map(vebmap) View Source
to_map(t()) :: %{optional(key()) => value()}
Link to this function update!(vebmap, key, fun) View Source
Link to this function update(vebmap, key, initial, fun) View Source
update(t(), key(), value(), (value() -> value())) :: t()
update(t(), key(), value(), (value() -> value())) :: t() | no_return()
Link to this function upgrade_capacity(vebmap, new_limit) View Source
upgrade_capacity(t(), non_neg_integer()) :: t() | :error
Link to this function values(vebmap) View Source
values(t()) :: [value()]