#HashSet

    A mutable hash set based on a Robin Hood hash table.

    #Usage

    Floating elements and keys used by ordinary comparison-based operations must not be NaN, including floating components of derived/composite keys. Signed zeros, infinities, and subnormals are supported. This is an input precondition, not an automatic NaN check; see the Eq and Compare trait contracts.

    #Create

    You can create an empty set using HashSet([]) or construct it from entries using HashSet([...]).

    ///|
    test {
    let _set1 = @hashset.HashSet([1, 2, 3, 4, 5])
    let _set2 : @hashset.HashSet[String] = HashSet([])
    }

    #Insert & Contain

    You can use add() to add a key to the set, and contains() to check whether a key exists.

    ///|
    test {
    let set : @hashset.HashSet[String] = HashSet([])
    set.add("a")
    @test.assert_eq(set.contains("a"), true)
    }

    #Remove

    You can use remove() to remove a key.

    ///|
    test {
    let set = @hashset.from_array(["a", "b", "c"])
    set.remove("a")
    @test.assert_eq(set.contains("a"), false)
    }

    #Size

    You can use length() to get the number of keys in the set. If you know roughly how large a set will get, pass a capacity hint when creating it to pre-size the table.

    ///|
    test {
    let set = @hashset.from_array(["a", "b", "c"])
    @test.assert_eq(set.length(), 3)
    let sized : @hashset.HashSet[String] = HashSet([], capacity=100)
    @test.assert_eq(sized.length(), 0)
    }

    Similarly, you can use is_empty() to check whether the set is empty.

    ///|
    test {
    let set : @hashset.HashSet[Int32] = HashSet([])
    @test.assert_eq(set.is_empty(), true)
    }

    #Clear

    You can use clear to remove all keys from the set, but the allocated memory will not change.

    ///|
    test {
    let set = @hashset.from_array(["a", "b", "c"])
    set.clear()
    @test.assert_eq(set.is_empty(), true)
    }

    #Iteration

    You can use each() or eachi() to iterate through all keys.

    ///|
    test {
    let set = @hashset.from_array(["a", "b", "c"])
    let arr = []
    set.each(k => arr.push(k))
    let arr2 = []
    set.eachi((i, k) => arr2.push((i, k)))
    }

    #Add & Remove with Check

    add_and_check() returns true if the element was newly added (not already present). remove_and_check() returns true if the element was actually removed.

    ///|
    test {
    let set = @hashset.from_array([1, 2, 3])
    @test.assert_eq(set.add_and_check(4), true) // new element
    @test.assert_eq(set.add_and_check(4), false) // already exists
    @test.assert_eq(set.remove_and_check(4), true) // removed
    @test.assert_eq(set.remove_and_check(4), false) // not present
    }

    #Retain

    retain() keeps only elements that satisfy a predicate, removing the rest in place.

    ///|
    test {
    let set = @hashset.from_array([1, 2, 3, 4, 5])
    set.retain(fn(x) { x % 2 == 0 })
    @test.assert_eq(set.contains(1), false)
    @test.assert_eq(set.contains(2), true)
    }

    #Copy

    copy() creates a shallow clone of the set.

    ///|
    test {
    let set = @hashset.from_array([1, 2, 3])
    let cloned = set.copy()
    cloned.add(4)
    @test.assert_eq(set.contains(4), false) // original unchanged
    @test.assert_eq(cloned.contains(4), true)
    }

    #Iterators & Conversion

    iter() returns an iterator. to_array() collects elements into an array. from_iter() constructs a set from an iterator.

    ///|
    test {
    let set = @hashset.from_array([1, 2, 3])
    let arr = set.to_array()
    arr.sort()
    @test.assert_eq(arr, [1, 2, 3])
    // from_iter
    let set2 = @hashset.from_iter([|4, 5, 6|])
    @test.assert_eq(set2.length(), 3)
    }

    #Set Operations

    union(), intersection(), difference(), and symmetric_difference() return new sets. These also have operator aliases: | (union), & (intersection), - (difference), ^ (symmetric difference).

    ///|
    test {
    let m1 = @hashset.from_array(["a", "b", "c"])
    let m2 = @hashset.from_array(["b", "c", "d"])
    fn to_sorted_array(set : @hashset.HashSet[String]) {
    let arr = set.to_array()
    arr.sort()
    arr
    }

    @test.assert_eq(m1.union(m2) |> to_sorted_array, ["a", "b", "c", "d"])
    @test.assert_eq(m1.intersection(m2) |> to_sorted_array, ["b", "c"])
    @test.assert_eq(m1.difference(m2) |> to_sorted_array, ["a"])
    @test.assert_eq(m1.symmetric_difference(m2) |> to_sorted_array, ["a", "d"])
    // operator aliases
    @test.assert_eq((m1 | m2) |> to_sorted_array, ["a", "b", "c", "d"])
    @test.assert_eq((m1 & m2) |> to_sorted_array, ["b", "c"])
    @test.assert_eq((m1 - m2) |> to_sorted_array, ["a"])
    @test.assert_eq((m1 ^ m2) |> to_sorted_array, ["a", "d"])
    }

    #Set Predicates

    is_subset(), is_superset(), and is_disjoint() test set relationships.

    ///|
    test {
    let small = @hashset.from_array([1, 2])
    let big = @hashset.from_array([1, 2, 3, 4])
    let other = @hashset.from_array([5, 6])
    @test.assert_eq(small.is_subset(big), true)
    @test.assert_eq(big.is_superset(small), true)
    @test.assert_eq(small.is_disjoint(other), true)
    @test.assert_eq(small.is_disjoint(big), false)
    }

    HashSet

    type HashSet[K]

    Mutable hash set, not thread safe.

    Example

    test {
    let set = @hashset.HashSet([(3, "three"), (8, "eight"), (1, "one")])
    set.add((4, "four"))
    @test.assert_eq(set.contains((4, "four")), true)
    }
    impl BitAnd for HashSet[K]
    impl BitOr for HashSet[K]
    impl BitXOr for HashSet[K]
    impl Default for HashSet[K]
    impl Eq for HashSet[K]
    impl Show for HashSet[K]
    impl Sub for HashSet[K]
    impl FromJson for HashSet[X]
    impl ToJson for HashSet[X]

    HashSet::HashSet

    #as_free_fn(of, deprecated="Use from_array instead")
    #alias(of, deprecated="Use from_array instead")
    #as_free_fn(from_array)
    #alias(from_array)
    fn[K : Hash + Eq] HashSet::HashSet(arr : ArrayView[K], capacity? : Int) -> HashSet[K]

    Creates a hash set containing all elements from the given array. The optional capacity reserves room for at least that many total elements without growing, including the elements in arr. A hint smaller than arr.length() is ignored. Without a hint, an empty set uses a small default size. Aborts if capacity is negative or if the requested element count exceeds the supported table size.

    HashSet::add

    #alias(insert, deprecated="`insert` is deprecated, use `add` instead")
    fn[K : Hash + Eq] HashSet::add(self : HashSet[K], key : K) -> Unit

    Insert a key into hash set.

    Parameters:

    • self : The hash set to modify.
    • key : The key to insert. Must implement Hash and Eq traits.

    Example:

    test {
    let set : @hashset.HashSet[String] = HashSet([])
    set.add("key")
    inspect(set.contains("key"), content="true")
    set.add("key") // no effect since it already exists
    inspect(set.length(), content="1")
    }

    HashSet::add_and_check

    fn[K : Hash + Eq] HashSet::add_and_check(self : HashSet[K], key : K) -> Bool

    Insert a key into the hash set and returns whether the key was successfully added.

    Parameters:

    • self : The hash set to modify.
    • key : The key to insert. Must implement Hash and Eq traits.

    Returns true if the key was successfully added (i.e., it wasn't already present), false if the key already existed in the set.

    Example:

    test {
    let set : @hashset.HashSet[String] = HashSet([])
    inspect(set.add_and_check("key"), content="true") // First insertion
    inspect(set.add_and_check("key"), content="false") // Already exists
    inspect(set.length(), content="1")
    }

    HashSet::capacity

    #deprecated("The bucket count is an implementation detail; the constructor's `capacity` hint is the only sizing control")
    fn[K] HashSet::capacity(self : HashSet[K]) -> Int

    Returns the number of buckets in the internal table.

    Deprecated: the bucket count is an implementation detail. Size the table with the constructor's capacity hint instead.

    HashSet::clear

    fn[K] HashSet::clear(self : HashSet[K]) -> Unit

    Clears the set, removing all keys. Keeps the allocated space.

    HashSet::contains

    fn[K : Hash + Eq] HashSet::contains(self : HashSet[K], key : K) -> Bool

    Returns true if the set contains the given key.

    HashSet::copy

    #alias(clone, deprecated="`clone` is deprecated, use `copy` instead")
    fn[K] HashSet::copy(self : HashSet[K]) -> HashSet[K]

    Copy the set, creating a new set with the same keys.

    HashSet::difference

    fn[K : Eq] HashSet::difference(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    Returns a new set containing elements in self that are not in other.

    HashSet::each

    fn[K] HashSet::each(self : HashSet[K], f : (K) -> Unit raise?) -> Unit raise?

    Calls f on each element in the set.

    If f structurally modifies the set (adds or removes elements, or clears it), the result is unspecified, though memory-safe.

    HashSet::eachi

    fn[K] HashSet::eachi(self : HashSet[K], f : (Int, K) -> Unit raise?) -> Unit raise?

    Calls f on each element with its index (0-based).

    If f structurally modifies the set (adds or removes elements, or clears it), the result is unspecified, though memory-safe.

    HashSet::equal

    fn[K : Eq] HashSet::equal(self : HashSet[K], other : HashSet[K]) -> Bool

    HashSet::filter

    fn[K] HashSet::filter(self : HashSet[K], f : (K) -> Bool raise?) -> HashSet[K] raise?

    Returns a new hash set holding the elements for which f returns true. self is unchanged.

    true means keep, as with Array::filter. To filter in place instead, use HashSet::retain.

    The result is sized for the elements kept, like @hashset.from_array. It is faster than rebuilding from a comprehension such as @hashset.from_array([for k in s if f(k) => k]) because each element's stored hash is reused: elements are never hashed again.

    If f structurally modifies self (adds or removes elements, or clears it), the result is unspecified, though memory-safe.

    Example:

    test {
    let set = @hashset.from_array([1, 2, 3, 4])
    let even = set.filter(x => x % 2 == 0)
    inspect(even.length(), content="2")
    inspect(even.contains(2), content="true")
    inspect(even.contains(3), content="false")
    inspect(set.length(), content="4")
    }

    HashSet::from_iter

    #as_free_fn(from_iterator, deprecated="Use HashSet::from_iter instead.")
    #alias(from_iterator, deprecated="`from_iterator` is deprecated, use `from_iter` instead")
    #as_free_fn
    fn[K : Hash + Eq] HashSet::from_iter(iter : Iter[K]) -> HashSet[K]

    Creates a hash set from an iterator of keys.

    HashSet::intersection

    fn[K : Eq] HashSet::intersection(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    Returns a new set containing only elements present in both sets. Equal keys retain the representative from this set.

    HashSet::is_disjoint

    fn[K : Eq] HashSet::is_disjoint(self : HashSet[K], other : HashSet[K]) -> Bool

    Returns true if the two sets have no elements in common.

    HashSet::is_empty

    fn[K] HashSet::is_empty(self : HashSet[K]) -> Bool

    Returns true if the set contains no elements.

    HashSet::is_subset

    fn[K : Eq] HashSet::is_subset(self : HashSet[K], other : HashSet[K]) -> Bool

    Returns true if every element of self is also in other.

    HashSet::is_superset

    fn[K : Eq] HashSet::is_superset(self : HashSet[K], other : HashSet[K]) -> Bool

    Returns true if every element of other is also in self.

    HashSet::iter

    #alias(iterator, deprecated="`iterator` is deprecated, use `iter` instead")
    fn[K] HashSet::iter(self : HashSet[K]) -> Iter[K]

    Returns an iterator over the elements of the set.

    If the set is structurally modified (elements added or removed, or the set cleared) while the iterator is in use, what it yields is unspecified, though memory-safe.

    HashSet::land

    fn[K : Eq] HashSet::land(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    HashSet::length

    #alias(size, deprecated="`size` is deprecated, use `length` instead")
    fn[K] HashSet::length(self : HashSet[K]) -> Int

    Returns the number of elements in the set.

    HashSet::lor

    fn[K : Eq] HashSet::lor(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    HashSet::lxor

    fn[K : Eq] HashSet::lxor(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    HashSet::new

    #as_free_fn(deprecated="Use `HashSet([], capacity=...)` instead")
    #deprecated("Use `HashSet([], capacity=...)` instead")
    fn[K] HashSet::new(capacity? : Int) -> HashSet[K]

    Creates an empty hash set with an optional initial capacity.

    Deprecated: use HashSet([], capacity=...) instead.

    HashSet::remove

    fn[K : Hash + Eq] HashSet::remove(self : HashSet[K], key : K) -> Unit

    Remove a key from hash set. If the key exists in the set, removes it and adjusts the probe sequence length (PSL) of subsequent entries to maintain the Robin Hood hashing invariant. If the key does not exist, the set remains unchanged.

    Parameters:

    • self : The hash set to remove the key from.
    • key : The key to remove from the set.

    Example:

    test {
    let set = @hashset.from_array(["a", "b"])
    set.remove("a")
    inspect(set.contains("a"), content="false")
    inspect(set.length(), content="1")
    }

    HashSet::remove_and_check

    fn[K : Hash + Eq] HashSet::remove_and_check(self : HashSet[K], key : K) -> Bool

    Remove a key from the hash set and returns whether the key was successfully removed.

    Parameters:

    • self : The hash set to modify.
    • key : The key to remove. Must implement Hash and Eq traits.

    Returns true if the key was successfully removed (i.e., it was present), false if the key didn't exist in the set.

    Example:

    test {
    let set = @hashset.from_array(["a", "b"])
    inspect(set.remove_and_check("a"), content="true") // Successfully removed
    inspect(set.remove_and_check("a"), content="false") // Already removed
    inspect(set.length(), content="1")
    }

    HashSet::retain

    fn[K] HashSet::retain(self : HashSet[K], f : (K) -> Bool) -> Unit

    Keeps only the elements for which f returns true, removing the rest in place. Calls the predicate once per element, in unspecified order.

    true means keep, as with HashSet::filter, which returns a new set and leaves self unchanged; use retain when the original is no longer needed. f must not modify the set: the result is then unspecified, though memory-safe.

    HashSet::sub

    fn[K : Eq] HashSet::sub(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    HashSet::symmetric_difference

    fn[K : Eq] HashSet::symmetric_difference(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    Symmetric difference of two hash sets.

    HashSet::to_array

    fn[K] HashSet::to_array(self : HashSet[K]) -> Array[K]

    Converts the hash set to an array.

    HashSet::union

    fn[K : Eq] HashSet::union(self : HashSet[K], other : HashSet[K]) -> HashSet[K]

    Returns a new set containing all elements from both sets.

    HashSet::union_in_place

    fn[K : Eq] HashSet::union_in_place(self : HashSet[K], other : HashSet[K]) -> Unit

    Adds every element of other to self, in place: the mutating counterpart of union, as HashMap::merge_in_place is of HashMap::merge. Elements are not hashed again, so only Eq is needed.

    Example:

    test {
    let set = @hashset.from_array([3, 1])
    set.union_in_place(@hashset.from_array([2, 3, 4]))
    inspect(set.length(), content="4")
    inspect(set.contains(4), content="true")
    }