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
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.
Vebmap.t()
is the type of vebmap.
Link to this section Functions
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}]]>
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.
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
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
.
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
.
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
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.
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 underkey
new_data
isdata
after updating the value ofkey
withupdate_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
.
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.
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.
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.
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 = []]>
slice(t(), non_neg_integer(), non_neg_integer()) :: t()
upgrade_capacity(t(), non_neg_integer()) :: t() | :error