1 //===- llvm/ADT/EquivalenceClasses.h - Generic Equiv. Classes ---*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // Generic implementation of equivalence classes through the use Tarjan's
11 // efficient union-find algorithm.
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_ADT_EQUIVALENCECLASSES_H
16 #define LLVM_ADT_EQUIVALENCECLASSES_H
26 /// EquivalenceClasses - This represents a collection of equivalence classes and
27 /// supports three efficient operations: insert an element into a class of its
28 /// own, union two classes, and find the class for a given element. In
29 /// addition to these modification methods, it is possible to iterate over all
30 /// of the equivalence classes and all of the elements in a class.
32 /// This implementation is an efficient implementation that only stores one copy
33 /// of the element being indexed per entry in the set, and allows any arbitrary
34 /// type to be indexed (as long as it can be ordered with operator<).
36 /// Here is a simple example using integers:
39 /// EquivalenceClasses<int> EC;
40 /// EC.unionSets(1, 2); // insert 1, 2 into the same set
41 /// EC.insert(4); EC.insert(5); // insert 4, 5 into own sets
42 /// EC.unionSets(5, 1); // merge the set for 1 with 5's set.
44 /// for (EquivalenceClasses<int>::iterator I = EC.begin(), E = EC.end();
45 /// I != E; ++I) { // Iterate over all of the equivalence sets.
46 /// if (!I->isLeader()) continue; // Ignore non-leader sets.
47 /// for (EquivalenceClasses<int>::member_iterator MI = EC.member_begin(I);
48 /// MI != EC.member_end(); ++MI) // Loop over members in this set.
49 /// cerr << *MI << " "; // Print member.
50 /// cerr << "\n"; // Finish set.
54 /// This example prints:
58 template <class ElemTy>
59 class EquivalenceClasses {
60 /// ECValue - The EquivalenceClasses data structure is just a set of these.
61 /// Each of these represents a relation for a value. First it stores the
62 /// value itself, which provides the ordering that the set queries. Next, it
63 /// provides a "next pointer", which is used to enumerate all of the elements
64 /// in the unioned set. Finally, it defines either a "end of list pointer" or
65 /// "leader pointer" depending on whether the value itself is a leader. A
66 /// "leader pointer" points to the node that is the leader for this element,
67 /// if the node is not a leader. A "end of list pointer" points to the last
68 /// node in the list of members of this list. Whether or not a node is a
69 /// leader is determined by a bit stolen from one of the pointers.
71 friend class EquivalenceClasses;
73 mutable const ECValue *Leader, *Next;
76 // ECValue ctor - Start out with EndOfList pointing to this node, Next is
77 // Null, isLeader = true.
78 ECValue(const ElemTy &Elt)
79 : Leader(this), Next((ECValue*)(intptr_t)1), Data(Elt) {}
81 const ECValue *getLeader() const {
82 if (isLeader()) return this;
83 if (Leader->isLeader()) return Leader;
85 return Leader = Leader->getLeader();
88 const ECValue *getEndOfList() const {
89 assert(isLeader() && "Cannot get the end of a list for a non-leader!");
93 void setNext(const ECValue *NewNext) const {
94 assert(getNext() == nullptr && "Already has a next pointer!");
95 Next = (const ECValue*)((intptr_t)NewNext | (intptr_t)isLeader());
99 ECValue(const ECValue &RHS) : Leader(this), Next((ECValue*)(intptr_t)1),
101 // Only support copying of singleton nodes.
102 assert(RHS.isLeader() && RHS.getNext() == nullptr && "Not a singleton!");
105 bool operator<(const ECValue &UFN) const { return Data < UFN.Data; }
107 bool isLeader() const { return (intptr_t)Next & 1; }
108 const ElemTy &getData() const { return Data; }
110 const ECValue *getNext() const {
111 return (ECValue*)((intptr_t)Next & ~(intptr_t)1);
115 bool operator<(const T &Val) const { return Data < Val; }
118 /// TheMapping - This implicitly provides a mapping from ElemTy values to the
119 /// ECValues, it just keeps the key as part of the value.
120 std::set<ECValue> TheMapping;
123 EquivalenceClasses() = default;
124 EquivalenceClasses(const EquivalenceClasses &RHS) {
128 const EquivalenceClasses &operator=(const EquivalenceClasses &RHS) {
130 for (iterator I = RHS.begin(), E = RHS.end(); I != E; ++I)
132 member_iterator MI = RHS.member_begin(I);
133 member_iterator LeaderIt = member_begin(insert(*MI));
134 for (++MI; MI != member_end(); ++MI)
135 unionSets(LeaderIt, member_begin(insert(*MI)));
140 //===--------------------------------------------------------------------===//
141 // Inspection methods
144 /// iterator* - Provides a way to iterate over all values in the set.
145 using iterator = typename std::set<ECValue>::const_iterator;
147 iterator begin() const { return TheMapping.begin(); }
148 iterator end() const { return TheMapping.end(); }
150 bool empty() const { return TheMapping.empty(); }
152 /// member_* Iterate over the members of an equivalence class.
153 class member_iterator;
154 member_iterator member_begin(iterator I) const {
155 // Only leaders provide anything to iterate over.
156 return member_iterator(I->isLeader() ? &*I : nullptr);
158 member_iterator member_end() const {
159 return member_iterator(nullptr);
162 /// findValue - Return an iterator to the specified value. If it does not
163 /// exist, end() is returned.
164 iterator findValue(const ElemTy &V) const {
165 return TheMapping.find(V);
168 /// getLeaderValue - Return the leader for the specified value that is in the
169 /// set. It is an error to call this method for a value that is not yet in
170 /// the set. For that, call getOrInsertLeaderValue(V).
171 const ElemTy &getLeaderValue(const ElemTy &V) const {
172 member_iterator MI = findLeader(V);
173 assert(MI != member_end() && "Value is not in the set!");
177 /// getOrInsertLeaderValue - Return the leader for the specified value that is
178 /// in the set. If the member is not in the set, it is inserted, then
180 const ElemTy &getOrInsertLeaderValue(const ElemTy &V) {
181 member_iterator MI = findLeader(insert(V));
182 assert(MI != member_end() && "Value is not in the set!");
186 /// getNumClasses - Return the number of equivalence classes in this set.
187 /// Note that this is a linear time operation.
188 unsigned getNumClasses() const {
190 for (iterator I = begin(), E = end(); I != E; ++I)
191 if (I->isLeader()) ++NC;
195 //===--------------------------------------------------------------------===//
198 /// insert - Insert a new value into the union/find set, ignoring the request
199 /// if the value already exists.
200 iterator insert(const ElemTy &Data) {
201 return TheMapping.insert(ECValue(Data)).first;
204 /// findLeader - Given a value in the set, return a member iterator for the
205 /// equivalence class it is in. This does the path-compression part that
206 /// makes union-find "union findy". This returns an end iterator if the value
207 /// is not in the equivalence class.
208 member_iterator findLeader(iterator I) const {
209 if (I == TheMapping.end()) return member_end();
210 return member_iterator(I->getLeader());
212 member_iterator findLeader(const ElemTy &V) const {
213 return findLeader(TheMapping.find(V));
216 /// union - Merge the two equivalence sets for the specified values, inserting
217 /// them if they do not already exist in the equivalence set.
218 member_iterator unionSets(const ElemTy &V1, const ElemTy &V2) {
219 iterator V1I = insert(V1), V2I = insert(V2);
220 return unionSets(findLeader(V1I), findLeader(V2I));
222 member_iterator unionSets(member_iterator L1, member_iterator L2) {
223 assert(L1 != member_end() && L2 != member_end() && "Illegal inputs!");
224 if (L1 == L2) return L1; // Unifying the same two sets, noop.
226 // Otherwise, this is a real union operation. Set the end of the L1 list to
227 // point to the L2 leader node.
228 const ECValue &L1LV = *L1.Node, &L2LV = *L2.Node;
229 L1LV.getEndOfList()->setNext(&L2LV);
231 // Update L1LV's end of list pointer.
232 L1LV.Leader = L2LV.getEndOfList();
234 // Clear L2's leader flag:
235 L2LV.Next = L2LV.getNext();
237 // L2's leader is now L1.
242 // isEquivalent - Return true if V1 is equivalent to V2. This can happen if
243 // V1 is equal to V2 or if they belong to one equivalence class.
244 bool isEquivalent(const ElemTy &V1, const ElemTy &V2) const {
245 // Fast path: any element is equivalent to itself.
248 auto It = findLeader(V1);
249 return It != member_end() && It == findLeader(V2);
252 class member_iterator : public std::iterator<std::forward_iterator_tag,
253 const ElemTy, ptrdiff_t> {
254 friend class EquivalenceClasses;
256 using super = std::iterator<std::forward_iterator_tag,
257 const ElemTy, ptrdiff_t>;
262 using size_type = size_t;
263 using pointer = typename super::pointer;
264 using reference = typename super::reference;
266 explicit member_iterator() = default;
267 explicit member_iterator(const ECValue *N) : Node(N) {}
269 reference operator*() const {
270 assert(Node != nullptr && "Dereferencing end()!");
271 return Node->getData();
273 pointer operator->() const { return &operator*(); }
275 member_iterator &operator++() {
276 assert(Node != nullptr && "++'d off the end of the list!");
277 Node = Node->getNext();
281 member_iterator operator++(int) { // postincrement operators.
282 member_iterator tmp = *this;
287 bool operator==(const member_iterator &RHS) const {
288 return Node == RHS.Node;
290 bool operator!=(const member_iterator &RHS) const {
291 return Node != RHS.Node;
296 } // end namespace llvm
298 #endif // LLVM_ADT_EQUIVALENCECLASSES_H