Add Disjoint Set collection

Author: hextriclosan

README.md

@@ -10,17 +10,50 @@ Alternatively you can pull it from the central Maven repositories:
 <dependency>
     <groupId>io.github.hextriclosan</groupId>
     <artifactId>algorithm</artifactId>
-    <version>0.0.3</version>
+    <version>0.0.4</version>
 </dependency>
 ```
 
 #### Gradle
 ```groovy
-implementation 'io.github.hextriclosan:algorithm:0.0.3'
+implementation 'io.github.hextriclosan:algorithm:0.0.4'
 ```
 
 ## Basic usage
 
+### Collections
+
+##### Disjoint Set
+Disjoint Set a.k.a. Union-Find data structure implementation
+```java
+DisjointSet<String> disjointSet = new DisjointSet<>();
+disjointSet.makeSets(List.of("New York", "Los Angeles", "Chicago", "Houston"));
+
+record Edge(String firstCity, String secondCity, int distance) {
+}
+
+List<Edge> edges = List.of(
+        new Edge("New York", "Los Angeles", 2445),
+        new Edge("New York", "Chicago", 790),
+        new Edge("New York", "Houston", 1628),
+        new Edge("Los Angeles", "Chicago", 2015),
+        new Edge("Los Angeles", "Houston", 1547),
+        new Edge("Chicago", "Houston", 1092)
+);
+
+edges.stream()
+    .sorted(Comparator.comparingInt(Edge::distance))
+    .filter(edge -> disjointSet.find(edge.firstCity()) != disjointSet.find(edge.secondCity()))
+    .forEach(edge -> {
+        disjointSet.union(edge.firstCity(), edge.secondCity());
+        System.out.println(edge);
+    });
+// prints out
+// Edge[firstCity=New York, secondCity=Chicago, distance=790]
+// Edge[firstCity=Chicago, secondCity=Houston, distance=1092]
+// Edge[firstCity=Los Angeles, secondCity=Houston, distance=1547]
+```
+
 ### Comparators
 
 ##### Lexicographical Comparator

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.github.hextriclosan</groupId>
     <artifactId>algorithm</artifactId>
-    <version>0.0.4-SNAPSHOT</version>
+    <version>0.0.4</version>
     <packaging>jar</packaging>
 
     <name>Java Algorithms</name>
@@ -40,11 +40,21 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     </properties>
 
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.junit</groupId>
+                <artifactId>junit-bom</artifactId>
+                <version>5.10.3</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
     <dependencies>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
-            <artifactId>junit-jupiter-engine</artifactId>
-            <version>5.10.3</version>
+            <artifactId>junit-jupiter</artifactId>
             <scope>test</scope>
         </dependency>
     </dependencies>

src/main/java/io/github/hextriclosan/algorithm/collections/DisjointSet.java

@@ -0,0 +1,129 @@
+package io.github.hextriclosan.algorithm.collections;
+
+import io.github.hextriclosan.algorithm.collections.disjointset.FindCompressStrategy;
+import io.github.hextriclosan.algorithm.collections.disjointset.FullCompression;
+
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * A data structure that maintains a collection of disjoint (non-overlapping) sets.
+ * It supports efficient union and find operations, as well as strategies for path compression and ranking.
+ *
+ * @param <E> the type of elements stored in the Disjoint Set
+ */
+public class DisjointSet<E> {
+    private final Map<E, E> parentByElement;
+    private final Map<E, Integer> rankByElement;
+    private final FindCompressStrategy<E> findCompressStrategy;
+
+    /**
+     * Constructs a DisjointSet with default initializations using {@link FullCompression} strategy.
+     */
+    public DisjointSet() {
+        this(new HashMap<>(), new HashMap<>(), new FullCompression<>());
+    }
+
+    /**
+     * Constructs a DisjointSet with a specified path compression strategy.
+     *
+     * @param findCompressStrategy the strategy used for path compression and find operations
+     */
+    public DisjointSet(FindCompressStrategy<E> findCompressStrategy) {
+        this(new HashMap<>(), new HashMap<>(), findCompressStrategy);
+    }
+
+    /**
+     * Constructs a DisjointSet with custom initial parent and rank mappings, along with a specified path compression strategy.
+     * This constructor allows the user to recreate a DisjointSet with a particular state, including predefined parent-to-element
+     * relationships, rank values, and a customized path compression strategy.
+     *
+     * @param parentByElement the initial mapping of elements to their parent elements
+     * @param rankByElement the initial mapping of elements to their ranks (or sizes)
+     * @param findCompressStrategy the strategy used for path compression and find operations
+     * @throws NullPointerException if any of the parameters are null
+     */
+    public DisjointSet(Map<E, E> parentByElement, Map<E, Integer> rankByElement, FindCompressStrategy<E> findCompressStrategy) {
+        Objects.requireNonNull(parentByElement, "parentByElement");
+        Objects.requireNonNull(rankByElement, "rankByElement");
+        Objects.requireNonNull(findCompressStrategy, "findCompressStrategy");
+        this.parentByElement = parentByElement;
+        this.rankByElement = rankByElement;
+        this.findCompressStrategy = findCompressStrategy;
+    }
+
+    /**
+     * Creates a new set with the specified element in the Disjoint Set structure.
+     * If the element is already present, no action is taken.
+     *
+     * @param element the element to initialize as a new set
+     * @throws NullPointerException if the specified element is null
+     */
+    public void makeSet(E element) {
+        Objects.requireNonNull(element, "element");
+        if (!parentByElement.containsKey(element)) {
+            parentByElement.put(element, element);
+            rankByElement.put(element, 0);
+        }
+    }
+
+    /**
+     * Creates new sets for each element in the specified collection in the Disjoint Set structure.
+     * If an element is already present, no action is taken for that element.
+     *
+     * @param elements the collection of elements to initialize as new sets
+     * @throws NullPointerException if the specified collection is null or contains null elements
+     */
+    public void makeSets(Collection<E> elements) {
+        Objects.requireNonNull(elements, "elements");
+        for (E element : elements) {
+            makeSet(element);
+        }
+    }
+
+    /**
+     * Unites the sets that contain the specified elements into a single set.
+     *
+     * @param first the first element
+     * @param second the second element
+     * @throws NullPointerException if either of the elements is null
+     */
+    public void union(E first, E second) {
+        Objects.requireNonNull(first, "first");
+        Objects.requireNonNull(second, "second");
+        E firstRoot = find(first);
+        E secondRoot = find(second);
+
+        if (firstRoot == secondRoot) {
+            return;
+        }
+
+        int firstRootRank = rankByElement.get(firstRoot);
+        int secondRootRank = rankByElement.get(secondRoot);
+
+        if (firstRootRank > secondRootRank) {
+            parentByElement.put(secondRoot, firstRoot);
+        } else {
+            parentByElement.put(firstRoot, secondRoot);
+            if (firstRootRank == secondRootRank) {
+                rankByElement.put(secondRoot, secondRootRank + 1);
+            }
+        }
+    }
+
+    /**
+     * Finds the representative (root) of the set containing the specified element,
+     * using the configured find and path compression strategy.
+     *
+     * @param element the element to find
+     * @return the representative (root) of the set containing the element
+     * @throws NullPointerException if the element is null
+     */
+    public E find(E element) {
+        Objects.requireNonNull(element, "element");
+        return findCompressStrategy.apply(parentByElement, element);
+    }
+
+}

src/main/java/io/github/hextriclosan/algorithm/collections/disjointset/FindCompressStrategy.java

@@ -0,0 +1,14 @@
+package io.github.hextriclosan.algorithm.collections.disjointset;
+
+import java.util.Map;
+import java.util.function.BiFunction;
+
+/**
+ * A strategy interface for the find and path compression operation in the {@link io.github.hextriclosan.algorithm.collections.DisjointSet}.
+ * This interface extends the {@link BiFunction} interface, taking a map of element-to-parent relationships and
+ * an element, and returning the representative (or root) of the subset containing the given element.
+ *
+ * @param <E> the type of elements in the Disjoint Set
+ */
+public interface FindCompressStrategy<E> extends BiFunction<Map<E, E>, E, E> {
+}

src/main/java/io/github/hextriclosan/algorithm/collections/disjointset/FullCompression.java

@@ -0,0 +1,45 @@
+package io.github.hextriclosan.algorithm.collections.disjointset;
+
+import java.util.Map;
+
+/**
+ * An implementation of the {@link FindCompressStrategy} interface that performs full path compression.
+ * This strategy ensures that all nodes along the path from the given element to the root are directly
+ * connected to the root, optimizing future find operations.
+ *
+ * @param <E> the type of elements in the Disjoint Set
+ */
+public class FullCompression<E> implements FindCompressStrategy<E> {
+
+    /**
+     * Applies the full path compression strategy to find the root of the subset containing the specified element.
+     * If the element is not found in the map, an {@link IllegalArgumentException} is thrown.
+     *
+     * @param parentByElement the map representing the parent relationship of elements in the disjoint set
+     * @param element the element for which to find the root
+     * @return the root of the subset containing the specified element
+     * @throws IllegalArgumentException if the element is not found in the disjoint set
+     */
+    @Override
+    public E apply(Map<E, E> parentByElement, E element) {
+        if (!parentByElement.containsKey(element)) {
+            throw new IllegalArgumentException("Element not found in the disjoint set");
+        }
+
+        E old = element;
+        E ancestor = parentByElement.get(element);
+        while (ancestor != element) {
+            element = ancestor;
+            ancestor = parentByElement.get(element);
+        }
+
+        element = parentByElement.get(old);
+        while (ancestor != element) {
+            parentByElement.put(old, ancestor);
+            old = element;
+            element = parentByElement.get(old);
+        }
+
+        return ancestor;
+    }
+}

src/main/java/io/github/hextriclosan/algorithm/collections/disjointset/PathHalvingCompression.java

@@ -0,0 +1,39 @@
+package io.github.hextriclosan.algorithm.collections.disjointset;
+
+import java.util.Map;
+
+/**
+ * An implementation of the {@link FindCompressStrategy} interface that performs path halving compression.
+ * This strategy optimizes the find operation by halving the path length during path compression.
+ *
+ * @param <E> the type of elements in the Disjoint Set
+ */
+public class PathHalvingCompression<E> implements FindCompressStrategy<E> {
+
+    /**
+     * Applies the path halving compression strategy to find the root of the subset containing the specified element.
+     * If the element is not found in the map, an {@link IllegalArgumentException} is thrown.
+     *
+     * @param parentByElement the map representing the parent relationship of elements in the disjoint set
+     * @param element the element for which to find the root
+     * @return the root of the subset containing the specified element
+     * @throws IllegalArgumentException if the element is not found in the disjoint set
+     */
+    @Override
+    public E apply(Map<E, E> parentByElement, E element) {
+        if (!parentByElement.containsKey(element)) {
+            throw new IllegalArgumentException("Element not found in the disjoint set");
+        }
+
+        E parent = parentByElement.get(element);
+        E grandparent = parentByElement.get(parent);
+        while (parent != grandparent) {
+            parentByElement.put(element, grandparent);
+            element = grandparent;
+            parent = parentByElement.get(element);
+            grandparent = parentByElement.get(parent);
+        }
+
+        return parent;
+    }
+}