regina::SubtreeIterator< const_ > Class Template Reference

A forward iterator for iterating through the entire packet subtree rooted at a given packet. More...

#include <packet/packet.h>

Public Types
using	value_type = typename std::conditional< const_, const Packet, Packet >::type
	Indicates what the iterator points to. More...
using	iterator_category = std::forward_iterator_tag
	Declares this to be a forward iterator type. More...
using	difference_type = ptrdiff_t
	The type obtained by subtracting iterators. More...
using	pointer = value_type *
	A pointer to value_type. More...
using	reference = value_type &
	A reference to value_type. More...

Public Member Functions
	SubtreeIterator ()=default
	Creates a past-the-end iterator. More...
	SubtreeIterator (const SubtreeIterator &)=default
	Default copy constructor. More...
	SubtreeIterator (std::shared_ptr< value_type > subtree)
	Creates a new iterator pointing to the first packet within the given subtree. More...
	SubtreeIterator (std::shared_ptr< value_type > subtree, std::shared_ptr< value_type > current)
	Creates a new iterator pointing to the given packet within the given subtree. More...
SubtreeIterator &	operator= (const SubtreeIterator &)=default
	Default copy assignment operator. More...
bool	operator== (const SubtreeIterator &rhs) const
	Tests whether this and the given iterator are equal. More...
bool	operator!= (const SubtreeIterator &rhs) const
	Tests whether this and the given iterator are different. More...
SubtreeIterator &	operator++ ()
	Preincrement operator. More...
SubtreeIterator	operator++ (int)
	Postincrement operator. More...
value_type &	operator* () const
	Returns the packet that this iterator is currently pointing to. More...
	operator bool () const
	Identifies whether this iterator is dereferencable. More...

Detailed Description

template<bool const_>
class regina::SubtreeIterator< const_ >

A forward iterator for iterating through the entire packet subtree rooted at a given packet.

The order of iteration is depth-first, where a parent packet is always processed before its descendants.

Each iterator will hold a std::shared_ptr to the packet whose subtree it is iterating over. This guarantees that the packet will not be destroyed mid-iteration, but it also means that you must ensure that you dispose of your iterators once you are finished with them.

Template Parameters

const_

Indicates whether this iterator should offer const or non-const access to the packet tree.

Python

Instead of the C++ interface described here, in Python this class implements the Python iterable/iterator interface. It implements the function iter(), which returns the iterator object itself; it also implements next(), which either returns the next packet in the subtree iteration or else throws a StopException if there are no more packets to return. All iteration in Python is non-const (i.e., Python exclusively uses the classes where const_ is false).

Member Typedef Documentation

difference_type

template<bool const_>

using regina::SubtreeIterator< const_ >::difference_type = ptrdiff_t

The type obtained by subtracting iterators.

iterator_category

template<bool const_>

using regina::SubtreeIterator< const_ >::iterator_category = std::forward_iterator_tag

Declares this to be a forward iterator type.

pointer

template<bool const_>

using regina::SubtreeIterator< const_ >::pointer = value_type*

A pointer to value_type.

reference

template<bool const_>

using regina::SubtreeIterator< const_ >::reference = value_type&

A reference to value_type.

value_type

template<bool const_>

using regina::SubtreeIterator< const_ >::value_type = typename std::conditional<const_, const Packet, Packet>::type

Indicates what the iterator points to.

This is either Packet or const Packet, according to the template argument const_.

Constructor & Destructor Documentation

SubtreeIterator() [1/4]

template<bool const_>

regina::SubtreeIterator< const_ >::SubtreeIterator ( )

default

Creates a past-the-end iterator.

Python

Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.

SubtreeIterator() [2/4]

template<bool const_>

regina::SubtreeIterator< const_ >::SubtreeIterator ( const SubtreeIterator< const_ > &  )

default

Default copy constructor.

Python

Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.

SubtreeIterator() [3/4]

template<bool const_>

regina::SubtreeIterator< const_ >::SubtreeIterator ( std::shared_ptr< value_type >  subtree )

inline

Creates a new iterator pointing to the first packet within the given subtree.

Dereferencing this iterator will return subtree itself.

Python

Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.

Parameters

subtree

the packet subtree that we are iterating through. This does not need to be the root of the overall packet tree (i.e., subtree is allowed to have a non-null parent).

SubtreeIterator() [4/4]

template<bool const_>

regina::SubtreeIterator< const_ >::SubtreeIterator ( std::shared_ptr< value_type >  subtree, std::shared_ptr< value_type >  current  )

inline

Creates a new iterator pointing to the given packet within the given subtree.

Python

Not present. The only way to create a SubtreeIterator is via Packet::subtree() or Packet::descendants(), or by iterating over a Packet itself.

Parameters

subtree	the packet subtree that we are iterating through. This does not need to be the root of the overall packet tree (i.e., subtree is allowed to have a non-null parent).
current	the packet within the subtree that the new iterator should point to, or null if the new iterator should be past-the-end. If current is not null, then it must be equal to or a descendant of subtree.

Member Function Documentation

operator bool()

template<bool const_>

regina::SubtreeIterator< const_ >::operator bool

inline

Identifies whether this iterator is dereferencable.

Python

Not present; instead this class implements next(), which either returns the current child packet and increments the iterator, or else throws a StopIteration exception if the iterator is not dereferencable.

Returns

true if and only if this is dereferencable (i.e., not past-the-end).

operator!=()

template<bool const_>

bool regina::SubtreeIterator< const_ >::operator!= ( const SubtreeIterator< const_ > &  rhs ) const

inline

Tests whether this and the given iterator are different.

Note

This routine only compares the packets that each iterator is currently pointing to. It does not compare the roots of the subtrees themselves.

Returns

true if and only if the two iterators are different.

operator*()

template<bool const_>

SubtreeIterator< const_ >::value_type & regina::SubtreeIterator< const_ >::operator*

inline

Returns the packet that this iterator is currently pointing to.

Python

Not present; instead this class implements next(), which either returns the current packet in the subtree and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.

Returns

the current packet.

operator++() [1/2]

template<bool const_>

SubtreeIterator< const_ > & regina::SubtreeIterator< const_ >::operator++

inline

Preincrement operator.

Python

Not present; instead this class implements next(), which either returns the current packet in the subtree and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.

Returns

a reference to this iterator.

operator++() [2/2]

template<bool const_>

SubtreeIterator< const_ > regina::SubtreeIterator< const_ >::operator++ ( int  )

inline

Postincrement operator.

Python

Not present; instead this class implements next(), which either returns the current packet in the subtree and increments the iterator, or else throws a StopIteration exception if the iterator is past-the-end.

Returns

a copy of this iterator before it was incremented.

operator=()

template<bool const_>

SubtreeIterator & regina::SubtreeIterator< const_ >::operator= ( const SubtreeIterator< const_ > &  )

default

Default copy assignment operator.

operator==()

template<bool const_>

bool regina::SubtreeIterator< const_ >::operator== ( const SubtreeIterator< const_ > &  rhs ) const

inline

Tests whether this and the given iterator are equal.

Note

This routine only compares the packets that each iterator is currently pointing to. It does not compare the roots of the subtrees themselves.

Returns

true if and only if the two iterators are equal.

---

The documentation for this class was generated from the following file:

• packet/packet.h