com.google.javascript.jscomp.graph.UnionFind Maven / Gradle / Ivy
/*
* Copyright 2008 The Closure Compiler Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.javascript.jscomp.graph;
import com.google.common.annotations.GwtCompatible;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableSet;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.util.Set;
/**
* Union-Find is a classical algorithm used to find connected components in
* graph theory.
*
* Each equivalence class has a representative element that is chosen
* arbitrarily and is used to determine if two elements are members of the same
* class.
*
*
See
* algorithmist for more detail.
*
* @param element type
*/
@GwtCompatible
public interface UnionFind {
/**
* Adds the given element to a new set if it is not already in a set.
*
* @throws UnsupportedOperationException if the add operation is not
* supported by this union-find.
*/
public void add(E e);
/**
* Unions the equivalence classes of {@code a} and {@code b} and returns the representative of the
* resulting equivalence class. The elements will be added if they are not already present.
*
* @throws UnsupportedOperationException if the add operation is not supported by this union-find.
*/
@CanIgnoreReturnValue
public E union(E a, E b);
/** Returns the representative of the equivalence class of {@code e}. */
public E find(E e);
/**
* Returns true if {@code a} and {@code b} belong to the same equivalence
* class.
*
* @throws IllegalArgumentException if any argument is not an element of this
* structure.
*/
public boolean areEquivalent(E a, E b);
/** Returns an unmodifiable set of all elements added to the UnionFind. */
public Set elements();
/**
* Returns an immutable collection containing all equivalence classes. The returned collection
* represents a snapshot of the current state and will not reflect changes made to the data
* structure.
*/
public ImmutableList> allEquivalenceClasses();
/**
* Returns the elements in the same equivalence class as {@code value}.
*
* @return an unmodifiable view. As equivalence classes are merged, this set
* will reflect those changes.
* @throws IllegalArgumentException if a requested element does not belong
* to the structure.
*/
public Set findAll(final E value);
}