49 add union find data structure

src/org/sosy_lab/common/collect/PackageSanityTest.java

@@ -9,7 +9,10 @@
 package org.sosy_lab.common.collect;
 
 import com.google.common.testing.AbstractPackageSanityTests;
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Method;
 import org.sosy_lab.common.Classes;
+import org.sosy_lab.common.collect.union_find.SortedTreeSetUnionFind;
 
 public class PackageSanityTest extends AbstractPackageSanityTests {
 
@@ -24,4 +27,19 @@ public class PackageSanityTest extends AbstractPackageSanityTests {
         OurSortedMap.class, OurSortedMap.EmptyImmutableOurSortedMap.of(), singletonMap);
     ignoreClasses(Classes.IS_GENERATED);
   }
+
+  {
+    setDefault(SortedTreeSetUnionFind.class, new SortedTreeSetUnionFind<>());
+    // ignoreClasses(Classes.IS_GENERATED);
+
+    try {
+      setDefault(Constructor.class, PackageSanityTest.class.getConstructor());
+      setDefault(Method.class, PackageSanityTest.class.getDeclaredMethod("defaultMethod"));
+    } catch (NoSuchMethodException e) {
+      throw new AssertionError(e);
+    }
+  }
+
+  @SuppressWarnings("unused")
+  private static void defaultMethod() {}
 }

src/org/sosy_lab/common/collect/union_find/AbstractGenericUnionFind.java

@@ -0,0 +1,179 @@
+// This file is part of SoSy-Lab Common,
+// a library of useful utilities:
+// https://github.com/sosy-lab/java-common-lib
+//
+// SPDX-FileCopyrightText: 2026 Dirk Beyer <https://www.sosy-lab.org>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package org.sosy_lab.common.collect.union_find;
+
+import com.google.common.base.Preconditions;
+import java.util.Collection;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Set;
+
+/**
+ * An abstract, generic implementation of {@link UnionFind} using a {@link Map} of {@link Set}s. In
+ * order to represent subsets by canonical elements, each one is mapped to its representative
+ * canonical element. This is always the first element added to the subset, unless it has changed
+ * due to union operations. The union is implemented as union by size.
+ *
+ * @param <T> type of elements added to the Union-Find.
+ */
+public abstract class AbstractGenericUnionFind<T, S extends Set<T>, M extends Map<T, S>>
+    implements UnionFind<T> {
+
+  protected final M mapOfSets;
+
+  /**
+   * Takes an empty map of the desired kind and allocates it to the variable mapOfSets. This enables
+   * child classes to simply pass an object of the desired kind without having to modify the
+   * constructor and methods.
+   */
+  @SuppressWarnings("unchecked")
+  public AbstractGenericUnionFind() {
+    mapOfSets = (M) getEmptyMap();
+  }
+
+  /**
+   * Returns the canonical element of the set containing the provided element.
+   *
+   * @param pE element for which set is to be found
+   * @return canonical element of the found set
+   * @throws IllegalArgumentException if element is not contained in any subset
+   */
+  @Override
+  public T find(T pE) {
+
+    Preconditions.checkNotNull(pE);
+
+    for (Entry<T, S> mapping : mapOfSets.entrySet()) {
+      if (mapping.getValue().contains(pE)) {
+        return mapping.getKey();
+      }
+    }
+
+    throw new IllegalArgumentException("Element not contained");
+  }
+
+  /**
+   * Merges the sets represented by the two input values according to standard Union-Find behaviour.
+   *
+   * <p>USES: Add new element as new set: pass it as both pE1 and pE2. Add new element to existing
+   * set: one input value is the new element, the other the canonical element of the set to be added
+   * to. Merge two existing sets: pE1, pE2 canonical elements of sets to be merged.
+   *
+   * @param pE1 first element
+   * @param pE2 second element
+   */
+  @Override
+  public void union(T pE1, T pE2) {
+
+    Preconditions.checkNotNull(pE1);
+    Preconditions.checkNotNull(pE2);
+
+    if (pE1.equals(pE2)) {
+      addElementAsNewSet(pE1);
+    } else {
+      Set<T> canonicalElements = mapOfSets.keySet();
+
+      if (canonicalElements.contains(pE1)) {
+        if (canonicalElements.contains(pE2)) {
+          mergeExistingSets(pE1, pE2);
+        } else {
+          addElementToExistingSet(pE2, pE1);
+        }
+      } else if (canonicalElements.contains(pE2)) {
+        addElementToExistingSet(pE1, pE2);
+      } else {
+
+        if (contains(pE1)) {
+          if (contains(pE2)) {
+            mergeExistingSets(find(pE1), find(pE2));
+          } else {
+            addElementToExistingSet(pE2, find(pE1));
+          }
+        } else {
+          addElementAsNewSet(pE1);
+          addElementToExistingSet(pE2, pE1);
+        }
+      }
+    }
+  }
+
+  @SuppressWarnings("unchecked")
+  private void addElementAsNewSet(T pE) {
+
+    if (!contains(pE)) {
+      S newSet = (S) getEmptySet();
+      newSet.add(pE);
+      mapOfSets.put(pE, newSet);
+    }
+  }
+
+  private void addElementToExistingSet(T pE, T pCanon) {
+
+    if (!contains(pE)) {
+      mapOfSets.get(pCanon).add(pE);
+    } else {
+      mergeExistingSets(find(pE), pCanon);
+    }
+  }
+
+  // pE1 will be new canonical element only if its set is actually bigger, otherwise pE2 new canon
+  private void mergeExistingSets(T pE1, T pE2) {
+
+    S set1 = mapOfSets.get(pE1);
+    S set2 = mapOfSets.get(pE2);
+
+    assert set1 != null;
+    assert set2 != null;
+
+    int size1 = set1.size();
+    int size2 = set2.size();
+
+    if (size1 > size2) {
+      set1.addAll(set2);
+      assert mapOfSets.remove(pE2, set2);
+    } else {
+      set2.addAll(set1);
+      assert mapOfSets.remove(pE1, set1);
+    }
+  }
+
+  /**
+   * Provides a {@link Collection} containing all current subsets.
+   *
+   * @return {@link Collection} containing all current subsets
+   */
+  @Override
+  public Collection<S> getAllSubsets() {
+    return mapOfSets.values();
+  }
+
+  /**
+   * Checks whether the provided element is contained in any current subset and returns true or
+   * false accordingly.
+   *
+   * @param pE element to be searched for
+   * @return true if contained, false if not
+   */
+  @Override
+  public boolean contains(T pE) {
+
+    Preconditions.checkNotNull(pE);
+
+    for (S current : mapOfSets.values()) {
+      if (current.contains(pE)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  protected abstract Set<T> getEmptySet();
+
+  protected abstract Map<T, Set<T>> getEmptyMap();
+}

src/org/sosy_lab/common/collect/union_find/AbstractImmutableParentPointerTreeBuilder.java

@@ -0,0 +1,80 @@
+// This file is part of SoSy-Lab Common,
+// a library of useful utilities:
+// https://github.com/sosy-lab/java-common-lib
+//
+// SPDX-FileCopyrightText: 2026 Dirk Beyer <https://www.sosy-lab.org>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package org.sosy_lab.common.collect.union_find;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import com.google.errorprone.annotations.Immutable;
+import java.util.Collection;
+import java.util.Set;
+import org.sosy_lab.common.collect.union_find.ParentPointerTreeUnionFind.UnionType;
+
+/**
+ * Abstract builder class which first collects the data in a mutable Union-Find and converts it to
+ * an immutable Union-Find when {@code build()} is called. From then onward, previously modifying
+ * methods will not cause further modifications to the Union-Find instance inside. See documentation
+ * in {@link ParentPointerTreeUnionFind} for explanations on {@code union()}, {@code add()} and
+ * {@code addAll()} as the methods in this builder simply pass to their aforementioned namesakes.
+ *
+ * @param <T> type of elements added to the Union-Find
+ */
+@Immutable(containerOf = "T")
+public abstract class AbstractImmutableParentPointerTreeBuilder<T> {
+
+  // union-find not immutable but only used internally and never mutated passed outward
+  // build() returns an immutable union-find that contains a copy of this union-find's map
+  @SuppressWarnings("Immutable")
+  final ParentPointerTreeUnionFind<T> unionFind;
+
+  // prevents further modifications after build()
+  // is never modified once having been switched to false
+  @SuppressWarnings("Immutable")
+  boolean modificationsAllowed;
+
+  protected AbstractImmutableParentPointerTreeBuilder(UnionType pUnionType) {
+    unionFind = new ParentPointerTreeUnionFind<>(pUnionType);
+    modificationsAllowed = true;
+  }
+
+  @CanIgnoreReturnValue
+  public AbstractImmutableParentPointerTreeBuilder<T> union(T pE1, T pE2) {
+
+    if (modificationsAllowed) {
+
+      unionFind.union(pE1, pE2);
+    }
+
+    return this;
+  }
+
+  @CanIgnoreReturnValue
+  public AbstractImmutableParentPointerTreeBuilder<T> add(Set<T> pSet) {
+
+    if (modificationsAllowed) {
+
+      unionFind.add(pSet);
+    }
+
+    return this;
+  }
+
+  @CanIgnoreReturnValue
+  public AbstractImmutableParentPointerTreeBuilder<T> addAll(Collection<Set<T>> pSets) {
+
+    if (modificationsAllowed) {
+
+      unionFind.addAll(pSets);
+    }
+
+    return this;
+  }
+
+  // get map from mutable Union-Find instance and convert to immutable map, then pass to constructor
+  // set modificationsAllowed to false!!
+  public abstract AbstractImmutableUnionFind<T> build();
+}

src/org/sosy_lab/common/collect/union_find/AbstractImmutableSortedUnionFind.java

@@ -0,0 +1,20 @@
+// This file is part of SoSy-Lab Common,
+// a library of useful utilities:
+// https://github.com/sosy-lab/java-common-lib
+//
+// SPDX-FileCopyrightText: 2026 Dirk Beyer <https://www.sosy-lab.org>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package org.sosy_lab.common.collect.union_find;
+
+import com.google.errorprone.annotations.Immutable;
+
+/**
+ * An abstract class for sorted immutable Union-Find implementations.
+ *
+ * @param <T> type of elements added to the Union-Find. Must be comparable.
+ */
+@Immutable(containerOf = "T")
+public abstract class AbstractImmutableSortedUnionFind<T extends Comparable<T>>
+    extends AbstractImmutableUnionFind<T> implements SortedUnionFind<T> {}

src/org/sosy_lab/common/collect/union_find/AbstractImmutableUnionFind.java

@@ -0,0 +1,28 @@
+// This file is part of SoSy-Lab Common,
+// a library of useful utilities:
+// https://github.com/sosy-lab/java-common-lib
+//
+// SPDX-FileCopyrightText: 2026 Dirk Beyer <https://www.sosy-lab.org>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package org.sosy_lab.common.collect.union_find;
+
+import com.google.errorprone.annotations.DoNotCall;
+import com.google.errorprone.annotations.Immutable;
+
+/**
+ * An abstract class for immutable Union-Find implementations.
+ *
+ * @param <T> type of elements added to the Union-Find
+ */
+@Immutable(containerOf = "T")
+public abstract class AbstractImmutableUnionFind<T> implements UnionFind<T> {
+
+  @Deprecated
+  @Override
+  @DoNotCall
+  public final void union(T pE1, T pE2) {
+    throw new UnsupportedOperationException();
+  }
+}

src/org/sosy_lab/common/collect/union_find/AbstractTreeNode.java

@@ -0,0 +1,55 @@
+// This file is part of SoSy-Lab Common,
+// a library of useful utilities:
+// https://github.com/sosy-lab/java-common-lib
+//
+// SPDX-FileCopyrightText: 2026 Dirk Beyer <https://www.sosy-lab.org>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package org.sosy_lab.common.collect.union_find;
+
+/**
+ * An abstract class of nodes from which a simple parent pointer tree can be built.
+ *
+ * @param <T> type of elements each node holds as value
+ */
+public abstract class AbstractTreeNode<T> {
+
+  private AbstractTreeNode<T> parent;
+  private final T value;
+
+  /**
+   * Constructor for a root node. The parent variable points to itself, thus indicating this is a
+   * root node. If appended to another tree, parent can be reallocated to the new parent node, while
+   * the current node simply functions as a non-root node from then on.
+   *
+   * @param pValue element to be stored in the node
+   */
+  protected AbstractTreeNode(T pValue) {
+    parent = this;
+    value = pValue;
+  }
+
+  /**
+   * Constructor for a non-root node.
+   *
+   * @param pParent pParent node (can be root or non-root)
+   * @param pValue element to be stored in the node
+   */
+  protected AbstractTreeNode(AbstractTreeNode<T> pParent, T pValue) {
+    parent = pParent;
+    value = pValue;
+  }
+
+  public AbstractTreeNode<T> getParent() {
+    return parent;
+  }
+
+  public void setParent(AbstractTreeNode<T> pParent) {
+    parent = pParent;
+  }
+
+  public T getValue() {
+    return value;
+  }
+}