HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Moduleequivalence-0.4.1Haskell2010

Data.Equivalence.STT

This is an implementation of Tarjan's Union-Find algorithm (Robert E. Tarjan. "Efficiency of a Good But Not Linear Set Union Algorithm", JACM 22(2), 1975) in order to maintain an equivalence relation.

This implementation is a port of the union-find package using the ST monad transformer (instead of the IO monad).

The implementation is based on mutable references. Each equivalence class has exactly one member that serves as its representative element. Every element either is the representative element of its equivalence class or points to another element in the same equivalence class. Equivalence testing thus consists of following the pointers to the representative elements and then comparing these for identity.

The algorithm performs lazy path compression. That is, whenever we walk along a path greater than length 1 we automatically update the pointers along the path to directly point to the representative element. Consequently future lookups will be have a path length of at most 1.

Each equivalence class remains a descriptor, i.e. some piece of data attached to an equivalence class which is combined when two classes are unioned.

  • 2 types
  • 14 values

Equivalence Relation

3 declarations
datadata Equiv s c a
#

This is the top-level data structure that represents an equivalence relation. An equivalence relation of type Equiv s c a lives in the state space indexed by s, contains equivalence class descriptors of type c and has elements of type a.

newtypenewtype Class s c a
#

Abstract representation of an equivalence class.

Instances1MonadEquiv
valueleastEquiv
  1. :: (Monad m, Applicative m)
  2. => (a -> c)

    Used to construct an equivalence class descriptor for a singleton class.

  3. -> (c -> c -> c)

    Used to combine the equivalence class descriptor of two classes which are meant to be combined.

  4. -> STT s m (Equiv s c a)
#

This function constructs the initial data structure for maintaining an equivalence relation. That is, it represents the finest (or least) equivalence class (of the set of all elements of type a). The arguments are used to maintain equivalence class descriptors.

Operations on Equivalence Classes

6 declarations
valuecombine
  1. :: (Monad m, Applicative m, Ord a)
  2. => Equiv s c a
  3. -> Class s c a
  4. -> Class s c a
  5. -> STT s m (Class s c a)
#

This function combines the two given equivalence classes. Afterwards both arguments represent the same equivalence class! One of it is returned in order to represent the new combined equivalence class.

valuecombineAll
  1. :: (Monad m, Applicative m, Ord a)
  2. => Equiv s c a
  3. -> [Class s c a]
  4. -> STT s m ()
#

This function combines all equivalence classes in the given list. Afterwards all elements in the argument list represent the same equivalence class!

valueremove
  1. :: (Monad m, Applicative m, Ord a)
  2. => Equiv s c a
  3. -> Class s c a
  4. -> STT s m Bool
#

This function removes the given equivalence class. If the equivalence class does not exist anymore, False is returned; otherwise True.

Operations on Elements

7 declarations
valueequate
  1. :: (Monad m, Applicative m, Ord a)
  2. => Equiv s c a
  3. -> a
  4. -> a
  5. -> STT s m ()
#

This function equates the two given elements. That is, it unions the equivalence classes of the two elements and combines their descriptor.

valueequateAll
  1. :: (Monad m, Applicative m, Ord a)
  2. => Equiv s c a
  3. -> [a]
  4. -> STT s m ()
#

This function equates the element in the given list. That is, it unions the equivalence classes of the elements and combines their descriptor.

valueequivalent
  1. :: (Monad m, Applicative m, Ord a)
  2. => Equiv s c a
  3. -> a
  4. -> a
  5. -> STT s m Bool
#

This function decides whether the two given elements are in the same equivalence class according to the given equivalence relation representation.

valueremoveClass
  1. :: (Monad m, Applicative m, Ord a)
  2. => Equiv s c a
  3. -> a
  4. -> STT s m Bool
#

This function removes the equivalence class of the given element. If there is no corresponding equivalence class, False is returned; otherwise True.