vmap.h: Enables one to create maps with a virtual base class.
3 * This file is a part of LEMON, a generic C++ optimization library
5 * Copyright (C) 2003-2006
6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
9 * Permission to use, modify and distribute this software is granted
10 * provided that this copyright notice appears in all copies. For
11 * precise terms see the accompanying LICENSE file.
13 * This software is provided "AS IS" with no warranty of any kind,
14 * express or implied, and with no claim as to its suitability for any
19 #ifndef LEMON_UNION_FIND_H
20 #define LEMON_UNION_FIND_H
24 //!\brief Union-Find data structures.
32 #include <lemon/invalid.h>
36 //! \addtogroup auxdat
40 * \brief A \e Union-Find data structure implementation
42 * The class implements the \e Union-Find data structure.
43 * The union operation uses rank heuristic, while
44 * the find operation uses path compression.
45 * This is a very simple but efficient implementation, providing
46 * only four methods: join (union), find, insert and size.
47 * For more features see the \ref UnionFindEnum class.
49 * It is primarily used in Kruskal algorithm for finding minimal
50 * cost spanning tree in a graph.
53 * \pre The elements are automatically added only if the map
54 * given to the constructor was filled with -1's. Otherwise you
55 * need to add all the elements by the \ref insert() method.
56 * \bug It is not clear what the constructor parameter is used for.
59 template <typename T, typename TIntMap>
63 typedef T ElementType;
64 typedef std::pair<int,int> PairType;
67 std::vector<PairType> data;
71 UnionFind(TIntMap& m) : map(m) {}
74 * \brief Returns the index of the element's component.
76 * The method returns the index of the element's component.
77 * This is an integer between zero and the number of inserted elements.
88 while ( (next = data[comp].first) != comp) {
91 while ( (next = data[comp0].first) != comp) {
92 data[comp0].first = comp;
100 * \brief Inserts a new element into the structure.
102 * This method inserts a new element into the data structure.
104 * It is not required to use this method:
105 * if the map given to the constructor was filled
106 * with -1's then it is called automatically
107 * on the first \ref find or \ref join.
109 * The method returns the index of the new component.
115 data.push_back(std::make_pair(n, 1));
121 * \brief Joining the components of element \e a and element \e b.
123 * This is the \e union operation of the Union-Find structure.
124 * Joins the component of element \e a and component of
125 * element \e b. If \e a and \e b are in the same component then
126 * it returns false otherwise it returns true.
137 if ( data[ca].second > data[cb].second ) {
139 data[ca].second += data[cb].second;
143 data[cb].second += data[ca].second;
149 * \brief Returns the size of the component of element \e a.
151 * Returns the size of the component of element \e a.
157 return data[ca].second;
165 /*******************************************************/
168 #ifdef DEVELOPMENT_DOCS
171 * \brief The auxiliary class for the \ref UnionFindEnum class.
173 * In the \ref UnionFindEnum class all components are represented as
175 * Items of these lists are UnionFindEnumItem structures.
177 * The class has four fields:
178 * - T me - the actual element
179 * - IIter parent - the parent of the element in the union-find structure
180 * - int size - the size of the component of the element.
181 * Only valid if the element
182 * is the leader of the component.
183 * - CIter my_class - pointer into the list of components
184 * pointing to the component of the element.
185 * Only valid if the element is the leader of the component.
190 template <typename T>
191 struct UnionFindEnumItem {
193 typedef std::list<UnionFindEnumItem> ItemList;
194 typedef std::list<ItemList> ClassList;
195 typedef typename ItemList::iterator IIter;
196 typedef typename ClassList::iterator CIter;
203 UnionFindEnumItem() {}
204 UnionFindEnumItem(const T &_me, CIter _my_class):
205 me(_me), size(1), my_class(_my_class) {}
210 * \brief A \e Union-Find data structure implementation which
211 * is able to enumerate the components.
213 * The class implements a \e Union-Find data structure
214 * which is able to enumerate the components and the items in
215 * a component. If you don't need this feature then perhaps it's
216 * better to use the \ref UnionFind class which is more efficient.
218 * The union operation uses rank heuristic, while
219 * the find operation uses path compression.
222 * need to add all the elements by the \ref insert() method.
226 template <typename T, template <typename Item> class Map>
227 class UnionFindEnum {
229 typedef std::list<UnionFindEnumItem<T> > ItemList;
230 typedef std::list<ItemList> ClassList;
231 typedef typename ItemList::iterator IIter;
232 typedef typename ItemList::const_iterator IcIter;
233 typedef typename ClassList::iterator CIter;
234 typedef typename ClassList::const_iterator CcIter;
237 typedef T ElementType;
238 typedef UnionFindEnumItem<T> ItemType;
239 typedef Map< IIter > MapType;
245 IIter _find(IIter a) const {
248 while( (next = comp->parent) != comp ) {
253 while( (next = comp1->parent) != comp ) {
254 comp1->parent = comp->parent;
261 UnionFindEnum(MapType& _m) : m(_m) {}
265 * \brief Inserts the given element into a new component.
267 * This method creates a new component consisting only of the
271 void insert(const T &a)
275 classes.push_back(ItemList());
276 CIter aclass = classes.end();
279 ItemList &alist = *aclass;
280 alist.push_back(ItemType(a, aclass));
281 IIter ai = alist.begin();
289 * \brief Inserts the given element into the component of the others.
291 * This methods inserts the element \e a into the component of the
295 void insert(const T &a, const T &comp) {
297 IIter clit = _find(m[comp]);
298 ItemList &c = *clit->my_class;
299 c.push_back(ItemType(a,0));
309 * \brief Finds the leader of the component of the given element.
311 * The method returns the leader of the component of the given element.
314 T find(const T &a) const {
315 return _find(m[a])->me;
320 * \brief Joining the component of element \e a and element \e b.
322 * This is the \e union operation of the Union-Find structure.
323 * Joins the component of element \e a and component of
324 * element \e b. If \e a and \e b are in the same component then
325 * returns false else returns true.
328 bool join(T a, T b) {
330 IIter ca = _find(m[a]);
331 IIter cb = _find(m[b]);
337 if ( ca->size > cb->size ) {
339 cb->parent = ca->parent;
340 ca->size += cb->size;
342 ItemList &alist = *ca->my_class;
343 alist.splice(alist.end(),*cb->my_class);
345 classes.erase(cb->my_class);
350 ca->parent = cb->parent;
351 cb->size += ca->size;
353 ItemList &blist = *cb->my_class;
354 blist.splice(blist.end(),*ca->my_class);
356 classes.erase(ca->my_class);
365 * \brief Returns the size of the component of element \e a.
367 * Returns the size of the component of element \e a.
370 int size(const T &a) const {
371 return _find(m[a])->size;
376 * \brief Splits up the component of the element.
378 * Splitting the component of the element into sigleton
379 * components (component of size one).
382 void split(const T &a) {
384 IIter ca = _find(m[a]);
389 CIter aclass = ca->my_class;
391 for(IIter curr = ca; ++curr != aclass->end(); curr=ca) {
392 classes.push_back(ItemList());
393 CIter nl = --classes.end();
394 nl->splice(nl->end(), *aclass, curr);
407 * \brief Sets the given element to the leader element of its component.
409 * Sets the given element to the leader element of its component.
412 void makeRep(const T &a) {
415 IIter la = _find(ia);
416 if (la == ia) return;
418 ia->my_class = la->my_class;
423 CIter l = ia->my_class;
424 l->splice(l->begin(),*l,ia);
431 * \brief Moves the given element to an other component.
433 * This method moves the element \e a from its component
434 * to the component of \e comp.
435 * If \e a and \e comp are in the same component then
436 * it returns false otherwise it returns true.
439 bool move(const T &a, const T &comp) {
442 IIter lai = _find(ai);
443 IIter clit = _find(m[comp]);
448 ItemList &cl = *clit->my_class,
449 &al = *lai->my_class;
451 bool is_leader = (lai == ai);
452 bool singleton = false;
458 cl.splice(cl.end(), al, ai);
462 classes.erase(ai->my_class);
466 lai->size = ai->size;
467 lai->my_class = ai->my_class;
471 for (IIter i = lai; i != al.end(); ++i)
485 * \brief Removes the given element from the structure.
487 * Removes the given element from the structure.
489 * Removes the element from its component and if the component becomes
490 * empty then removes that component from the component list.
492 void erase(const T &a) {
497 IIter la = _find(ma);
499 if (ma -> size == 1){
500 classes.erase(ma->my_class);
506 la->my_class = ma->my_class;
509 for (IIter i = la; i != la->my_class->end(); ++i) {
514 la->my_class->erase(ma);
519 * \brief Removes the component of the given element from the structure.
521 * Removes the component of the given element from the structure.
524 void eraseClass(const T &a) {
528 CIter c = _find(ma)->my_class;
529 for (IIter i=c->begin(); i!=c->end(); ++i)
532 classes.erase(_find(ma)->my_class);
537 friend class UnionFindEnum;
541 ClassIt(Invalid): i(0) {}
544 operator const T& () const {
545 ItemList const &ll = *i;
546 return (ll.begin())->me; }
547 bool operator == (ClassIt it) const {
550 bool operator != (ClassIt it) const {
553 bool operator < (ClassIt it) const {
557 bool valid() const { return i != 0; }
559 void first(const ClassList &l) { i = l.begin(); validate(l); }
560 void next(const ClassList &l) {
564 void validate(const ClassList &l) {
571 * \brief Sets the iterator to point to the first component.
573 * Sets the iterator to point to the first component.
575 * With the \ref first, \ref valid and \ref next methods you can
576 * iterate through the components. For example:
578 * UnionFindEnum<Graph::Node, Graph::NodeMap>::MapType map(G);
579 * UnionFindEnum<Graph::Node, Graph::NodeMap> U(map);
580 * UnionFindEnum<Graph::Node, Graph::NodeMap>::ClassIt iter;
581 * for (U.first(iter); U.valid(iter); U.next(iter)) {
582 * // iter is convertible to Graph::Node
583 * cout << iter << endl;
588 ClassIt& first(ClassIt& it) const {
594 * \brief Returns whether the iterator is valid.
596 * Returns whether the iterator is valid.
598 * With the \ref first, \ref valid and \ref next methods you can
599 * iterate through the components. See the example here: \ref first.
602 bool valid(ClassIt const &it) const {
607 * \brief Steps the iterator to the next component.
609 * Steps the iterator to the next component.
611 * With the \ref first, \ref valid and \ref next methods you can
612 * iterate through the components. See the example here: \ref first.
615 ClassIt& next(ClassIt& it) const {
622 friend class UnionFindEnum;
627 ItemIt(Invalid): i(0) {}
630 operator const T& () const { return i->me; }
631 bool operator == (ItemIt it) const {
634 bool operator != (ItemIt it) const {
637 bool operator < (ItemIt it) const {
641 bool valid() const { return i != 0; }
643 void first(const ItemList &il) { l=&il; i = l->begin(); validate(); }
657 * \brief Sets the iterator to point to the first element of the component.
660 * Sets the iterator to point to the first element of the component.
662 * With the \ref first2 "first", \ref valid2 "valid"
663 * and \ref next2 "next" methods you can
664 * iterate through the elements of a component. For example
665 * (iterating through the component of the node \e node):
667 * Graph::Node node = ...;
668 * UnionFindEnum<Graph::Node, Graph::NodeMap>::MapType map(G);
669 * UnionFindEnum<Graph::Node, Graph::NodeMap> U(map);
670 * UnionFindEnum<Graph::Node, Graph::NodeMap>::ItemIt iiter;
671 * for (U.first(iiter, node); U.valid(iiter); U.next(iiter)) {
672 * // iiter is convertible to Graph::Node
673 * cout << iiter << endl;
678 ItemIt& first(ItemIt& it, const T& a) const {
679 it.first( * _find(m[a])->my_class );
684 * \brief Returns whether the iterator is valid.
687 * Returns whether the iterator is valid.
689 * With the \ref first2 "first", \ref valid2 "valid"
690 * and \ref next2 "next" methods you can
691 * iterate through the elements of a component.
692 * See the example here: \ref first2 "first".
695 bool valid(ItemIt const &it) const {
700 * \brief Steps the iterator to the next component.
703 * Steps the iterator to the next component.
705 * With the \ref first2 "first", \ref valid2 "valid"
706 * and \ref next2 "next" methods you can
707 * iterate through the elements of a component.
708 * See the example here: \ref first2 "first".
711 ItemIt& next(ItemIt& it) const {
723 #endif //LEMON_UNION_FIND_H