equivalence-0.2.3: Maintaining an equivalence relation implemented as union-find using STT.

Portability unknown unknown Patrick Bahr Safe-Infered

Data.Equivalence.STT

Description

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.

Synopsis

# Equivalence Relation

data Equiv s c a Source

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`.

data Class s c a Source

Instances

 (Monad m, Ord v) => MonadEquiv (Class s d v) v d (EquivT s d v m)

Arguments

 :: Monad m => (a -> c) used to construct an equivalence class descriptor for a singleton class -> (c -> c -> c) used to combine the equivalence class descriptor of two classes which are meant to be combined. -> STT s m (Equiv s c a)

This function constructs the initial data structure for maintaining an equivalence relation. That is it represents, the fines (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

getClass :: (Monad m, Ord a) => Equiv s c a -> a -> STT s m (Class s c a)Source

This function provides the equivalence class the given element is contained in.

combine :: (Monad m, Ord a) => Equiv s c a -> Class s c a -> Class s c a -> STT s m (Class s c a)Source

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.

combineAll :: (Monad m, Ord a) => Equiv s c a -> [Class s c a] -> STT s m ()Source

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

same :: (Monad m, Ord a) => Equiv s c a -> Class s c a -> Class s c a -> STT s m BoolSource

This function decides whether the two given equivalence classes are the same.

desc :: (Monad m, Ord a) => Equiv s c a -> Class s c a -> STT s m cSource

This function returns the descriptor of the given equivalence class.

remove :: (Monad m, Ord a) => Equiv s c a -> Class s c a -> STT s m BoolSource

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

# Operations on Elements

equate :: (Monad m, Ord a) => Equiv s c a -> a -> a -> STT s m ()Source

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

equateAll :: (Monad m, Ord a) => Equiv s c a -> [a] -> STT s m ()Source

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

equivalent :: (Monad m, Ord a) => Equiv s c a -> a -> a -> STT s m BoolSource

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

classDesc :: (Monad m, Ord a) => Equiv s c a -> a -> STT s m cSource

This function returns the descriptor of the given element's equivalence class.

removeClass :: (Monad m, Ord a) => Equiv s c a -> a -> STT s m BoolSource

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