Skip to content

BaseDict[S @ {...}]

The read-only half of a Dict, whose items it holds covariantly: a Dict[{a: Int}] is a BaseDict[{a: (Int | Str)}]. A parameter that only reads a dict takes a BaseDict, so it accepts dicts with narrower items.

BaseDict is Dict at runtime, so only a dict is a BaseDict.

Inherits from: Iterable[Entries[S]]

Implements: Map[S], Index[S], Spread[S]

Fields

len @ Int [get]

Returns the number of key-value pairs (counting each value in a multi-map separately).

Methods

(index)[K] key -> IndexItem[S, K]

Returns the value of a key, the last one if it is repeated.

let d = {name: "Alice"}
assert_eq $d[:name:] "Alice"

A missing key raises IndexError.

Range values are treated as ordinary keys, not as slices.

Parameters

NameTypeDescription
key K

(iter)() -> Iter[Entries[S]]

Iterating over a dictionary yields (key, value) pairs:

for pair = {a: 1, b: 2}
  echo $pair

(spread)() -> Spread[S]

Spreads the dictionary's entries.

(unpack)() -> BaseDict[S]

Destructures the dictionary by key.

let :name age: years = {name: "Alice", age: 30}

contains key … -> Bool

Tests whether the dictionary contains the given key. If a value is provided, tests whether any value associated with that key matches the given value (multi-map aware).

Parameters

NameTypeDescription
key Value the key to check
value? Value optional value to check for (multi-map)

Example

let d = {a: 1, b: 2}
d.insert :a: 3

# Key-only check. A bareword key is a `Sym`, so `"a"` would not match it.
assert (d.contains :a:)
assert (!d.contains :z:)

# Key + value check (multi-map aware)
assert (d.contains :a: 1)
assert (d.contains :a: 3)
assert (!d.contains :a: 2)
Open in playground

copy() -> BaseDict[S]

Returns a shallow copy of the dictionary.

Insertion order and multiple per-key values are preserved. Keys and values are not copied recursively.

When inherited by a Do subclass, copy() calls the subclass constructor with the source dict as a single positional argument.

count … -> Int

Returns a count derived from the dictionary's multi-map structure.

With no key, it returns the number of distinct keys. With a key, it returns the number of values associated with that key.

Missing keys return 0.

Parameters

NameTypeDescription
key? Value

get[K, D = nil] key … -> (IndexItem[S, K] | D)

Retrieves the value for a key. Returns nil if the key is missing and no alternative is provided. Negative instance indexes count from the end.

Parameters

NameTypeDescription
key K the key to look up
instance? Int which value to retrieve when a key has multiple values (0-indexed; negative counts from end; default: last)
:default? D
:else? (() -> D)

Example

let d = {name: "Alice"}
assert_eq (d.get :name:) "Alice"
assert_eq ({name: "Alice", name: "Bob"}.get :name: -1) "Bob"
assert_eq (d.get :missing: default: "unknown") "unknown"

keys() -> UnpackIter[Keys[S]]

Returns an iterator of keys. Each distinct key is yielded exactly once, in the order its first pair was inserted.

To visit each value of a repeated key, use pairs instead.

pairs() -> Iter[Entries[S]]

Returns an iterator yielding (key, value) pairs, the same as ordinary iteration, so that a Dict and an Array can be iterated by key and value alike.

values() -> UnpackIter[Values[S]] overload 1 of 2

Returns an iterator of values. With no argument, it yields all stored values in pair insertion order. With a key, it yields only the values associated with that key, in that key's insertion order.

Missing keys return an empty iterator.