EIC code displayed by LXR master/​include/​llvm/​ADT/​EquivalenceClasses.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-05-10 08:43:04

 //===- llvm/ADT/EquivalenceClasses.h - Generic Equiv. Classes ---*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 ///
 /// \file
 /// Generic implementation of equivalence classes through the use Tarjan's
 /// efficient union-find algorithm.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_ADT_EQUIVALENCECLASSES_H
 #define LLVM_ADT_EQUIVALENCECLASSES_H
 
 #include <cassert>
 #include <cstddef>
 #include <cstdint>
 #include <iterator>
 #include <set>
 
 namespace llvm {
 
 /// EquivalenceClasses - This represents a collection of equivalence classes and
 /// supports three efficient operations: insert an element into a class of its
 /// own, union two classes, and find the class for a given element.  In
 /// addition to these modification methods, it is possible to iterate over all
 /// of the equivalence classes and all of the elements in a class.
 ///
 /// This implementation is an efficient implementation that only stores one copy
 /// of the element being indexed per entry in the set, and allows any arbitrary
 /// type to be indexed (as long as it can be ordered with operator< or a
 /// comparator is provided).
 ///
 /// Here is a simple example using integers:
 ///
 /// \code
 ///  EquivalenceClasses<int> EC;
 ///  EC.unionSets(1, 2);                // insert 1, 2 into the same set
 ///  EC.insert(4); EC.insert(5);        // insert 4, 5 into own sets
 ///  EC.unionSets(5, 1);                // merge the set for 1 with 5's set.
 ///
 ///  for (EquivalenceClasses<int>::iterator I = EC.begin(), E = EC.end();
 ///       I != E; ++I) {           // Iterate over all of the equivalence sets.
 ///    if (!I->isLeader()) continue;   // Ignore non-leader sets.
 ///    for (EquivalenceClasses<int>::member_iterator MI = EC.member_begin(I);
 ///         MI != EC.member_end(); ++MI)   // Loop over members in this set.
 ///      cerr << *MI << " ";  // Print member.
 ///    cerr << "\n";   // Finish set.
 ///  }
 /// \endcode
 ///
 /// This example prints:
 ///   4
 ///   5 1 2
 ///
 template <class ElemTy, class Compare = std::less<ElemTy>>
 class EquivalenceClasses {
   /// ECValue - The EquivalenceClasses data structure is just a set of these.
   /// Each of these represents a relation for a value.  First it stores the
   /// value itself, which provides the ordering that the set queries.  Next, it
   /// provides a "next pointer", which is used to enumerate all of the elements
   /// in the unioned set.  Finally, it defines either a "end of list pointer" or
   /// "leader pointer" depending on whether the value itself is a leader.  A
   /// "leader pointer" points to the node that is the leader for this element,
   /// if the node is not a leader.  A "end of list pointer" points to the last
   /// node in the list of members of this list.  Whether or not a node is a
   /// leader is determined by a bit stolen from one of the pointers.
   class ECValue {
     friend class EquivalenceClasses;
 
     mutable const ECValue *Leader, *Next;
     ElemTy Data;
 
     // ECValue ctor - Start out with EndOfList pointing to this node, Next is
     // Null, isLeader = true.
     ECValue(const ElemTy &Elt)
       : Leader(this), Next((ECValue*)(intptr_t)1), Data(Elt) {}
 
     const ECValue *getLeader() const {
       if (isLeader()) return this;
       if (Leader->isLeader()) return Leader;
       // Path compression.
       return Leader = Leader->getLeader();
     }
 
     const ECValue *getEndOfList() const {
       assert(isLeader() && "Cannot get the end of a list for a non-leader!");
       return Leader;
     }
 
     void setNext(const ECValue *NewNext) const {
       assert(getNext() == nullptr && "Already has a next pointer!");
       Next = (const ECValue*)((intptr_t)NewNext | (intptr_t)isLeader());
     }
 
   public:
     ECValue(const ECValue &RHS) : Leader(this), Next((ECValue*)(intptr_t)1),
                                   Data(RHS.Data) {
       // Only support copying of singleton nodes.
       assert(RHS.isLeader() && RHS.getNext() == nullptr && "Not a singleton!");
     }
 
     bool isLeader() const { return (intptr_t)Next & 1; }
     const ElemTy &getData() const { return Data; }
 
     const ECValue *getNext() const {
       return (ECValue*)((intptr_t)Next & ~(intptr_t)1);
     }
   };
 
   /// A wrapper of the comparator, to be passed to the set.
   struct ECValueComparator {
     using is_transparent = void;
 
     ECValueComparator() : compare(Compare()) {}
 
     bool operator()(const ECValue &lhs, const ECValue &rhs) const {
       return compare(lhs.Data, rhs.Data);
     }
 
     template <typename T>
     bool operator()(const T &lhs, const ECValue &rhs) const {
       return compare(lhs, rhs.Data);
     }
 
     template <typename T>
     bool operator()(const ECValue &lhs, const T &rhs) const {
       return compare(lhs.Data, rhs);
     }
 
     const Compare compare;
   };
 
   /// TheMapping - This implicitly provides a mapping from ElemTy values to the
   /// ECValues, it just keeps the key as part of the value.
   std::set<ECValue, ECValueComparator> TheMapping;
 
 public:
   EquivalenceClasses() = default;
   EquivalenceClasses(const EquivalenceClasses &RHS) {
     operator=(RHS);
   }
 
   const EquivalenceClasses &operator=(const EquivalenceClasses &RHS) {
     TheMapping.clear();
     for (iterator I = RHS.begin(), E = RHS.end(); I != E; ++I)
       if (I->isLeader()) {
         member_iterator MI = RHS.member_begin(I);
         member_iterator LeaderIt = member_begin(insert(*MI));
         for (++MI; MI != member_end(); ++MI)
           unionSets(LeaderIt, member_begin(insert(*MI)));
       }
     return *this;
   }
 
   //===--------------------------------------------------------------------===//
   // Inspection methods
   //
 
   /// iterator* - Provides a way to iterate over all values in the set.
   using iterator =
       typename std::set<ECValue, ECValueComparator>::const_iterator;
 
   iterator begin() const { return TheMapping.begin(); }
   iterator end() const { return TheMapping.end(); }
 
   bool empty() const { return TheMapping.empty(); }
 
   /// member_* Iterate over the members of an equivalence class.
   class member_iterator;
   member_iterator member_begin(iterator I) const {
     // Only leaders provide anything to iterate over.
     return member_iterator(I->isLeader() ? &*I : nullptr);
   }
   member_iterator member_end() const {
     return member_iterator(nullptr);
   }
 
   /// findValue - Return an iterator to the specified value.  If it does not
   /// exist, end() is returned.
   iterator findValue(const ElemTy &V) const {
     return TheMapping.find(V);
   }
 
   /// getLeaderValue - Return the leader for the specified value that is in the
   /// set.  It is an error to call this method for a value that is not yet in
   /// the set.  For that, call getOrInsertLeaderValue(V).
   const ElemTy &getLeaderValue(const ElemTy &V) const {
     member_iterator MI = findLeader(V);
     assert(MI != member_end() && "Value is not in the set!");
     return *MI;
   }
 
   /// getOrInsertLeaderValue - Return the leader for the specified value that is
   /// in the set.  If the member is not in the set, it is inserted, then
   /// returned.
   const ElemTy &getOrInsertLeaderValue(const ElemTy &V) {
     member_iterator MI = findLeader(insert(V));
     assert(MI != member_end() && "Value is not in the set!");
     return *MI;
   }
 
   /// getNumClasses - Return the number of equivalence classes in this set.
   /// Note that this is a linear time operation.
   unsigned getNumClasses() const {
     unsigned NC = 0;
     for (iterator I = begin(), E = end(); I != E; ++I)
       if (I->isLeader()) ++NC;
     return NC;
   }
 
   //===--------------------------------------------------------------------===//
   // Mutation methods
 
   /// insert - Insert a new value into the union/find set, ignoring the request
   /// if the value already exists.
   iterator insert(const ElemTy &Data) {
     return TheMapping.insert(ECValue(Data)).first;
   }
 
   /// findLeader - Given a value in the set, return a member iterator for the
   /// equivalence class it is in.  This does the path-compression part that
   /// makes union-find "union findy".  This returns an end iterator if the value
   /// is not in the equivalence class.
   member_iterator findLeader(iterator I) const {
     if (I == TheMapping.end()) return member_end();
     return member_iterator(I->getLeader());
   }
   member_iterator findLeader(const ElemTy &V) const {
     return findLeader(TheMapping.find(V));
   }
 
   /// union - Merge the two equivalence sets for the specified values, inserting
   /// them if they do not already exist in the equivalence set.
   member_iterator unionSets(const ElemTy &V1, const ElemTy &V2) {
     iterator V1I = insert(V1), V2I = insert(V2);
     return unionSets(findLeader(V1I), findLeader(V2I));
   }
   member_iterator unionSets(member_iterator L1, member_iterator L2) {
     assert(L1 != member_end() && L2 != member_end() && "Illegal inputs!");
     if (L1 == L2) return L1;   // Unifying the same two sets, noop.
 
     // Otherwise, this is a real union operation.  Set the end of the L1 list to
     // point to the L2 leader node.
     const ECValue &L1LV = *L1.Node, &L2LV = *L2.Node;
     L1LV.getEndOfList()->setNext(&L2LV);
 
     // Update L1LV's end of list pointer.
     L1LV.Leader = L2LV.getEndOfList();
 
     // Clear L2's leader flag:
     L2LV.Next = L2LV.getNext();
 
     // L2's leader is now L1.
     L2LV.Leader = &L1LV;
     return L1;
   }
 
   // isEquivalent - Return true if V1 is equivalent to V2. This can happen if
   // V1 is equal to V2 or if they belong to one equivalence class.
   bool isEquivalent(const ElemTy &V1, const ElemTy &V2) const {
     // Fast path: any element is equivalent to itself.
     if (V1 == V2)
       return true;
     auto It = findLeader(V1);
     return It != member_end() && It == findLeader(V2);
   }
 
   class member_iterator {
     friend class EquivalenceClasses;
 
     const ECValue *Node;
 
   public:
     using iterator_category = std::forward_iterator_tag;
     using value_type = const ElemTy;
     using size_type = std::size_t;
     using difference_type = std::ptrdiff_t;
     using pointer = value_type *;
     using reference = value_type &;
 
     explicit member_iterator() = default;
     explicit member_iterator(const ECValue *N) : Node(N) {}
 
     reference operator*() const {
       assert(Node != nullptr && "Dereferencing end()!");
       return Node->getData();
     }
     pointer operator->() const { return &operator*(); }
 
     member_iterator &operator++() {
       assert(Node != nullptr && "++'d off the end of the list!");
       Node = Node->getNext();
       return *this;
     }
 
     member_iterator operator++(int) {    // postincrement operators.
       member_iterator tmp = *this;
       ++*this;
       return tmp;
     }
 
     bool operator==(const member_iterator &RHS) const {
       return Node == RHS.Node;
     }
     bool operator!=(const member_iterator &RHS) const {
       return Node != RHS.Node;
     }
   };
 };
 
 } // end namespace llvm
 
 #endif // LLVM_ADT_EQUIVALENCECLASSES_H

This page was automatically generated by the 2.3.7 LXR engine. The LXR team