Skip to content
FutureBlitz

    Install

    Import std.collections.immutable

    std.collections.immutable

    Arrays, maps, and sets that never change, so any thread can read them.

    ImmutableArray<T>, ImmutableMap<K, V>, and ImmutableSet<T>: collections that never change, so any thread can read one. A change gives a new collection, which shares all of the old one's nodes but the ones on the way down to what changed, in a balanced tree, about log(Count) of them. Their values are Sendable, as the collections are.

    std/collections/immutable.fb

    Types

    ImmutableArray struct 

    @DebugElements Public Struct ImmutableArray<T: Sendable> Implements Iterable<T>, Defaultable, Sendable

    An array that never changes: each change gives a new one, which shares what it can with the old, so threads can share it.

    Examples

    Local first = ImmutableArray<Int>().AddAll([1, 2, 3])
Local second = first.Set(0, 10).Add(4)
Expect(first.ToArray() == [1, 2, 3])
Expect(second.ToArray() == [10, 2, 3, 4])

    std/collections/immutable.fb, line 41

    • Public New() constructor #

      An empty one.

    • Public Static Method From(values: Iterable<T>): ImmutableArray<T> static method #

      One with the values, in order, all read first.

    • Public Property Count: Int property #

      How many values it holds.

    • @PanicsAtCaller Operator [](index: Int): T operator #

      The value at index, which panics outside it.

    • @PanicsAtCaller Public Method Set(index: Int, value: T): ImmutableArray<T> method #

      A copy with value at index in place of what's there.

    • Public Method Add(value: T): ImmutableArray<T> method #

      A copy with value added at the end.

    • Public Method AddAll(values: Iterable<T>): ImmutableArray<T> method #

      A copy with each of the values added at the end, in order, all read first.

    • @PanicsAtCaller Public Method Insert(index: Int, value: T): ImmutableArray<T> method #

      A copy with value at index, moving what's there and after it along, where index is from 0 to Count.

    • @PanicsAtCaller Public Method RemoveAt(index: Int): ImmutableArray<T> method #

      A copy without the value at index.

    • Public Method Contains(value: T): Bool method #

      Whether it holds value.

    • Public Method ToArray(): T[] method #

      The values, in order, in a new array.

    • Public Static Method DefaultValue(): ImmutableArray<T> static method #

      An empty one.

    • Public Method Iterate(): ImmutableArrayIterator<T> method #

      The values, in order.

    ImmutableArrayIterator struct 

    Public Struct ImmutableArrayIterator<T: Sendable> Implements Iterator<T>

    The values of an ImmutableArray, in order, which a For loop goes over.

    std/collections/immutable.fb, line 258

    • Public ByRef Method Next(): T? method #

      The next value, in order, or Null after the last.

    ImmutableMap struct 

    @DebugEntries Public Struct ImmutableMap<K, V> Implements Iterable<(K, V)>, Defaultable, Sendable

    A Map that never changes: each change gives a new one, which shares what it can with the old, so threads can share it.

    Examples

    Local empty = ImmutableMap<String, Int>()
Local ages = empty.Add("Ada", 36).Add("Alan", 41)
Expect(empty.Count == 0 && ages.Count == 2)
Expect(ages.Get("Ada") == 36)
Expect(!ages.Remove("Ada").Contains("Ada") && ages.Contains("Ada"))

    std/collections/immutable.fb, line 372

    • Public New() constructor #

      An empty one.

    • Public Static Method From(entries: Iterable<(K, V)>): ImmutableMap<K, V> static method #

      One with the entries, all read first, a second entry's value for a key taking the place of an earlier one's.

    • Public Property Count: Int property #

      How many entries it holds.

    • Public Method Get(key: K): V? method #

      The key's value, or Null when it isn't there.

    • Public Method Get(key: K, fallback: V): V method #

      The key's value, or fallback when it isn't there.

    • @PanicsAtCaller Operator [](key: K): V operator #

      The key's value. A key that isn't there panics.

    • Public Method Contains(key: K): Bool method #

      Whether key has an entry.

    • Public Method Add(key: K, value: V): ImmutableMap<K, V> method #

      A copy with the key's value, which takes the place of the one it has.

    • Public Method AddAll(entries: Iterable<(K, V)>): ImmutableMap<K, V> method #

      A copy with each of the entries added in turn, as Add adds one, all read first.

    • Public Method Remove(key: K): ImmutableMap<K, V> method #

      A copy without the key's entry, or the same one when it has none.

    • Public Method Keys(): K[] method #

      The keys, in the order the entries go in.

    • Public Method Values(): V[] method #

      The values, in their keys' order.

    • Public Method ToMap(): Map<K, V> method #

      A new Map with the same entries, in the same order.

    • Public Static Method DefaultValue(): ImmutableMap<K, V> static method #

      An empty one.

    • Public Method Iterate(): ImmutableMapIterator<K, V> method #

      Each key and its value, for 'For key, value In map', by their keys' hashes, and keys of one hash in the order they were added.

    ImmutableMapIterator struct 

    Public Struct ImmutableMapIterator<K, V> Implements Iterator<(K, V)>

    The entries of an ImmutableMap, in its order, which a For loop goes over.

    std/collections/immutable.fb, line 658

    • Public ByRef Method Next(): (K, V)? method #

      The next key and its value, in the ImmutableMap's order, or Null after the last.

    ImmutableSet struct 

    @DebugElements Public Struct ImmutableSet<T> Implements Iterable<T>, Defaultable, Sendable, Hashable

    A Set that never changes: each change gives a new one, which shares what it can with the old, so threads can share it.

    Examples

    Local a = ImmutableSet<Int>().AddAll([1, 2])
Local b = a.Add(3)
Expect(a.Count == 2 && b.Count == 3)
Expect(b.Contains(3) && !a.Contains(3))

    std/collections/immutable.fb, line 750

    • Public New() constructor #

      An empty one.

    • Public Static Method From(values: Iterable<T>): ImmutableSet<T> static method #

      One with the values, all read first.

    • Public Property Count: Int property #

      How many values it holds.

    • Public Method Contains(value: T): Bool method #

      Whether it holds value.

    • Public Method Add(value: T): ImmutableSet<T> method #

      A copy with the value, or the same one when it has it.

    • Public Method AddAll(values: Iterable<T>): ImmutableSet<T> method #

      A copy with each of the values added, all read first.

    • Public Method Remove(value: T): ImmutableSet<T> method #

      A copy without the value, or the same one when it hasn't got it.

    • Public Method ToArray(): T[] method #

      The values, in a new array, in the order they go in.

    • Public Static Method DefaultValue(): ImmutableSet<T> static method #

      An empty one.

    • Operator ==(a: ImmutableSet<T>, b: ImmutableSet<T>): Bool operator #

      Two ImmutableSets are equal when they have the same values.

    • Public Method Hash(): UInt64 method #

      Equal ImmutableSets have equal hashes, whatever order their values go in.

    • Public Method Iterate(): ImmutableSetIterator<T> method #

      The values, by their hashes, and values of one hash in the order they were added.

    ImmutableSetIterator struct 

    Public Struct ImmutableSetIterator<T> Implements Iterator<T>

    The values of an ImmutableSet, which a For loop goes over.

    std/collections/immutable.fb, line 819

    • Public ByRef Method Next(): T? method #

      The next value, in the ImmutableSet's order, or Null after the last.

    Extends

    ImmutableArray extend 

    Extend ImmutableArray<T> Implements Equatable

    Compares ImmutableArrays with == and !=, where their values can be compared.

    std/collections/immutable.fb, line 282

    • Operator ==(a: ImmutableArray<T>, b: ImmutableArray<T>): Bool operator #

      Whether the two have equal values in the same order.

    ImmutableArray extend 

    Extend ImmutableArray<T> Implements Hashable

    Hashes an ImmutableArray, where its values can be hashed, so it can be a Map's key or a Set's value.

    std/collections/immutable.fb, line 299

    • Public Method Hash(): UInt64 method #

      A hash of its values in order, which ImmutableArrays that are equal share.

    ImmutableArray extend 

    Extend ImmutableArray<T> Implements Printable

    Shows an ImmutableArray in a string, as its ToString writes it.

    std/collections/immutable.fb, line 314

    • Public Method ToString(): String method #

      Its values, in order, as an array shows them: "[1, 2, 3]".

    ImmutableMap extend 

    Extend ImmutableMap<K, V> Implements Equatable

    Compares ImmutableMaps with == and !=, where their values can be compared.

    std/collections/immutable.fb, line 693

    • Operator ==(a: ImmutableMap<K, V>, b: ImmutableMap<K, V>): Bool operator #

      Whether the two have the same keys, each with an equal value.

    ImmutableMap extend 

    Extend ImmutableMap<K, V> Implements Hashable

    Hashes an ImmutableMap, where its keys and values can be hashed, so it can be a Map's key or a Set's value.

    std/collections/immutable.fb, line 710

    • Public Method Hash(): UInt64 method #

      A hash of its entries, whatever their order, which ImmutableMaps that are equal share.

    ImmutableMap extend 

    Extend ImmutableMap<K, V> Implements Printable

    Shows an ImmutableMap in a string, as its ToString writes it.

    std/collections/immutable.fb, line 725

    • Public Method ToString(): String method #

      Its entries, in its order, as a Map shows them: "{a: 1, b: 2}".

    ImmutableSet extend 

    Extend ImmutableSet<T> Implements Printable

    Shows an ImmutableSet in a string, as its ToString writes it.

    std/collections/immutable.fb, line 835

    • Public Method ToString(): String method #

      Its values, in its order, as a Set shows them: "{1, 2, 3}".

    Report an issue with this page or with FutureBlitz on GitHub.