GitHub

TxHashMap

API reference for TxHashMap.

class TxHashMap[K = Unsubscripted, V = Unsubscripted]

TxHashMap(ref) wraps an existing TxRef; empty, make and from_iterable are the effects.

Attributes

AttributeTypeDescription
refTxRef[HashMap[K, V]]

Functions

__init__

__init__(ref) -> None
ParameterTypeDescription
refTxRef[HashMap[K, V]]
def __init__(self, ref: TxRef[HashMap[K, V]]) -> None:
    self._ref = ref

empty

empty() -> Effect[TxHashMap[K, V]]

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

Returns Effect[TxHashMap[K, V]]

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

make

make[K2, V2](*entries: tuple[K2, V2] = ()) -> Effect[TxHashMap[K2, V2]]
make(*entries: tuple[K, V] = ()) -> Effect[TxHashMap[K, V]]

TxHashMap[K, V].make(...) takes the subscript; TxHashMap.make infers it from the entries.

ParameterTypeDescription
entries= ()
@overload
@classmethod
def make[K2, V2](
    cls: type[TxHashMap[Unsubscripted, Unsubscripted]], *entries: tuple[K2, V2]
) -> Effect[TxHashMap[K2, V2]]: ...
@overload
@classmethod
def make(cls, *entries: tuple[K, V]) -> Effect[TxHashMap[K, V]]: ...
@classmethod
def make(cls, *entries: tuple[Any, Any]) -> Effect[TxHashMap[Any, Any]]:
    """``TxHashMap[K, V].make(...)`` takes the subscript; ``TxHashMap.make``
    infers it from the entries."""
    return _new(HashMap.from_iterable(entries))

from_iterable

from_iterable[K2, V2](entries: list[tuple[K2, V2]]) -> Effect[TxHashMap[K2, V2]]
from_iterable[K2, V2](entries: Iterable[tuple[K2, V2]]) -> Effect[TxHashMap[K2, V2]]
from_iterable(entries: Iterable[tuple[K, V]]) -> Effect[TxHashMap[K, V]]

A new map each time the effect runs. entries is read once, here, so a one-shot iterator survives transaction retries.

ParameterTypeDescription
entries
@overload
@classmethod
def from_iterable[K2, V2](
    cls: type[TxHashMap[Unsubscripted, Unsubscripted]], entries: list[tuple[K2, V2]]
) -> Effect[TxHashMap[K2, V2]]: ...
@overload
@classmethod
def from_iterable[K2, V2](
    cls: type[TxHashMap[Unsubscripted, Unsubscripted]], entries: Iterable[tuple[K2, V2]]
) -> Effect[TxHashMap[K2, V2]]: ...
@overload
@classmethod
def from_iterable(cls, entries: Iterable[tuple[K, V]]) -> Effect[TxHashMap[K, V]]: ...
@classmethod
def from_iterable(cls, entries: Iterable[tuple[Any, Any]]) -> Effect[TxHashMap[Any, Any]]:
    """A new map each time the effect runs. ``entries`` is read once,
    here, so a one-shot iterator survives transaction retries."""
    return _new(HashMap.from_iterable(entries))

get

get(key) -> Effect[Option[V]]
ParameterTypeDescription
keyK

Returns Effect[Option[V]]

def get(self, key: K) -> Effect[Option[V]]:
    return _tx_ops.read(self._ref, lambda m: m.get(key))

has

has(key) -> Effect[bool]
ParameterTypeDescription
keyK

Returns Effect[bool]

def has(self, key: K) -> Effect[bool]:
    return _tx_ops.read(self._ref, lambda m: m.has(key))

get_hash

get_hash(key, hash) -> Effect[Option[V]]

get, finding nothing unless hash is hash(equal_key(key)).

ParameterTypeDescription
keyK
hashint

Returns Effect[Option[V]]

def get_hash(self, key: K, hash: int) -> Effect[Option[V]]:
    """``get``, finding nothing unless ``hash`` is ``hash(equal_key(key))``."""
    return _tx_ops.read(self._ref, lambda m: m.get(key) if _hash(key) == hash else None)

has_hash

has_hash(key, hash) -> Effect[bool]

has, finding nothing unless hash is hash(equal_key(key)).

ParameterTypeDescription
keyK
hashint

Returns Effect[bool]

def has_hash(self, key: K, hash: int) -> Effect[bool]:
    """``has``, finding nothing unless ``hash`` is ``hash(equal_key(key))``."""
    return _tx_ops.read(self._ref, lambda m: _hash(key) == hash and m.has(key))

size

size() -> Effect[int]

Returns Effect[int]

def size(self) -> Effect[int]:
    return _tx_ops.read(self._ref, len)

is_empty

is_empty() -> Effect[bool]

Returns Effect[bool]

def is_empty(self) -> Effect[bool]:
    return _tx_ops.read(self._ref, HashMap[K, V].is_empty)

is_non_empty

is_non_empty() -> Effect[bool]

Returns Effect[bool]

def is_non_empty(self) -> Effect[bool]:
    return _tx_ops.read(self._ref, bool)

keys

keys() -> Effect[list[K]]

Returns Effect[list[K]]

def keys(self) -> Effect[list[K]]:
    return _tx_ops.read(self._ref, lambda m: list(m.keys()))

values

values() -> Effect[list[V]]

Returns Effect[list[V]]

def values(self) -> Effect[list[V]]:
    return _tx_ops.read(self._ref, HashMap[K, V].to_values)

entries

entries() -> Effect[list[tuple[K, V]]]

Returns Effect[list[tuple[K, V]]]

def entries(self) -> Effect[list[tuple[K, V]]]:
    return _tx_ops.read(self._ref, HashMap[K, V].to_entries)

to_entries

to_entries() -> Effect[list[tuple[K, V]]]

Returns Effect[list[tuple[K, V]]]

def to_entries(self) -> Effect[list[tuple[K, V]]]:
    return self.entries()

to_values

to_values() -> Effect[list[V]]

Returns Effect[list[V]]

def to_values(self) -> Effect[list[V]]:
    return self.values()

snapshot

snapshot() -> Effect[HashMap[K, V]]

The map as it is now; HashMap is immutable, so it never changes.

Returns Effect[HashMap[K, V]]

def snapshot(self) -> Effect[HashMap[K, V]]:
    """The map as it is now; ``HashMap`` is immutable, so it never
    changes."""
    return self._ref.get()

reduce

reduce[A](zero, f) -> Effect[A]
ParameterTypeDescription
zeroA
fCallable[[A, V, K], A]

Returns Effect[A]

def reduce[A](self, zero: A, f: Callable[[A, V, K], A]) -> Effect[A]:
    return _tx_ops.read(self._ref, lambda m: m.reduce(zero, f))

has_by

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

Returns Effect[bool]

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

some

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

Returns Effect[bool]

def some(self, predicate: Callable[[V, K], bool]) -> Effect[bool]:
    return _tx_ops.read(self._ref, lambda m: m.some(predicate))

every

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

Returns Effect[bool]

def every(self, predicate: Callable[[V, K], bool]) -> Effect[bool]:
    return _tx_ops.read(self._ref, lambda m: m.every(predicate))

find_first

find_first(predicate) -> Effect[tuple[K, V] | None]

The first entry, in the map's hash order, satisfying predicate(value, key).

ParameterTypeDescription
predicateCallable[[V, K], bool]

Returns Effect[tuple[K, V] | None]

def find_first(self, predicate: Callable[[V, K], bool]) -> Effect[tuple[K, V] | None]:
    """The first entry, in the map's hash order, satisfying
    ``predicate(value, key)``."""
    return _tx_ops.read(self._ref, lambda m: _value_or_none(m.find_first(predicate)))

for_each

for_each[E = Never, R = Never](f) -> Effect[None, E, R]

Run f on each entry of the map as it was read, in order.

ParameterTypeDescription
fCallable[[V, K], Effect[Any, E, R]]

Returns Effect[None, E, R]

def for_each[E = Never, R = Never](
    self, f: Callable[[V, K], Effect[Any, E, R]]
) -> Effect[None, E, R]:
    """Run ``f`` on each entry of the map as it was read, in order."""
    return (
        self.entries()
        .flat_map(lambda items: for_each(items, lambda entry: f(entry[1], entry[0])))
        .as_void()
    )

set

set(key, value) -> Effect[None]
ParameterTypeDescription
keyK
valueV

Returns Effect[None]

def set(self, key: K, value: V) -> Effect[None]:
    return self._ref.update(lambda m: m.set(key, value))

remove

remove(key) -> Effect[bool]

Remove key; True when it was there.

ParameterTypeDescription
keyK

Returns Effect[bool]

def remove(self, key: K) -> Effect[bool]:
    """Remove ``key``; ``True`` when it was there."""
    return _tx_ops.modify_or_skip(
        self._ref, lambda m: (True, Some(m.remove(key))) if m.has(key) else (False, None)
    )

clear

clear() -> Effect[None]

Returns Effect[None]

def clear(self) -> Effect[None]:
    return self._ref.set(HashMap[K, V].empty())

modify

modify(key, f) -> Effect[Option[V]]

Replace the value at key with f of it; the old value, or None (and no write) when key is absent.

ParameterTypeDescription
keyK
fCallable[[V], V]

Returns Effect[Option[V]]

def modify(self, key: K, f: Callable[[V], V]) -> Effect[Option[V]]:
    """Replace the value at ``key`` with ``f`` of it; the old value, or
    ``None`` (and no write) when ``key`` is absent."""

    def run(m: HashMap[K, V]) -> tuple[Option[V], Option[HashMap[K, V]]]:
        match m.get(key):
            case Some(old):
                return Some(old), Some(m.set(key, f(old)))
            case None:
                return None, None

    return _tx_ops.modify_or_skip(self._ref, run)

modify_at

modify_at(key, f) -> Effect[None]

Set key to what f returns for its current value, or remove it when f returns None.

ParameterTypeDescription
keyK
fCallable[[Option[V]], Option[V]]

Returns Effect[None]

def modify_at(self, key: K, f: Callable[[Option[V]], Option[V]]) -> Effect[None]:
    """Set ``key`` to what ``f`` returns for its current value, or remove
    it when ``f`` returns ``None``."""

    def run(m: HashMap[K, V]) -> tuple[None, Option[HashMap[K, V]]]:
        current = m.get(key)
        match f(current):
            case Some(value):
                return None, Some(m.set(key, value))
            case None:
                return None, None if current is None else Some(m.remove(key))

    return _tx_ops.modify_or_skip(self._ref, run)

union

union(other) -> Effect[None]

Add other's entries, replacing values at shared keys.

ParameterTypeDescription
otherHashMap[K, V]

Returns Effect[None]

def union(self, other: HashMap[K, V]) -> Effect[None]:
    """Add ``other``'s entries, replacing values at shared keys."""
    return self._ref.update(lambda m: m.set_many(other))

set_many

set_many(entries) -> Effect[None]

Set every entry; entries is read once, here.

ParameterTypeDescription
entriesIterable[tuple[K, V]]

Returns Effect[None]

def set_many(self, entries: Iterable[tuple[K, V]]) -> Effect[None]:
    """Set every entry; ``entries`` is read once, here."""
    added = list(entries)
    return self._ref.update(lambda m: m.set_many(added))

remove_many

remove_many(keys) -> Effect[None]

Remove every key; keys is read once, here.

ParameterTypeDescription
keysIterable[K]

Returns Effect[None]

def remove_many(self, keys: Iterable[K]) -> Effect[None]:
    """Remove every key; ``keys`` is read once, here."""
    removed = list(keys)
    return self._ref.update(lambda m: m.remove_many(removed))

map

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

Returns Effect[TxHashMap[K, A]]

def map[A](self, f: Callable[[V, K], A]) -> Effect[TxHashMap[K, A]]:
    return _derive(self, lambda m: m.map(f))

filter

filter[B](predicate: Callable[[V, K], TypeIs[B]]) -> Effect[TxHashMap[K, B]]
filter(predicate: Callable[[V, K], bool]) -> Effect[TxHashMap[K, V]]
ParameterTypeDescription
predicate
@overload
def filter[B](self, predicate: Callable[[V, K], TypeIs[B]]) -> Effect[TxHashMap[K, B]]: ...
@overload
def filter(self, predicate: Callable[[V, K], bool]) -> Effect[TxHashMap[K, V]]: ...
def filter(self, predicate: Callable[[V, K], bool]) -> Effect[TxHashMap[K, Any]]:
    return _derive(self, lambda m: m.filter(predicate))

filter_map

filter_map[A](f) -> Effect[TxHashMap[K, A]]

A new map of the Ok values f gives; Err drops the entry.

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

Returns Effect[TxHashMap[K, A]]

def filter_map[A](self, f: Callable[[V, K], Result[A, object]]) -> Effect[TxHashMap[K, A]]:
    """A new map of the ``Ok`` values ``f`` gives; ``Err`` drops the
    entry."""
    return _derive(self, lambda m: m.filter_map(f))

compact

compact[A]() -> Effect[TxHashMap[K, A]]

A new map of the Some values, unwrapped.

Returns Effect[TxHashMap[K, A]]

def compact[A](self: TxHashMap[K, Option[A]]) -> Effect[TxHashMap[K, A]]:
    """A new map of the ``Some`` values, unwrapped."""
    return _derive(self, HashMap[K, Option[A]].compact)

flat_map

flat_map[A, E = Never, R = Never](f) -> Effect[TxHashMap[K, A], E, R]

A new map of the entries of every map f gives, in one transaction; later entries replace earlier ones.

ParameterTypeDescription
fCallable[[V, K], Effect[TxHashMap[K, A], E, R]]

Returns Effect[TxHashMap[K, A], E, R]

def flat_map[A, E = Never, R = Never](
    self, f: Callable[[V, K], Effect[TxHashMap[K, A], E, R]]
) -> Effect[TxHashMap[K, A], E, R]:
    """A new map of the entries of every map ``f`` gives, in one
    transaction; later entries replace earlier ones."""

    def body():
        source = yield from self.entries()
        out = HashMap[K, A].empty()
        for key, value in source:
            produced = yield from f(value, key)
            out = out.set_many((yield from produced.entries()))
        return TxHashMap(TxRef(out))

    return tx(_Gen(body))