PageRenderTime 78ms CodeModel.GetById 16ms app.highlight 55ms RepoModel.GetById 1ms app.codeStats 1ms

/indra/llcommon/lltreeiterators.h

https://bitbucket.org/lindenlab/viewer-beta/
C++ Header | 705 lines | 349 code | 41 blank | 315 comment | 17 complexity | 80f9db743681f3e800844d6de6d1fce7 MD5 | raw file
  1/**
  2 * @file   lltreeiterators.h
  3 * @author Nat Goodspeed
  4 * @date   2008-08-19
  5 * @brief  This file defines iterators useful for traversing arbitrary node
  6 *         classes, potentially polymorphic, linked into strict tree
  7 *         structures.
  8 *
  9 *         Dereferencing any one of these iterators actually yields a @em
 10 *         pointer to the node in question. For example, given an
 11 *         LLLinkedIter<MyNode> <tt>li</tt>, <tt>*li</tt> gets you a pointer
 12 *         to MyNode, and <tt>**li</tt> gets you the MyNode instance itself.
 13 *         More commonly, instead of writing <tt>li->member</tt>, you write
 14 *         <tt>(*li)->member</tt> -- as you would if you were traversing an
 15 *         STL container of MyNode pointers.
 16 *
 17 *         It would certainly be possible to build these iterators so that
 18 *         <tt>*iterator</tt> would return a reference to the node itself
 19 *         rather than a pointer to the node, and for many purposes it would
 20 *         even be more convenient. However, that would be insufficiently
 21 *         flexible. If you want to use an iterator range to (e.g.) initialize
 22 *         a std::vector collecting results -- you rarely want to actually @em
 23 *         copy the nodes in question. You're much more likely to want to copy
 24 *         <i>pointers to</i> the traversed nodes. Hence these iterators
 25 *         produce pointers.
 26 *
 27 *         Though you specify the actual NODE class as the template parameter,
 28 *         these iterators internally use LLPtrTo<> to discover whether to
 29 *         store and return an LLPointer<NODE> or a simple NODE*.
 30 *
 31 *         By strict tree structures, we mean that each child must have
 32 *         exactly one parent. This forbids a child claiming any ancestor as a
 33 *         child of its own. Child nodes with multiple parents will be visited
 34 *         once for each parent. Cycles in the graph will result in either an
 35 *         infinite loop or an out-of-memory crash. You Have Been Warned.
 36 * 
 37 * $LicenseInfo:firstyear=2008&license=viewerlgpl$
 38 * Second Life Viewer Source Code
 39 * Copyright (C) 2010, Linden Research, Inc.
 40 * 
 41 * This library is free software; you can redistribute it and/or
 42 * modify it under the terms of the GNU Lesser General Public
 43 * License as published by the Free Software Foundation;
 44 * version 2.1 of the License only.
 45 * 
 46 * This library is distributed in the hope that it will be useful,
 47 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 48 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 49 * Lesser General Public License for more details.
 50 * 
 51 * You should have received a copy of the GNU Lesser General Public
 52 * License along with this library; if not, write to the Free Software
 53 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 54 * 
 55 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 56 * $/LicenseInfo$
 57 */
 58
 59#if ! defined(LL_LLTREEITERATORS_H)
 60#define LL_LLTREEITERATORS_H
 61
 62#include "llptrto.h"
 63#include <vector>
 64#include <deque>
 65#include <boost/iterator/iterator_facade.hpp>
 66#include <boost/function.hpp>
 67#include <boost/static_assert.hpp>
 68
 69namespace LLTreeIter
 70{
 71    /// Discriminator between LLTreeUpIter and LLTreeDownIter
 72    enum RootIter { UP, DOWN };
 73    /// Discriminator between LLTreeDFSIter, LLTreeDFSPostIter and LLTreeBFSIter
 74    enum WalkIter { DFS_PRE, DFS_POST, BFS };
 75}
 76
 77/**
 78 * LLBaseIter defines some machinery common to all these iterators. We use
 79 * boost::iterator_facade to define the iterator boilerplate: the conventional
 80 * operators and methods necessary to implement a standards-conforming
 81 * iterator. That allows us to specify the actual iterator semantics in terms
 82 * of equal(), dereference() and increment() methods.
 83 */
 84template <class SELFTYPE, class NODE>
 85class LLBaseIter: public boost::iterator_facade<SELFTYPE,
 86                                                // use pointer type as the
 87                                                // reference type
 88                                                typename LLPtrTo<NODE>::type,
 89                                                boost::forward_traversal_tag>
 90{
 91protected:
 92    /// LLPtrTo<NODE>::type is either NODE* or LLPointer<NODE>, as appropriate
 93    typedef typename LLPtrTo<NODE>::type ptr_type;
 94    /// function that advances from this node to next accepts a node pointer
 95    /// and returns another
 96    typedef boost::function<ptr_type(const ptr_type&)> func_type;
 97    typedef SELFTYPE self_type;
 98};
 99
100/// Functor returning NULL, suitable for an end-iterator's 'next' functor
101template <class NODE>
102typename LLPtrTo<NODE>::type LLNullNextFunctor(const typename LLPtrTo<NODE>::type&)
103{
104    return typename LLPtrTo<NODE>::type();
105}
106
107/**
108 * LLLinkedIter is an iterator over an intrusive singly-linked list. The
109 * beginning of the list is represented by LLLinkedIter(list head); the end is
110 * represented by LLLinkedIter().
111 *
112 * The begin LLLinkedIter must be instantiated with a functor to extract the
113 * 'next' pointer from the current node. Supposing that the link pointer is @c
114 * public, something like:
115 *
116 * @code
117 * NODE* mNext;
118 * @endcode
119 *
120 * you can use (e.g.) <tt>boost::bind(&NODE::mNext, _1)</tt> for the purpose.
121 * Alternatively, you can bind whatever accessor method is normally used to
122 * advance to the next node, e.g. for:
123 *
124 * @code
125 * NODE* next() const;
126 * @endcode
127 *
128 * you can use <tt>boost::bind(&NODE::next, _1)</tt>.
129 */
130template <class NODE>
131class LLLinkedIter: public LLBaseIter<LLLinkedIter<NODE>, NODE>
132{
133    typedef LLBaseIter<LLLinkedIter<NODE>, NODE> super;
134protected:
135    /// some methods need to return a reference to self
136    typedef typename super::self_type self_type;
137    typedef typename super::ptr_type ptr_type;
138    typedef typename super::func_type func_type;
139public:
140    /// Instantiate an LLLinkedIter to start a range, or to end a range before
141    /// a particular list entry. Pass a functor to extract the 'next' pointer
142    /// from the current node.
143    LLLinkedIter(const ptr_type& entry, const func_type& nextfunc):
144        mCurrent(entry),
145        mNextFunc(nextfunc)
146    {}
147    /// Instantiate an LLLinkedIter to end a range at the end of the list
148    LLLinkedIter():
149        mCurrent(),
150        mNextFunc(LLNullNextFunctor<NODE>)
151    {}
152
153private:
154    /// leverage boost::iterator_facade
155    friend class boost::iterator_core_access;
156
157    /// advance
158    void increment()
159    {
160        mCurrent = mNextFunc(mCurrent);
161    }
162    /// equality
163    bool equal(const self_type& that) const { return this->mCurrent == that.mCurrent; }
164    /// dereference
165    ptr_type& dereference() const { return const_cast<ptr_type&>(mCurrent); }
166
167    ptr_type mCurrent;
168    func_type mNextFunc;
169};
170
171/**
172 * LLTreeUpIter walks from the node in hand to the root of the tree. The term
173 * "up" is applied to a tree visualized with the root at the top.
174 *
175 * LLTreeUpIter is an alias for LLLinkedIter, since any linked tree that you
176 * can navigate that way at all contains parent pointers.
177 */
178template <class NODE>
179class LLTreeUpIter: public LLLinkedIter<NODE>
180{
181    typedef LLLinkedIter<NODE> super;
182public:
183    /// Instantiate an LLTreeUpIter to start from a particular tree node, or
184    /// to end a parent traversal before reaching a particular ancestor. Pass
185    /// a functor to extract the 'parent' pointer from the current node.
186    LLTreeUpIter(const typename super::ptr_type& node,
187                 const typename super::func_type& parentfunc):
188        super(node, parentfunc)
189    {}
190    /// Instantiate an LLTreeUpIter to end a range at the root of the tree
191    LLTreeUpIter():
192        super()
193    {}
194};
195
196/**
197 * LLTreeDownIter walks from the root of the tree to the node in hand. The
198 * term "down" is applied to a tree visualized with the root at the top.
199 *
200 * Though you instantiate the begin() LLTreeDownIter with a pointer to some
201 * node at an arbitrary location in the tree, the root will be the first node
202 * you dereference and the passed node will be the last node you dereference.
203 *
204 * On construction, LLTreeDownIter walks from the current node to the root,
205 * capturing the path. Then in use, it replays that walk in reverse. As with
206 * all traversals of interesting data structures, it is actively dangerous to
207 * modify the tree during an LLTreeDownIter walk.
208 */
209template <class NODE>
210class LLTreeDownIter: public LLBaseIter<LLTreeDownIter<NODE>, NODE>
211{
212    typedef LLBaseIter<LLTreeDownIter<NODE>, NODE> super;
213    typedef typename super::self_type self_type;
214protected:
215    typedef typename super::ptr_type ptr_type;
216    typedef typename super::func_type func_type;
217private:
218    typedef std::vector<ptr_type> list_type;
219public:
220    /// Instantiate an LLTreeDownIter to end at a particular tree node. Pass a
221    /// functor to extract the 'parent' pointer from the current node.
222    LLTreeDownIter(const ptr_type& node,
223                   const func_type& parentfunc)
224    {
225        for (ptr_type n = node; n; n = parentfunc(n))
226            mParents.push_back(n);
227    }
228    /// Instantiate an LLTreeDownIter representing "here", the end of the loop
229    LLTreeDownIter() {}
230
231private:
232    /// leverage boost::iterator_facade
233    friend class boost::iterator_core_access;
234
235    /// advance
236    void increment()
237    {
238        mParents.pop_back();
239    }
240    /// equality
241    bool equal(const self_type& that) const { return this->mParents == that.mParents; }
242    /// implement dereference/indirection operators
243    ptr_type& dereference() const { return const_cast<ptr_type&>(mParents.back()); }
244
245    list_type mParents;
246};
247
248/**
249 * When you want to select between LLTreeUpIter and LLTreeDownIter with a
250 * compile-time discriminator, use LLTreeRootIter with an LLTreeIter::RootIter
251 * template arg.
252 */
253template <LLTreeIter::RootIter DISCRIM, class NODE>
254class LLTreeRootIter
255{
256    enum { use_a_valid_LLTreeIter_RootIter_value = false };
257public:
258    /// Bogus constructors for default (unrecognized discriminator) case
259    template <typename TYPE1, typename TYPE2>
260    LLTreeRootIter(TYPE1, TYPE2)
261    {
262        BOOST_STATIC_ASSERT(use_a_valid_LLTreeIter_RootIter_value);
263    }
264    LLTreeRootIter()
265    {
266        BOOST_STATIC_ASSERT(use_a_valid_LLTreeIter_RootIter_value);
267    }
268};
269
270/// Specialize for LLTreeIter::UP
271template <class NODE>
272class LLTreeRootIter<LLTreeIter::UP, NODE>: public LLTreeUpIter<NODE>
273{
274    typedef LLTreeUpIter<NODE> super;
275public:
276    /// forward begin ctor
277    LLTreeRootIter(const typename super::ptr_type& node,
278                   const typename super::func_type& parentfunc):
279        super(node, parentfunc)
280    {}
281    /// forward end ctor
282    LLTreeRootIter():
283        super()
284    {}
285};
286
287/// Specialize for LLTreeIter::DOWN
288template <class NODE>
289class LLTreeRootIter<LLTreeIter::DOWN, NODE>: public LLTreeDownIter<NODE>
290{
291    typedef LLTreeDownIter<NODE> super;
292public:
293    /// forward begin ctor
294    LLTreeRootIter(const typename super::ptr_type& node,
295                   const typename super::func_type& parentfunc):
296        super(node, parentfunc)
297    {}
298    /// forward end ctor
299    LLTreeRootIter():
300        super()
301    {}
302};
303
304/**
305 * Instantiated with a tree node, typically the root, LLTreeDFSIter "flattens"
306 * a depth-first tree walk through that node and all its descendants.
307 *
308 * The begin() LLTreeDFSIter must be instantiated with functors to obtain from
309 * a given node begin() and end() iterators for that node's children. For this
310 * reason, you must specify the type of the node's child iterator as an
311 * additional template parameter.
312 *
313 * Specifically, the begin functor must return an iterator whose dereferenced
314 * value is a @em pointer to a child tree node. For instance, if each node
315 * tracks its children in an STL container of node* pointers, you can simply
316 * return that container's begin() iterator.
317 *
318 * Alternatively, if a node tracks its children with a classic linked list,
319 * write a functor returning LLLinkedIter<NODE>.
320 *
321 * The end() LLTreeDFSIter must, of course, match the begin() iterator's
322 * template parameters, but is constructed without runtime parameters.
323 */
324template <class NODE, typename CHILDITER>
325class LLTreeDFSIter: public LLBaseIter<LLTreeDFSIter<NODE, CHILDITER>, NODE>
326{
327    typedef LLBaseIter<LLTreeDFSIter<NODE, CHILDITER>, NODE> super;
328    typedef typename super::self_type self_type;
329protected:
330    typedef typename super::ptr_type ptr_type;
331    // The func_type is different for this: from a NODE pointer, we must
332    // obtain a CHILDITER.
333    typedef boost::function<CHILDITER(const ptr_type&)> func_type;
334private:
335    typedef std::vector<ptr_type> list_type;
336public:
337    /// Instantiate an LLTreeDFSIter to start a depth-first walk. Pass
338    /// functors to extract the 'child begin' and 'child end' iterators from
339    /// each node.
340    LLTreeDFSIter(const ptr_type& node, const func_type& beginfunc, const func_type& endfunc)
341	    : mBeginFunc(beginfunc),
342	    mEndFunc(endfunc),
343	    mSkipChildren(false)
344    {
345        // Only push back this node if it's non-NULL!
346        if (node)
347            mPending.push_back(node);
348    }
349    /// Instantiate an LLTreeDFSIter to mark the end of the walk
350    LLTreeDFSIter() : mSkipChildren(false) {}
351
352    /// flags iterator logic to skip traversing children of current node on next increment
353    void skipDescendants(bool skip = true) { mSkipChildren = skip; }
354
355private:
356    /// leverage boost::iterator_facade
357    friend class boost::iterator_core_access;
358
359    /// advance
360    /// This implementation is due to http://en.wikipedia.org/wiki/Depth-first_search
361    void increment()
362    {
363        // Capture the node we were just looking at
364        ptr_type current = mPending.back();
365        // Remove it from mPending so we don't process it again later
366        mPending.pop_back();
367		if (!mSkipChildren)
368		{
369			// Add all its children to mPending
370			addChildren(current);
371		}
372		// reset flag after each step
373		mSkipChildren = false;
374    }
375    /// equality
376    bool equal(const self_type& that) const { return this->mPending == that.mPending; }
377    /// implement dereference/indirection operators
378    ptr_type& dereference() const { return const_cast<ptr_type&>(mPending.back()); }
379
380    /// Add the direct children of the specified node to mPending
381    void addChildren(const ptr_type& node)
382    {
383        // If we just use push_back() for each child in turn, we'll end up
384        // processing children in reverse order. We don't want to assume
385        // CHILDITER is reversible: some of the linked trees we'll be
386        // processing manage their children using singly-linked lists. So
387        // figure out how many children there are, grow mPending by that size
388        // and reverse-copy the children into the new space.
389        CHILDITER chi = mBeginFunc(node), chend = mEndFunc(node);
390        // grow mPending by the number of children
391        mPending.resize(mPending.size() + std::distance(chi, chend));
392        // reverse-copy the children into the newly-expanded space
393        std::copy(chi, chend, mPending.rbegin());
394    }
395
396    /// list of the nodes yet to be processed
397    list_type mPending;
398    /// functor to extract begin() child iterator
399    func_type mBeginFunc;
400    /// functor to extract end() child iterator
401    func_type mEndFunc;
402    /// flag which controls traversal of children (skip children of current node if true)
403    bool	mSkipChildren;
404};
405
406/**
407 * Instantiated with a tree node, typically the root, LLTreeDFSPostIter
408 * "flattens" a depth-first tree walk through that node and all its
409 * descendants. Whereas LLTreeDFSIter visits each node before visiting any of
410 * its children, LLTreeDFSPostIter visits all of a node's children before
411 * visiting the node itself.
412 *
413 * The begin() LLTreeDFSPostIter must be instantiated with functors to obtain
414 * from a given node begin() and end() iterators for that node's children. For
415 * this reason, you must specify the type of the node's child iterator as an
416 * additional template parameter.
417 *
418 * Specifically, the begin functor must return an iterator whose dereferenced
419 * value is a @em pointer to a child tree node. For instance, if each node
420 * tracks its children in an STL container of node* pointers, you can simply
421 * return that container's begin() iterator.
422 *
423 * Alternatively, if a node tracks its children with a classic linked list,
424 * write a functor returning LLLinkedIter<NODE>.
425 *
426 * The end() LLTreeDFSPostIter must, of course, match the begin() iterator's
427 * template parameters, but is constructed without runtime parameters.
428 */
429template <class NODE, typename CHILDITER>
430class LLTreeDFSPostIter: public LLBaseIter<LLTreeDFSPostIter<NODE, CHILDITER>, NODE>
431{
432    typedef LLBaseIter<LLTreeDFSPostIter<NODE, CHILDITER>, NODE> super;
433    typedef typename super::self_type self_type;
434protected:
435    typedef typename super::ptr_type ptr_type;
436    // The func_type is different for this: from a NODE pointer, we must
437    // obtain a CHILDITER.
438    typedef boost::function<CHILDITER(const ptr_type&)> func_type;
439private:
440    // Upon reaching a given node in our pending list, we need to know whether
441    // we've already pushed that node's children, so we must associate a bool
442    // with each node pointer.
443    typedef std::vector< std::pair<ptr_type, bool> > list_type;
444public:
445    /// Instantiate an LLTreeDFSPostIter to start a depth-first walk. Pass
446    /// functors to extract the 'child begin' and 'child end' iterators from
447    /// each node.
448    LLTreeDFSPostIter(const ptr_type& node, const func_type& beginfunc, const func_type& endfunc)
449	    : mBeginFunc(beginfunc),
450	    mEndFunc(endfunc),
451	    mSkipAncestors(false)
452	    {
453        if (! node)
454            return;
455        mPending.push_back(typename list_type::value_type(node, false));
456        makeCurrent();
457    }
458    /// Instantiate an LLTreeDFSPostIter to mark the end of the walk
459    LLTreeDFSPostIter() : mSkipAncestors(false) {}
460
461    /// flags iterator logic to skip traversing ancestors of current node on next increment
462    void skipAncestors(bool skip = true) { mSkipAncestors = skip; }
463
464private:
465    /// leverage boost::iterator_facade
466    friend class boost::iterator_core_access;
467
468    /// advance
469    /// This implementation is due to http://en.wikipedia.org/wiki/Depth-first_search
470    void increment()
471    {
472        // Pop the previous current node
473        mPending.pop_back();
474        makeCurrent();
475    }
476    /// equality
477    bool equal(const self_type& that) const { return this->mPending == that.mPending; }
478    /// implement dereference/indirection operators
479    ptr_type& dereference() const { return const_cast<ptr_type&>(mPending.back().first); }
480
481	struct isOpen
482	{
483		bool operator()(const typename list_type::value_type& item)
484		{
485			return item.second;
486		}
487	};
488
489    /// Call this each time we change mPending.back() -- that is, every time
490    /// we're about to change the value returned by dereference(). If we
491    /// haven't yet pushed the new node's children, do so now.
492    void makeCurrent()
493    {
494		if (mSkipAncestors)
495		{
496			mPending.erase(std::remove_if(mPending.begin(), mPending.end(), isOpen()), mPending.end());
497			mSkipAncestors = false;
498		}
499
500        // Once we've popped the last node, this becomes a no-op.
501        if (mPending.empty())
502            return;
503        // Here mPending.back() holds the node pointer we're proposing to
504        // dereference next. Have we pushed that node's children yet?
505        if (mPending.back().second)
506            return;                 // if so, it's okay to visit this node now
507        // We haven't yet pushed this node's children. Do so now. Remember
508        // that we did -- while the node in question is still back().
509        mPending.back().second = true;
510        addChildren(mPending.back().first);
511        // Now, because we've just changed mPending.back(), make that new node
512        // current.
513        makeCurrent();
514    }
515
516    /// Add the direct children of the specified node to mPending
517    void addChildren(const ptr_type& node)
518    {
519        // If we just use push_back() for each child in turn, we'll end up
520        // processing children in reverse order. We don't want to assume
521        // CHILDITER is reversible: some of the linked trees we'll be
522        // processing manage their children using singly-linked lists. So
523        // figure out how many children there are, grow mPending by that size
524        // and reverse-copy the children into the new space.
525        CHILDITER chi = mBeginFunc(node), chend = mEndFunc(node);
526        // grow mPending by the number of children
527        mPending.resize(mPending.size() + std::distance(chi, chend));
528        // Reverse-copy the children into the newly-expanded space. We can't
529        // just use std::copy() because the source is a ptr_type, whereas the
530        // dest is a pair of (ptr_type, bool).
531        for (typename list_type::reverse_iterator pi = mPending.rbegin(); chi != chend; ++chi, ++pi)
532        {
533            pi->first = *chi;       // copy the child pointer
534            pi->second = false;     // we haven't yet pushed this child's chldren
535        }
536    }
537
538    /// list of the nodes yet to be processed
539    list_type	mPending;
540    /// functor to extract begin() child iterator
541    func_type	mBeginFunc;
542    /// functor to extract end() child iterator
543    func_type	mEndFunc;
544	/// flags logic to skip traversal of ancestors of current node
545	bool		mSkipAncestors;
546};
547
548/**
549 * Instantiated with a tree node, typically the root, LLTreeBFSIter "flattens"
550 * a breadth-first tree walk through that node and all its descendants.
551 *
552 * The begin() LLTreeBFSIter must be instantiated with functors to obtain from
553 * a given node the begin() and end() iterators of that node's children. For
554 * this reason, you must specify the type of the node's child iterator as an
555 * additional template parameter.
556 *
557 * Specifically, the begin functor must return an iterator whose dereferenced
558 * value is a @em pointer to a child tree node. For instance, if each node
559 * tracks its children in an STL container of node* pointers, you can simply
560 * return that container's begin() iterator.
561 *
562 * Alternatively, if a node tracks its children with a classic linked list,
563 * write a functor returning LLLinkedIter<NODE>.
564 *
565 * The end() LLTreeBFSIter must, of course, match the begin() iterator's
566 * template parameters, but is constructed without runtime parameters.
567 */
568template <class NODE, typename CHILDITER>
569class LLTreeBFSIter: public LLBaseIter<LLTreeBFSIter<NODE, CHILDITER>, NODE>
570{
571    typedef LLBaseIter<LLTreeBFSIter<NODE, CHILDITER>, NODE> super;
572    typedef typename super::self_type self_type;
573protected:
574    typedef typename super::ptr_type ptr_type;
575    // The func_type is different for this: from a NODE pointer, we must
576    // obtain a CHILDITER.
577    typedef boost::function<CHILDITER(const ptr_type&)> func_type;
578private:
579    // We need a FIFO queue rather than a LIFO stack. Use a deque rather than
580    // a vector, since vector can't implement pop_front() efficiently.
581    typedef std::deque<ptr_type> list_type;
582public:
583    /// Instantiate an LLTreeBFSIter to start a depth-first walk. Pass
584    /// functors to extract the 'child begin' and 'child end' iterators from
585    /// each node.
586    LLTreeBFSIter(const ptr_type& node, const func_type& beginfunc, const func_type& endfunc):
587        mBeginFunc(beginfunc),
588        mEndFunc(endfunc)
589    {
590        if (node)
591            mPending.push_back(node);
592    }
593    /// Instantiate an LLTreeBFSIter to mark the end of the walk
594    LLTreeBFSIter() {}
595
596private:
597    /// leverage boost::iterator_facade
598    friend class boost::iterator_core_access;
599
600    /// advance
601    /// This implementation is due to http://en.wikipedia.org/wiki/Breadth-first_search
602    void increment()
603    {
604        // Capture the node we were just looking at
605        ptr_type current = mPending.front();
606        // Remove it from mPending so we don't process it again later
607        mPending.pop_front();
608        // Add all its children to mPending
609        CHILDITER chend = mEndFunc(current);
610        for (CHILDITER chi = mBeginFunc(current); chi != chend; ++chi)
611            mPending.push_back(*chi);
612    }
613    /// equality
614    bool equal(const self_type& that) const { return this->mPending == that.mPending; }
615    /// implement dereference/indirection operators
616    ptr_type& dereference() const { return const_cast<ptr_type&>(mPending.front()); }
617
618    /// list of the nodes yet to be processed
619    list_type mPending;
620    /// functor to extract begin() child iterator
621    func_type mBeginFunc;
622    /// functor to extract end() child iterator
623    func_type mEndFunc;
624};
625
626/**
627 * When you want to select between LLTreeDFSIter, LLTreeDFSPostIter and
628 * LLTreeBFSIter with a compile-time discriminator, use LLTreeWalkIter with an
629 * LLTreeIter::WalkIter template arg.
630 */
631template <LLTreeIter::WalkIter DISCRIM, class NODE, typename CHILDITER>
632class LLTreeWalkIter
633{
634    enum { use_a_valid_LLTreeIter_WalkIter_value = false };
635public:
636    /// Bogus constructors for default (unrecognized discriminator) case
637    template <typename TYPE1, typename TYPE2>
638    LLTreeWalkIter(TYPE1, TYPE2)
639    {
640        BOOST_STATIC_ASSERT(use_a_valid_LLTreeIter_WalkIter_value);
641    }
642    LLTreeWalkIter()
643    {
644        BOOST_STATIC_ASSERT(use_a_valid_LLTreeIter_WalkIter_value);
645    }
646};
647
648/// Specialize for LLTreeIter::DFS_PRE
649template <class NODE, typename CHILDITER>
650class LLTreeWalkIter<LLTreeIter::DFS_PRE, NODE, CHILDITER>:
651    public LLTreeDFSIter<NODE, CHILDITER>
652{
653    typedef LLTreeDFSIter<NODE, CHILDITER> super;
654public:
655    /// forward begin ctor
656    LLTreeWalkIter(const typename super::ptr_type& node,
657                   const typename super::func_type& beginfunc,
658                   const typename super::func_type& endfunc):
659        super(node, beginfunc, endfunc)
660    {}
661    /// forward end ctor
662    LLTreeWalkIter():
663        super()
664    {}
665};
666
667/// Specialize for LLTreeIter::DFS_POST
668template <class NODE, typename CHILDITER>
669class LLTreeWalkIter<LLTreeIter::DFS_POST, NODE, CHILDITER>:
670    public LLTreeDFSPostIter<NODE, CHILDITER>
671{
672    typedef LLTreeDFSPostIter<NODE, CHILDITER> super;
673public:
674    /// forward begin ctor
675    LLTreeWalkIter(const typename super::ptr_type& node,
676                   const typename super::func_type& beginfunc,
677                   const typename super::func_type& endfunc):
678        super(node, beginfunc, endfunc)
679    {}
680    /// forward end ctor
681    LLTreeWalkIter():
682        super()
683    {}
684};
685
686/// Specialize for LLTreeIter::BFS
687template <class NODE, typename CHILDITER>
688class LLTreeWalkIter<LLTreeIter::BFS, NODE, CHILDITER>:
689    public LLTreeBFSIter<NODE, CHILDITER>
690{
691    typedef LLTreeBFSIter<NODE, CHILDITER> super;
692public:
693    /// forward begin ctor
694    LLTreeWalkIter(const typename super::ptr_type& node,
695                   const typename super::func_type& beginfunc,
696                   const typename super::func_type& endfunc):
697        super(node, beginfunc, endfunc)
698    {}
699    /// forward end ctor
700    LLTreeWalkIter():
701        super()
702    {}
703};
704
705#endif /* ! defined(LL_LLTREEITERATORS_H) */