SortedMap (ordered_collections v0.1.0)

A sorted key-value store implemented using Erlang's :gb_trees (Red-Black Trees).

This module stores items in sorted order by their keys.

Summary

Functions

Deletes a key.

Retrieves a value by key, returning a default if missing.

Checks if a key exists.

Returns the largest key. Returns :none if the map is empty.

Returns the smallest key. Returns :none if the map is empty.

Creates a new empty sorted map.

Creates a new sorted map from a standard map.

Inserts a key-value pair, maintaining order.

Iterates over a range of keys, returning key-value pairs whose keys are between min and max (inclusive).

Returns all key-value pairs in sorted order.

Converts the SortedMap into a standard Map, losing the sorted property.

Updates a key if it exists, otherwise sets a default value.

Types

t()

@opaque t()

Functions

delete(map, key)

@spec delete(t(), any()) :: t()

Deletes a key.

Examples

iex> sm = SortedMap.new(%{a: 1, b: 2})
iex> sm2 = SortedMap.delete(sm, :b)
iex> SortedMap.has_key?(sm2, :b)
false

get(sorted_map, key, default \\ nil)

@spec get(t(), any(), any()) :: any()

Retrieves a value by key, returning a default if missing.

Examples

iex> sm = SortedMap.new(%{a: 1})
iex> SortedMap.get(sm, :a)
1
iex> SortedMap.get(sm, :b, :default)
:default

has_key?(sorted_map, key)

@spec has_key?(t(), any()) :: boolean()

Checks if a key exists.

Examples

iex> sm = SortedMap.new(%{a: 1, b: 2})
iex> SortedMap.has_key?(sm, :a)
true
iex> SortedMap.has_key?(sm, :c)
false

max_key(sorted_map)

@spec max_key(t()) :: any()

Returns the largest key. Returns :none if the map is empty.

Examples

iex> sm = SortedMap.new(%{b: 2, a: 1, c: 3})
iex> SortedMap.max_key(sm)
:c

iex> sm_empty = SortedMap.new()
iex> SortedMap.max_key(sm_empty)
:none

min_key(sorted_map)

@spec min_key(t()) :: any()

Returns the smallest key. Returns :none if the map is empty.

Examples

iex> sm = SortedMap.new(%{b: 2, a: 1, c: 3})
iex> SortedMap.min_key(sm)
:a

iex> sm_empty = SortedMap.new()
iex> SortedMap.min_key(sm_empty)
:none

new()

@spec new() :: t()

Creates a new empty sorted map.

Examples

iex> sm = SortedMap.new()
iex> SortedMap.to_map(sm)
%{}

new(map)

@spec new(map()) :: t()

Creates a new sorted map from a standard map.

Examples

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

put(map, key, value)

@spec put(t(), any(), any()) :: t()

Inserts a key-value pair, maintaining order.

Examples

iex> sm = SortedMap.new(%{a: 1})
iex> sm = SortedMap.put(sm, :b, 2)
iex> SortedMap.get(sm, :b)
2

range(sorted_map, min, max)

@spec range(t(), any(), any()) :: [{any(), any()}]

Iterates over a range of keys, returning key-value pairs whose keys are between min and max (inclusive).

Examples

iex> sm = SortedMap.new(%{a: 1, b: 2, c: 3, d: 4})
iex> SortedMap.range(sm, :b, :c)
[{:b, 2}, {:c, 3}]

to_list(sorted_map)

@spec to_list(t()) :: [{any(), any()}]

Returns all key-value pairs in sorted order.

Examples

iex> sm = SortedMap.new(%{b: 2, a: 1})
iex> SortedMap.to_list(sm)
[{:a, 1}, {:b, 2}]

to_map(sorted_map)

@spec to_map(t()) :: map()

Converts the SortedMap into a standard Map, losing the sorted property.

Examples

iex> sm = SortedMap.new(%{b: 2, a: 1})
iex> SortedMap.to_map(sm)
%{a: 1, b: 2}

update(map, key, fun, default \\ nil)

@spec update(t(), any(), (any() -> any()), any()) :: t()

Updates a key if it exists, otherwise sets a default value.

Examples

iex> sm = SortedMap.new(%{a: 1})
iex> SortedMap.update(sm, :a, fn val -> val + 1 end) |> SortedMap.get(:a)
2

iex> SortedMap.new(%{a: 1}) |> SortedMap.update(:b, fn val -> val + 1 end, 10) |> SortedMap.get(:b)
10