GitHub

API reference for HashMap.

class HashMap[K = Unsubscripted, V = Unsubscripted]

Build one with HashMap.empty(), HashMap.make(*entries) or HashMap.from_iterable(entries).

Functions

__init__

__init__(root=None, size=0) -> None
ParameterTypeDescription
rootNode | None = None
sizeint = 0
def __init__(self, root: Node | None = None, size: int = 0) -> None:
    self._root = root
    self._size = size
    self._mutable = False

empty

empty() -> HashMap[K, V]

Spelled HashMap[str, int].empty().

Returns HashMap[K, V]

@classmethod
def empty(cls) -> HashMap[K, V]:
    """Spelled ``HashMap[str, int].empty()``."""
    return HashMap()

make

make[K2, V2](*entries: tuple[K2, V2] = ()) -> HashMap[K2, V2]
make[K2, V2](*entries: tuple[K2, V2] = ()) -> HashMap[K2, V2]
ParameterTypeDescription
entries= ()
@overload
@classmethod
def make[K2, V2](
    cls: type[HashMap[Unsubscripted, Unsubscripted]], *entries: tuple[K2, V2]
) -> HashMap[K2, V2]: ...
@overload
@classmethod
def make[K2, V2](cls: type[HashMap[K2, V2]], *entries: tuple[K2, V2]) -> HashMap[K2, V2]: ...
@classmethod
def make[K2, V2](cls, *entries: tuple[K2, V2]) -> HashMap[K2, V2]:
    return HashMap.from_iterable(entries)

from_iterable

from_iterable[K2, V2](entries: list[tuple[K2, V2]]) -> HashMap[K2, V2]
from_iterable[K2, V2](entries: Iterable[tuple[K2, V2]]) -> HashMap[K2, V2]
from_iterable[K2, V2](entries: Iterable[tuple[K2, V2]]) -> HashMap[K2, V2]

The map of entries; a later value for an equal key wins, and the first key is kept.

ParameterTypeDescription
entries
@overload
@classmethod
def from_iterable[K2, V2](
    cls: type[HashMap[Unsubscripted, Unsubscripted]], entries: list[tuple[K2, V2]]
) -> HashMap[K2, V2]: ...
@overload
@classmethod
def from_iterable[K2, V2](
    cls: type[HashMap[Unsubscripted, Unsubscripted]], entries: Iterable[tuple[K2, V2]]
) -> HashMap[K2, V2]: ...
@overload
@classmethod
def from_iterable[K2, V2](
    cls: type[HashMap[K2, V2]], entries: Iterable[tuple[K2, V2]]
) -> HashMap[K2, V2]: ...
@classmethod
def from_iterable[K2, V2](cls, entries: Iterable[tuple[K2, V2]]) -> HashMap[K2, V2]:
    """The map of ``entries``; a later value for an equal key wins, and
    the first key is kept."""
    return HashMap[K2, V2]().set_many(entries)

is_empty

is_empty() -> bool

Returns bool

def is_empty(self) -> bool:
    return self._size == 0

get

get(key) -> Option[V]

Some(value) for key, or None.

ParameterTypeDescription
keyobject

Returns Option[V]

def get(self, key: object) -> Option[V]:
    """``Some(value)`` for ``key``, or ``None``."""
    found = self._find(key)
    return None if found is None else Some(found.value)

get_hash

get_hash(key, hash) -> Option[V]
ParameterTypeDescription
keyobject
hashint

Returns Option[V]

def get_hash(self, key: object, hash: int) -> Option[V]:
    return self.get(key)

get_unsafe

get_unsafe(key) -> V

The value for key; raises KeyError without one.

ParameterTypeDescription
keyobject

Returns V

def get_unsafe(self, key: object) -> V:
    """The value for ``key``; raises ``KeyError`` without one."""
    found = self._find(key)
    if found is None:
        raise KeyError("HashMap.getUnsafe: key not found")
    return found.value

has

has(key) -> bool
ParameterTypeDescription
keyobject

Returns bool

def has(self, key: object) -> bool:
    return self._find(key) is not None

has_hash

has_hash(key, hash) -> bool
ParameterTypeDescription
keyobject
hashint

Returns bool

def has_hash(self, key: object, hash: int) -> bool:
    return self.has(key)

has_by

has_by(predicate) -> bool

Whether an entry satisfies predicate(value, key).

ParameterTypeDescription
predicateCallable[[V, K], bool]

Returns bool

def has_by(self, predicate: Callable[[V, K], bool]) -> bool:
    """Whether an entry satisfies ``predicate(value, key)``."""
    return any(predicate(e.value, e.key) for e in self._entries())

keys

keys() -> Iterator[K]

Returns Iterator[K]

def keys(self) -> Iterator[K]:
    return (e.key for e in self._entries())

values

values() -> Iterator[V]

Returns Iterator[V]

def values(self) -> Iterator[V]:
    return (e.value for e in self._entries())

to_values

to_values[V2]() -> list[V2]

Returns list[V2]

def to_values[V2](self: HashMap[Any, V2]) -> list[V2]:
    return list(self.values())

entries

entries() -> Iterator[tuple[K, V]]

Returns Iterator[tuple[K, V]]

def entries(self) -> Iterator[tuple[K, V]]:
    return iter(self)

to_entries

to_entries[K2, V2]() -> list[tuple[K2, V2]]

Returns list[tuple[K2, V2]]

def to_entries[K2, V2](self: HashMap[K2, V2]) -> list[tuple[K2, V2]]:
    return list(self)

find_first

find_first(predicate) -> Option[tuple[K, V]]

The first entry satisfying predicate(value, key).

ParameterTypeDescription
predicateCallable[[V, K], bool]

Returns Option[tuple[K, V]]

def find_first(self, predicate: Callable[[V, K], bool]) -> Option[tuple[K, V]]:
    """The first entry satisfying ``predicate(value, key)``."""
    for e in self._entries():
        if predicate(e.value, e.key):
            return Some((e.key, e.value))
    return None

some

some(predicate) -> bool
ParameterTypeDescription
predicateCallable[[V, K], bool]

Returns bool

def some(self, predicate: Callable[[V, K], bool]) -> bool:
    return self.has_by(predicate)

every

every(predicate) -> bool
ParameterTypeDescription
predicateCallable[[V, K], bool]

Returns bool

def every(self, predicate: Callable[[V, K], bool]) -> bool:
    return all(predicate(e.value, e.key) for e in self._entries())

reduce

reduce[Z](zero, f) -> Z
ParameterTypeDescription
zeroZ
fCallable[[Z, V, K], Z]

Returns Z

def reduce[Z](self, zero: Z, f: Callable[[Z, V, K], Z]) -> Z:
    out = zero
    for e in self._entries():
        out = f(out, e.value, e.key)
    return out

for_each

for_each(f) -> None
ParameterTypeDescription
fCallable[[V, K], object]
def for_each(self, f: Callable[[V, K], object]) -> None:
    for e in self._entries():
        f(e.value, e.key)

set

set[K2, V2](key, value) -> HashMap[K2, V2]

The map with key set to value; the same map when key already holds this value (Object.is: pyfect._js.same_value). An equal key already there is kept.

ParameterTypeDescription
keyK2
valueV2

Returns HashMap[K2, V2]

def set[K2, V2](self: HashMap[K2, V2], key: K2, value: V2) -> HashMap[K2, V2]:
    """The map with ``key`` set to ``value``; the same map when ``key``
    already holds this value (``Object.is``: ``pyfect._js.same_value``).
    An equal key already there is kept."""
    ident = equal_key(key)
    hash = _hamt.hash_of(ident)
    added = _hamt.find(self._root, hash, ident) is None
    root = _hamt.insert(self._root, Entry(hash, ident, key, value))
    return self._with(root, self._size + added)

set_many

set_many[K2, V2](entries) -> HashMap[K2, V2]
ParameterTypeDescription
entriesIterable[tuple[K2, V2]]

Returns HashMap[K2, V2]

def set_many[K2, V2](
    self: HashMap[K2, V2], entries: Iterable[tuple[K2, V2]]
) -> HashMap[K2, V2]:
    root, size = self._root, self._size
    for key, value in entries:
        ident = equal_key(key)
        hash = _hamt.hash_of(ident)
        size += _hamt.find(root, hash, ident) is None
        root = _hamt.insert(root, Entry(hash, ident, key, value))
    return self._with(root, size)

remove

remove[K2, V2](key) -> HashMap[K2, V2]

The map without key; the same map when it has no key.

ParameterTypeDescription
keyK2

Returns HashMap[K2, V2]

def remove[K2, V2](self: HashMap[K2, V2], key: K2) -> HashMap[K2, V2]:
    """The map without ``key``; the same map when it has no ``key``."""
    return self.remove_many((key,))

remove_many

remove_many[K2, V2](keys) -> HashMap[K2, V2]
ParameterTypeDescription
keysIterable[K2]

Returns HashMap[K2, V2]

def remove_many[K2, V2](self: HashMap[K2, V2], keys: Iterable[K2]) -> HashMap[K2, V2]:
    root, size = self._root, self._size
    for key in keys:
        ident = equal_key(key)
        smaller = _hamt.remove(root, _hamt.hash_of(ident), ident)
        size -= smaller is not root
        root = smaller
    return self._with(root, size)

modify_at

modify_at[K2, V2](key, f) -> HashMap[K2, V2]

Set, keep or remove key by what f makes of its current value: Some(new) sets it, None removes it.

ParameterTypeDescription
keyK2
fCallable[[Option[V2]], Option[V2]]

Returns HashMap[K2, V2]

def modify_at[K2, V2](
    self: HashMap[K2, V2], key: K2, f: Callable[[Option[V2]], Option[V2]]
) -> HashMap[K2, V2]:
    """Set, keep or remove ``key`` by what ``f`` makes of its current
    value: ``Some(new)`` sets it, ``None`` removes it."""
    match f(self.get(key)):
        case Some(value):
            return self.set(key, value)
        case None:
            return self.remove(key)

modify_hash

modify_hash[K2, V2](key, hash, f) -> HashMap[K2, V2]
ParameterTypeDescription
keyK2
hashint
fCallable[[Option[V2]], Option[V2]]

Returns HashMap[K2, V2]

def modify_hash[K2, V2](
    self: HashMap[K2, V2], key: K2, hash: int, f: Callable[[Option[V2]], Option[V2]]
) -> HashMap[K2, V2]:
    return self.modify_at(key, f)

modify

modify[K2, V2](key, f) -> HashMap[K2, V2]

The map with key's value replaced by f(value); the same map without key.

ParameterTypeDescription
keyK2
fCallable[[V2], V2]

Returns HashMap[K2, V2]

def modify[K2, V2](self: HashMap[K2, V2], key: K2, f: Callable[[V2], V2]) -> HashMap[K2, V2]:
    """The map with ``key``'s value replaced by ``f(value)``; the same
    map without ``key``."""
    found = self._find(key)
    return self if found is None else self.set(found.key, f(found.value))

union

union[K1, V1](that) -> HashMap[K | K1, V | V1]

Both maps' entries; that's value wins for an equal key.

ParameterTypeDescription
thatHashMap[K1, V1]

Returns HashMap[K | K1, V | V1]

def union[K1, V1](self, that: HashMap[K1, V1]) -> HashMap[K | K1, V | V1]:
    """Both maps' entries; ``that``'s value wins for an equal key."""
    return HashMap[K | K1, V | V1](self._root, self._size).set_many(that)

map

map[A](f) -> HashMap[K, A]
ParameterTypeDescription
fCallable[[V, K], A]

Returns HashMap[K, A]

def map[A](self, f: Callable[[V, K], A]) -> HashMap[K, A]:
    return self._rebuilt((e.key, f(e.value, e.key)) for e in list(self._entries()))

flat_map

flat_map[K2, V2, A](f) -> HashMap[K2, A]

The union of f(value, key) for every entry.

ParameterTypeDescription
fCallable[[V2, K2], HashMap[K2, A]]

Returns HashMap[K2, A]

def flat_map[K2, V2, A](
    self: HashMap[K2, V2], f: Callable[[V2, K2], HashMap[K2, A]]
) -> HashMap[K2, A]:
    """The union of ``f(value, key)`` for every entry."""
    return self._rebuilt(pair for e in list(self._entries()) for pair in f(e.value, e.key))

filter

filter[B](predicate: Callable[[V, K], TypeIs[B]]) -> HashMap[K, B]
filter(predicate: Callable[[V, K], bool]) -> HashMap[K, V]
ParameterTypeDescription
predicate
@overload
def filter[B](self, predicate: Callable[[V, K], TypeIs[B]]) -> HashMap[K, B]: ...
@overload
def filter(self, predicate: Callable[[V, K], bool]) -> HashMap[K, V]: ...
def filter(self, predicate: Callable[[V, K], bool]) -> HashMap[K, Any]:
    return self._rebuilt((e.key, e.value) for e in self._entries() if predicate(e.value, e.key))

filter_map

filter_map[A](f) -> HashMap[K, A]

The entries f(value, key) keeps (Ok), with its values.

ParameterTypeDescription
fCallable[[V, K], Result[A, object]]

Returns HashMap[K, A]

def filter_map[A](self, f: Callable[[V, K], Result[A, object]]) -> HashMap[K, A]:
    """The entries ``f(value, key)`` keeps (``Ok``), with its values."""

    def kept() -> Iterator[tuple[K, A]]:
        for e in self._entries():
            result = f(e.value, e.key)
            if isinstance(result, Ok):
                yield e.key, result.value

    return self._rebuilt(kept())

compact

compact[A]() -> HashMap[K, A]

The Some values, unwrapped.

Returns HashMap[K, A]

def compact[A](self: HashMap[K, Option[A]]) -> HashMap[K, A]:
    """The ``Some`` values, unwrapped."""
    return self._rebuilt(
        (e.key, e.value.value) for e in self._entries() if isinstance(e.value, Some)
    )

begin_mutation

begin_mutation() -> HashMap[K, V]

A copy whose set / remove / ... update it in place (and return it) until end_mutation.

Returns HashMap[K, V]

def begin_mutation(self) -> HashMap[K, V]:
    """A copy whose ``set`` / ``remove`` / ... update it in place (and
    return it) until ``end_mutation``."""
    out = HashMap[K, V](self._root, self._size)
    out._mutable = True
    return out

end_mutation

end_mutation() -> HashMap[K, V]

Freeze a map from begin_mutation; returns the same map.

Returns HashMap[K, V]

def end_mutation(self) -> HashMap[K, V]:
    """Freeze a map from ``begin_mutation``; returns the same map."""
    self._mutable = False
    return self

mutate

mutate(f) -> HashMap[K, V]

A new map: a mutable copy of this one after f has updated it.

ParameterTypeDescription
fCallable[[HashMap[K, V]], object]

Returns HashMap[K, V]

def mutate(self, f: Callable[[HashMap[K, V]], object]) -> HashMap[K, V]:
    """A new map: a mutable copy of this one after ``f`` has updated it."""
    draft = self.begin_mutation()
    f(draft)
    return draft.end_mutation()