contrib/llvm-project/llvm/include/llvm/ADT/EquivalenceClasses.h

   1 //===- llvm/ADT/EquivalenceClasses.h - Generic Equiv. Classes ---*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // Generic implementation of equivalence classes through the use Tarjan's
  10 // efficient union-find algorithm.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_ADT_EQUIVALENCECLASSES_H
  15 #define LLVM_ADT_EQUIVALENCECLASSES_H
  16
  17 #include <cassert>
  18 #include <cstddef>
  19 #include <cstdint>
  20 #include <iterator>
  21 #include <set>
  22
  23 namespace llvm {
  24
  25 /// EquivalenceClasses - This represents a collection of equivalence classes and
  26 /// supports three efficient operations: insert an element into a class of its
  27 /// own, union two classes, and find the class for a given element.  In
  28 /// addition to these modification methods, it is possible to iterate over all
  29 /// of the equivalence classes and all of the elements in a class.
  30 ///
  31 /// This implementation is an efficient implementation that only stores one copy
  32 /// of the element being indexed per entry in the set, and allows any arbitrary
  33 /// type to be indexed (as long as it can be ordered with operator<).
  34 ///
  35 /// Here is a simple example using integers:
  36 ///
  37 /// \code
  38 ///  EquivalenceClasses<int> EC;
  39 ///  EC.unionSets(1, 2);                // insert 1, 2 into the same set
  40 ///  EC.insert(4); EC.insert(5);        // insert 4, 5 into own sets
  41 ///  EC.unionSets(5, 1);                // merge the set for 1 with 5's set.
  42 ///
  43 ///  for (EquivalenceClasses<int>::iterator I = EC.begin(), E = EC.end();
  44 ///       I != E; ++I) {           // Iterate over all of the equivalence sets.
  45 ///    if (!I->isLeader()) continue;   // Ignore non-leader sets.
  46 ///    for (EquivalenceClasses<int>::member_iterator MI = EC.member_begin(I);
  47 ///         MI != EC.member_end(); ++MI)   // Loop over members in this set.
  48 ///      cerr << *MI << " ";  // Print member.
  49 ///    cerr << "\n";   // Finish set.
  50 ///  }
  51 /// \endcode
  52 ///
  53 /// This example prints:
  54 ///   4
  55 ///   5 1 2
  56 ///
  57 template <class ElemTy>
  58 class EquivalenceClasses {
  59   /// ECValue - The EquivalenceClasses data structure is just a set of these.
  60   /// Each of these represents a relation for a value.  First it stores the
  61   /// value itself, which provides the ordering that the set queries.  Next, it
  62   /// provides a "next pointer", which is used to enumerate all of the elements
  63   /// in the unioned set.  Finally, it defines either a "end of list pointer" or
  64   /// "leader pointer" depending on whether the value itself is a leader.  A
  65   /// "leader pointer" points to the node that is the leader for this element,
  66   /// if the node is not a leader.  A "end of list pointer" points to the last
  67   /// node in the list of members of this list.  Whether or not a node is a
  68   /// leader is determined by a bit stolen from one of the pointers.
  69   class ECValue {
  70     friend class EquivalenceClasses;
  71
  72     mutable const ECValue *Leader, *Next;
  73     ElemTy Data;
  74
  75     // ECValue ctor - Start out with EndOfList pointing to this node, Next is
  76     // Null, isLeader = true.
  77     ECValue(const ElemTy &Elt)
  78       : Leader(this), Next((ECValue*)(intptr_t)1), Data(Elt) {}
  79
  80     const ECValue *getLeader() const {
  81       if (isLeader()) return this;
  82       if (Leader->isLeader()) return Leader;
  83       // Path compression.
  84       return Leader = Leader->getLeader();
  85     }
  86
  87     const ECValue *getEndOfList() const {
  88       assert(isLeader() && "Cannot get the end of a list for a non-leader!");
  89       return Leader;
  90     }
  91
  92     void setNext(const ECValue *NewNext) const {
  93       assert(getNext() == nullptr && "Already has a next pointer!");
  94       Next = (const ECValue*)((intptr_t)NewNext | (intptr_t)isLeader());
  95     }
  96
  97   public:
  98     ECValue(const ECValue &RHS) : Leader(this), Next((ECValue*)(intptr_t)1),
  99                                   Data(RHS.Data) {
 100       // Only support copying of singleton nodes.
 101       assert(RHS.isLeader() && RHS.getNext() == nullptr && "Not a singleton!");
 102     }
 103
 104     bool operator<(const ECValue &UFN) const { return Data < UFN.Data; }
 105
 106     bool isLeader() const { return (intptr_t)Next & 1; }
 107     const ElemTy &getData() const { return Data; }
 108
 109     const ECValue *getNext() const {
 110       return (ECValue*)((intptr_t)Next & ~(intptr_t)1);
 111     }
 112
 113     template<typename T>
 114     bool operator<(const T &Val) const { return Data < Val; }
 115   };
 116
 117   /// TheMapping - This implicitly provides a mapping from ElemTy values to the
 118   /// ECValues, it just keeps the key as part of the value.
 119   std::set<ECValue> TheMapping;
 120
 121 public:
 122   EquivalenceClasses() = default;
 123   EquivalenceClasses(const EquivalenceClasses &RHS) {
 124     operator=(RHS);
 125   }
 126
 127   const EquivalenceClasses &operator=(const EquivalenceClasses &RHS) {
 128     TheMapping.clear();
 129     for (iterator I = RHS.begin(), E = RHS.end(); I != E; ++I)
 130       if (I->isLeader()) {
 131         member_iterator MI = RHS.member_begin(I);
 132         member_iterator LeaderIt = member_begin(insert(*MI));
 133         for (++MI; MI != member_end(); ++MI)
 134           unionSets(LeaderIt, member_begin(insert(*MI)));
 135       }
 136     return *this;
 137   }
 138
 139   //===--------------------------------------------------------------------===//
 140   // Inspection methods
 141   //
 142
 143   /// iterator* - Provides a way to iterate over all values in the set.
 144   using iterator = typename std::set<ECValue>::const_iterator;
 145
 146   iterator begin() const { return TheMapping.begin(); }
 147   iterator end() const { return TheMapping.end(); }
 148
 149   bool empty() const { return TheMapping.empty(); }
 150
 151   /// member_* Iterate over the members of an equivalence class.
 152   class member_iterator;
 153   member_iterator member_begin(iterator I) const {
 154     // Only leaders provide anything to iterate over.
 155     return member_iterator(I->isLeader() ? &*I : nullptr);
 156   }
 157   member_iterator member_end() const {
 158     return member_iterator(nullptr);
 159   }
 160
 161   /// findValue - Return an iterator to the specified value.  If it does not
 162   /// exist, end() is returned.
 163   iterator findValue(const ElemTy &V) const {
 164     return TheMapping.find(V);
 165   }
 166
 167   /// getLeaderValue - Return the leader for the specified value that is in the
 168   /// set.  It is an error to call this method for a value that is not yet in
 169   /// the set.  For that, call getOrInsertLeaderValue(V).
 170   const ElemTy &getLeaderValue(const ElemTy &V) const {
 171     member_iterator MI = findLeader(V);
 172     assert(MI != member_end() && "Value is not in the set!");
 173     return *MI;
 174   }
 175
 176   /// getOrInsertLeaderValue - Return the leader for the specified value that is
 177   /// in the set.  If the member is not in the set, it is inserted, then
 178   /// returned.
 179   const ElemTy &getOrInsertLeaderValue(const ElemTy &V) {
 180     member_iterator MI = findLeader(insert(V));
 181     assert(MI != member_end() && "Value is not in the set!");
 182     return *MI;
 183   }
 184
 185   /// getNumClasses - Return the number of equivalence classes in this set.
 186   /// Note that this is a linear time operation.
 187   unsigned getNumClasses() const {
 188     unsigned NC = 0;
 189     for (iterator I = begin(), E = end(); I != E; ++I)
 190       if (I->isLeader()) ++NC;
 191     return NC;
 192   }
 193
 194   //===--------------------------------------------------------------------===//
 195   // Mutation methods
 196
 197   /// insert - Insert a new value into the union/find set, ignoring the request
 198   /// if the value already exists.
 199   iterator insert(const ElemTy &Data) {
 200     return TheMapping.insert(ECValue(Data)).first;
 201   }
 202
 203   /// findLeader - Given a value in the set, return a member iterator for the
 204   /// equivalence class it is in.  This does the path-compression part that
 205   /// makes union-find "union findy".  This returns an end iterator if the value
 206   /// is not in the equivalence class.
 207   member_iterator findLeader(iterator I) const {
 208     if (I == TheMapping.end()) return member_end();
 209     return member_iterator(I->getLeader());
 210   }
 211   member_iterator findLeader(const ElemTy &V) const {
 212     return findLeader(TheMapping.find(V));
 213   }
 214
 215   /// union - Merge the two equivalence sets for the specified values, inserting
 216   /// them if they do not already exist in the equivalence set.
 217   member_iterator unionSets(const ElemTy &V1, const ElemTy &V2) {
 218     iterator V1I = insert(V1), V2I = insert(V2);
 219     return unionSets(findLeader(V1I), findLeader(V2I));
 220   }
 221   member_iterator unionSets(member_iterator L1, member_iterator L2) {
 222     assert(L1 != member_end() && L2 != member_end() && "Illegal inputs!");
 223     if (L1 == L2) return L1;   // Unifying the same two sets, noop.
 224
 225     // Otherwise, this is a real union operation.  Set the end of the L1 list to
 226     // point to the L2 leader node.
 227     const ECValue &L1LV = *L1.Node, &L2LV = *L2.Node;
 228     L1LV.getEndOfList()->setNext(&L2LV);
 229
 230     // Update L1LV's end of list pointer.
 231     L1LV.Leader = L2LV.getEndOfList();
 232
 233     // Clear L2's leader flag:
 234     L2LV.Next = L2LV.getNext();
 235
 236     // L2's leader is now L1.
 237     L2LV.Leader = &L1LV;
 238     return L1;
 239   }
 240
 241   // isEquivalent - Return true if V1 is equivalent to V2. This can happen if
 242   // V1 is equal to V2 or if they belong to one equivalence class.
 243   bool isEquivalent(const ElemTy &V1, const ElemTy &V2) const {
 244     // Fast path: any element is equivalent to itself.
 245     if (V1 == V2)
 246       return true;
 247     auto It = findLeader(V1);
 248     return It != member_end() && It == findLeader(V2);
 249   }
 250
 251   class member_iterator : public std::iterator<std::forward_iterator_tag,
 252                                                const ElemTy, ptrdiff_t> {
 253     friend class EquivalenceClasses;
 254
 255     using super = std::iterator<std::forward_iterator_tag,
 256                                 const ElemTy, ptrdiff_t>;
 257
 258     const ECValue *Node;
 259
 260   public:
 261     using size_type = size_t;
 262     using pointer = typename super::pointer;
 263     using reference = typename super::reference;
 264
 265     explicit member_iterator() = default;
 266     explicit member_iterator(const ECValue *N) : Node(N) {}
 267
 268     reference operator*() const {
 269       assert(Node != nullptr && "Dereferencing end()!");
 270       return Node->getData();
 271     }
 272     pointer operator->() const { return &operator*(); }
 273
 274     member_iterator &operator++() {
 275       assert(Node != nullptr && "++'d off the end of the list!");
 276       Node = Node->getNext();
 277       return *this;
 278     }
 279
 280     member_iterator operator++(int) {    // postincrement operators.
 281       member_iterator tmp = *this;
 282       ++*this;
 283       return tmp;
 284     }
 285
 286     bool operator==(const member_iterator &RHS) const {
 287       return Node == RHS.Node;
 288     }
 289     bool operator!=(const member_iterator &RHS) const {
 290       return Node != RHS.Node;
 291     }
 292   };
 293 };
 294
 295 } // end namespace llvm
 296
 297 #endif // LLVM_ADT_EQUIVALENCECLASSES_H