feat: Add Disjoint Set(Union Find)

Author: idsulik

README.md

@@ -28,6 +28,7 @@
    - [BloomFilter](#bloom-filter)
    - [RingBuffer(Circular Buffer)](#ring-buffer)
    - [SegmentTree](#segment-tree)
+   - [DisjointSet(UnionFind)](#disjoint-set)
 4. [License](#license)
 
 ## [Installation](#installation)
@@ -578,6 +579,85 @@ minSt := collections.NewSegmentTree(arr, math.Inf(1), func(a, b float64) float64
 - Statistical range queries
 - Competitive programming
 - Database query optimization
+---
+### [Disjoint Set](#disjoint-set)
+
+A Disjoint Set (also known as Union-Find) is a data structure that keeps track of elements partitioned into non-overlapping subsets. It provides near-constant-time operations to merge sets and determine if two elements belong to the same set.
+
+#### Type `DisjointSet[T comparable]`
+
+- **Constructor:**
+
+  ```go
+  func New[T comparable]() *DisjointSet[T]
+  ```
+
+- **Methods:**
+
+  - `MakeSet(x T)`: Creates a new set containing a single element.
+  - `Find(x T) T`: Returns the representative element of the set containing x.
+  - `Union(x, y T)`: Merges the sets containing elements x and y.
+  - `Connected(x, y T) bool`: Returns true if elements x and y are in the same set.
+  - `Clear()`: Removes all elements from the disjoint set.
+  - `Len() int`: Returns the number of elements in the disjoint set.
+  - `IsEmpty() bool`: Returns true if the disjoint set contains no elements.
+  - `GetSets() map[T][]T`: Returns a map of representatives to their set members.
+
+#### Example Usage:
+
+```go
+package main
 
+import (
+    "fmt"
+    "github.com/idsulik/go-collections/v2/disjointset"
+)
+
+func main() {
+    // Create a new disjoint set
+    ds := disjointset.New[string]()
+
+    // Create individual sets
+    ds.MakeSet("A")
+    ds.MakeSet("B")
+    ds.MakeSet("C")
+    ds.MakeSet("D")
+
+    // Merge sets
+    ds.Union("A", "B")
+    ds.Union("C", "D")
+
+    // Check if elements are in the same set
+    fmt.Println(ds.Connected("A", "B")) // true
+    fmt.Println(ds.Connected("A", "C")) // false
+
+    // Get all sets
+    sets := ds.GetSets()
+    for root, elements := range sets {
+        fmt.Printf("Set with root %v: %v\n", root, elements)
+    }
+}
+```
+
+#### Performance Characteristics:
+
+- MakeSet: O(1)
+- Find: O(α(n)) amortized (nearly constant)
+- Union: O(α(n)) amortized (nearly constant)
+- Connected: O(α(n)) amortized (nearly constant)
+
+Where α(n) is the inverse Ackermann function, which grows extremely slowly and is effectively constant for all practical values of n.
+
+#### Use Cases:
+
+- Detecting cycles in graphs
+- Finding connected components
+- Network connectivity
+- Image processing (connected component labeling)
+- Kruskal's minimum spanning tree algorithm
+- Dynamic connectivity problems
+- Online dynamic connectivity
+- Percolation analysis
+---
 ## [License](#license)
 This project is licensed under the [MIT License](LICENSE) - see the [LICENSE](LICENSE) file for details.

disjointset/disjointset.go

@@ -0,0 +1,88 @@
+package disjointset
+
+// DisjointSet represents a disjoint set data structure
+type DisjointSet[T comparable] struct {
+	parent map[T]T
+	rank   map[T]int
+}
+
+// New creates a new DisjointSet instance
+func New[T comparable]() *DisjointSet[T] {
+	return &DisjointSet[T]{
+		parent: make(map[T]T),
+		rank:   make(map[T]int),
+	}
+}
+
+// MakeSet creates a new set containing a single element
+func (ds *DisjointSet[T]) MakeSet(x T) {
+	if _, exists := ds.parent[x]; !exists {
+		ds.parent[x] = x
+		ds.rank[x] = 0
+	}
+}
+
+// Find returns the representative element of the set containing x
+// Uses path compression for optimization
+func (ds *DisjointSet[T]) Find(x T) T {
+	if _, exists := ds.parent[x]; !exists {
+		return x
+	}
+
+	if ds.parent[x] != x {
+		ds.parent[x] = ds.Find(ds.parent[x]) // Path compression
+	}
+	return ds.parent[x]
+}
+
+// Union merges the sets containing elements x and y
+// Uses union by rank for optimization
+func (ds *DisjointSet[T]) Union(x, y T) {
+	rootX := ds.Find(x)
+	rootY := ds.Find(y)
+
+	if rootX == rootY {
+		return
+	}
+
+	// Union by rank
+	if ds.rank[rootX] < ds.rank[rootY] {
+		ds.parent[rootX] = rootY
+	} else if ds.rank[rootX] > ds.rank[rootY] {
+		ds.parent[rootY] = rootX
+	} else {
+		ds.parent[rootY] = rootX
+		ds.rank[rootX]++
+	}
+}
+
+// Connected returns true if elements x and y are in the same set
+func (ds *DisjointSet[T]) Connected(x, y T) bool {
+	return ds.Find(x) == ds.Find(y)
+}
+
+// Clear removes all elements from the disjoint set
+func (ds *DisjointSet[T]) Clear() {
+	ds.parent = make(map[T]T)
+	ds.rank = make(map[T]int)
+}
+
+// Len returns the number of elements in the disjoint set
+func (ds *DisjointSet[T]) Len() int {
+	return len(ds.parent)
+}
+
+// IsEmpty returns true if the disjoint set contains no elements
+func (ds *DisjointSet[T]) IsEmpty() bool {
+	return len(ds.parent) == 0
+}
+
+// GetSets returns a map of representatives to their set members
+func (ds *DisjointSet[T]) GetSets() map[T][]T {
+	sets := make(map[T][]T)
+	for element := range ds.parent {
+		root := ds.Find(element)
+		sets[root] = append(sets[root], element)
+	}
+	return sets
+}

disjointset/disjointset_test.go

@@ -0,0 +1,119 @@
+package disjointset
+
+import (
+	"testing"
+)
+
+func TestDisjointSet(t *testing.T) {
+	t.Run(
+		"New DisjointSet", func(t *testing.T) {
+			ds := New[int]()
+			if !ds.IsEmpty() {
+				t.Error("New DisjointSet should be empty")
+			}
+		},
+	)
+
+	t.Run(
+		"MakeSet", func(t *testing.T) {
+			ds := New[int]()
+			ds.MakeSet(1)
+			if ds.Find(1) != 1 {
+				t.Error("MakeSet should create a set with the element as its own representative")
+			}
+		},
+	)
+
+	t.Run(
+		"Union and Find", func(t *testing.T) {
+			ds := New[int]()
+			ds.MakeSet(1)
+			ds.MakeSet(2)
+			ds.MakeSet(3)
+
+			ds.Union(1, 2)
+			if !ds.Connected(1, 2) {
+				t.Error("Elements 1 and 2 should be connected after Union")
+			}
+
+			ds.Union(2, 3)
+			if !ds.Connected(1, 3) {
+				t.Error("Elements 1 and 3 should be connected after Union")
+			}
+		},
+	)
+
+	t.Run(
+		"Connected", func(t *testing.T) {
+			ds := New[string]()
+			ds.MakeSet("A")
+			ds.MakeSet("B")
+			ds.MakeSet("C")
+
+			if ds.Connected("A", "B") {
+				t.Error("Elements should not be connected before Union")
+			}
+
+			ds.Union("A", "B")
+			if !ds.Connected("A", "B") {
+				t.Error("Elements should be connected after Union")
+			}
+		},
+	)
+
+	t.Run(
+		"Clear", func(t *testing.T) {
+			ds := New[int]()
+			ds.MakeSet(1)
+			ds.MakeSet(2)
+			ds.Union(1, 2)
+
+			ds.Clear()
+			if !ds.IsEmpty() {
+				t.Error("DisjointSet should be empty after Clear")
+			}
+		},
+	)
+
+	t.Run(
+		"GetSets", func(t *testing.T) {
+			ds := New[int]()
+			ds.MakeSet(1)
+			ds.MakeSet(2)
+			ds.MakeSet(3)
+			ds.MakeSet(4)
+
+			ds.Union(1, 2)
+			ds.Union(3, 4)
+
+			sets := ds.GetSets()
+			if len(sets) != 2 {
+				t.Error("Should have exactly 2 distinct sets")
+			}
+
+			for _, set := range sets {
+				if len(set) != 2 {
+					t.Error("Each set should contain exactly 2 elements")
+				}
+			}
+		},
+	)
+
+	t.Run(
+		"Path Compression", func(t *testing.T) {
+			ds := New[int]()
+			ds.MakeSet(1)
+			ds.MakeSet(2)
+			ds.MakeSet(3)
+
+			ds.Union(1, 2)
+			ds.Union(2, 3)
+
+			// After finding 3, the path should be compressed
+			root := ds.Find(3)
+			if ds.parent[3] != root {
+				t.Error("Path compression should make 3 point directly to the root")
+			}
+		},
+	)
+}