Add set operations to @immut/hash{map, set} and @internal/sparse_array Summary

[Asterless]

Related Issue

Fixes #1830: Efficient set operations for @immut/hash{map, set}

Changes

@immut/hashmap

• union_with(f: (K, V, V) => V)
  Merges two hashmaps, resolving key conflicts with a custom function f.
• intersection()
  Returns a new hashmap containing keys present in both input maps, with values from the first map.
• intersection_with(f: (K, V, V) => V)
  Computes intersection, resolving overlapping keys' values with function f.
• difference()
  Returns entries present in the first map but not in the second.

@immut/hashset

• intersection()
  Returns a new set containing elements common to both input sets.
• difference()
  Returns elements present in the first set but not in the second.

@internal/sparse_array

• intersection()
  Computes index-wise intersection of two sparse arrays.
• difference()
  Computes index-wise difference between two sparse arrays.

Motivation

These changes provide a more complete and consistent set of set operations for immutable collections, making it easier to perform common set algebra tasks and improving API parity across collection types.

Tests

Added and updated unit tests for all new and modified methods to ensure correctness and expected behavior.

Checklist

All new and existing tests pass
Code is formatted and documented where appropriate

[peter-jerry-ye-code-review]

Potential performance issue in hashset intersection implementation

Category
Correctness
Code Snippet
Branch(sa1), Branch(sa2)) => {
let res = sa1.intersection(sa2, fn(m1, m2) { m1.intersection(m2) })
if res.size() == 0 {
Empty
} else {
Branch(res)
}
Recommendation
Avoid creating intermediate Branch if result is empty:

Branch(sa1), Branch(sa2)) => {
  let res = sa1.intersection(sa2, fn(m1, m2) { m1.intersection(m2) })
  match res.size() {
    0 => Empty
    _ => Branch(res)
  }
}
**Reasoning**
The current implementation creates a Branch node and then checks if it's empty, potentially wasting memory. By checking size first, we can return Empty directly without allocating unnecessary Branch node.

</details>
<details>

<summary> Missing documentation for important parameter in union_with </summary>

**Category**
Maintainability
**Code Snippet**
pub fn[K : Eq + Hash, V] union_with(
  self : T[K, V],
  other : T[K, V],
  f : (K, V, V) -> V
) -> T[K, V]
**Recommendation**
Add detailed documentation for the union function parameter:
```moonbit
///|
/// Union two hashmaps with a function
/// @param f Function to resolve conflicts, receives (key, value1, value2) and returns merged value
/// @return New hashmap containing all keys with values combined using f for duplicates
pub fn[K : Eq + Hash, V] union_with(...)
**Reasoning**
The function parameter f is critical for understanding how value conflicts are resolved, but lacks documentation about its expected behavior and contract. Clear documentation helps users implement correct combining functions.

</details>
<details>

<summary> Inefficient handling of empty cases in difference operation </summary>

**Category**
Performance
**Code Snippet**
pub fn[K : Eq + Hash] difference(self : T[K], other : T[K]) -> T[K] {
  match (self, other) {
    (Empty, _) => Empty
    (_, Empty) => self
**Recommendation**
Add more specific pattern matching for efficiency:
```moonbit
match (self, other) {
  (Empty, _) => Empty
  (s, Empty) => s.clone()
  (Leaf(k), Leaf(k2)) when k == k2 => Empty
  (Leaf(k), Leaf(_)) => self
**Reasoning**
Adding more specific pattern matching for common cases like identical single elements can avoid unnecessary iteration and improve performance for simple cases. The clone() is explicit about creating a new copy.

</details>

[coveralls]

Pull Request Test Coverage Report for Build 6913

Details

• 52 of 103 (50.49%) changed or added relevant lines in 3 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.4%) to 92.01%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
immut/internal/sparse_array/sparse_array.mbt	15	16	93.75%
immut/hashset/HAMT.mbt	7	26	26.92%
immut/hashmap/HAMT.mbt	30	61	49.18%

Totals
Change from base Build 6912:	-0.4%
Covered Lines:	8740
Relevant Lines:	9499

---

💛 - Coveralls