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 = std::conditional_t< const_, const Packet, Packet >
	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
	Creates a new copy of the given iterator. 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
	Sets this to be a copy of the given iterator. More...
auto	__iter__ () const
	Returns a Python iterator over all members of the relevant packet subtree. 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...
auto	__next__ ()
	Returns the current packet in the subtree and increments this iterator. 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 = std::conditional_t<const_, const Packet, Packet>

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

Creates a new copy of the given 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() [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

__iter__()

template<bool const_>

auto regina::SubtreeIterator< const_ >::__iter__

(

)

const

Returns a Python iterator over all members of the relevant packet subtree.

C++

Not present. For C++ users, you can access such iterators by calling begin() and end() on either (i) the packet at the root of the subtree, or (ii) the PacketDescendant object returned by Packet::descendants(). In particular, this allows you to iterate through a packet subtree (including or excluding the subtree root respectively) using a range-based for loop.

Returns

an iterator over all members of the relevant packet subtree.

__next__()

template<bool const_>

auto regina::SubtreeIterator< const_ >::__next__

(

)

Returns the current packet in the subtree and increments this iterator.

C++

Not present. For C++ users, SubtreeIterator provides the usual iterator preincrement, postincrement and dereferencing operators (++ and *) instead.

Exceptions

StopIteration

The iterator is already past-the-end when this function is called.

Returns

the packet that this iterator is pointing to, before the increment takes place.

operator bool()

template<bool const_>

regina::SubtreeIterator< const_ >::operator bool

inline

Identifies whether this iterator is dereferencable.

Python

Not present. For Python users, SubtreeIterator implements the Python iterator interface instead. See next() for details.

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.

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.

Precondition

This iterator is dereferenceable (i.e., it is not past-the-end).

Python

Not present. For Python users, SubtreeIterator implements the Python iterator interface instead. See next() for details.

Returns

the current packet.

operator++() [1/2]

template<bool const_>

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

inline

Preincrement operator.

Precondition

This iterator is dereferenceable (i.e., it is not past-the-end).

Python

Not present. For Python users, SubtreeIterator implements the Python iterator interface instead. See next() for details.

Returns

a reference to this iterator.

operator++() [2/2]

template<bool const_>

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

inline

Postincrement operator.

Precondition

This iterator is dereferenceable (i.e., it is not past-the-end).

Python

Not present. For Python users, SubtreeIterator implements the Python iterator interface instead. See next() for details.

Returns

a copy of this iterator before it was incremented.

operator=()

template<bool const_>

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

default

Sets this to be a copy of the given iterator.

Returns

a reference to this iterator.

operator==()

template<bool const_>

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

inline

Tests whether this and the given iterator are equal.

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