Adobe Source Libraries 1.49.0
A collection of C++ libraries.
Loading...
Searching...
No Matches
forest< T > Class Template Reference

A homogeneous hierarchical structure class. More...

#include <adobe/forest.hpp>

Public Types

typedef T & reference
typedef const T & const_reference
typedef implementation::forest_iterator< T > iterator
typedef implementation::forest_const_iterator< T > const_iterator
typedef std::size_t size_type
typedef std::ptrdiff_t difference_type
typedef T value_type
typedef T * pointer
typedef const T * const_pointer
typedef reverse_fullorder_iterator< iteratorreverse_iterator
typedef reverse_fullorder_iterator< const_iteratorconst_reverse_iterator
typedef adobe::child_iterator< iteratorchild_iterator
typedef adobe::child_iterator< const_iteratorconst_child_iterator
typedef std::reverse_iterator< child_iteratorreverse_child_iterator
typedef edge_iterator< iterator, forest_leading_edgepreorder_iterator
typedef edge_iterator< const_iterator, forest_leading_edgeconst_preorder_iterator
typedef edge_iterator< iterator, forest_trailing_edgepostorder_iterator
typedef edge_iterator< const_iterator, forest_trailing_edgeconst_postorder_iterator

Public Member Functions

 forest ()=default
 ~forest ()
 forest (const forest &)
 forest (forest &&) noexcept
forestoperator= (const forest &x)
forestoperator= (forest &&x) noexcept
void swap (forest &)
size_type size () const
size_type max_size () const
bool size_valid () const
bool empty () const
iterator root ()
const_iterator root () const
iterator begin ()
iterator end ()
const_iterator begin () const
const_iterator end () const
reverse_iterator rbegin ()
reverse_iterator rend ()
const_reverse_iterator rbegin () const
const_reverse_iterator rend () const
reference front ()
const_reference front () const
reference back ()
const_reference back () const
void clear ()
iterator erase (const iterator &position)
iterator erase (const iterator &first, const iterator &last)
iterator insert (const iterator &position, T x)
void push_front (const T &x)
void push_back (const T &x)
void pop_front ()
void pop_back ()
iterator insert (iterator position, const_child_iterator first, const_child_iterator last)
iterator splice (iterator position, forest< T > &x)
iterator splice (iterator position, forest< T > &x, iterator i)
iterator splice (iterator position, forest< T > &x, child_iterator first, child_iterator last)
iterator splice (iterator position, forest< T > &x, child_iterator first, child_iterator last, size_type count)
iterator insert_parent (child_iterator front, child_iterator back, const T &x)
void reverse (child_iterator first, child_iterator last)

Friends

class child_adaptor< forest< T > >
struct unsafe::set_next_fn< iterator >

(Note that these are not member symbols.)

void pivot (I &iter)
pivot_of (I iter)
trailing_of (C cursor)
leading_of (C cursor)
bool has_children (const C &cursor)
ForestTraveler find_parent (ForestTraveler traveler)
child_iterator< BeadIterator > child_begin (const BeadIterator &iter)
child_iterator< BeadIterator > child_end (const BeadIterator &iter)
template<typename R, typename P>
auto filter_fullorder_range (R &x, P p) -> boost::iterator_range< filter_fullorder_iterator< typename boost::range_iterator< R >::type, P > >
template<typename R, typename P>
auto filter_fullorder_range (const R &x, P p) -> boost::iterator_range< filter_fullorder_iterator< typename boost::range_const_iterator< R >::type, P > >
template<typename R>
auto reverse_fullorder_range (R &x) -> boost::iterator_range< reverse_fullorder_iterator< typename boost::range_iterator< R >::type > >
template<typename R>
boost::iterator_range< reverse_fullorder_iterator< typename boost::range_const_iterator< R >::type > > reverse_fullorder_range (const R &x)
template<typename R>
boost::iterator_range< depth_fullorder_iterator< typename boost::range_iterator< R >::type > > depth_range (R &x)
template<typename R>
boost::iterator_range< depth_fullorder_iterator< typename boost::range_const_iterator< R >::type > > depth_range (const R &x)
template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_iterator< R >::type, forest_trailing_edge > > postorder_range (R &x)
template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_const_iterator< R >::type, forest_trailing_edge > > postorder_range (const R &x)
template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_iterator< R >::type, forest_leading_edge > > preorder_range (R &x)
template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_const_iterator< R >::type, forest_leading_edge > > preorder_range (const R &x)
template<typename SourceForestIterType, typename DestForestType, typename UnaryFunction>
void transform_forest (SourceForestIterType first, SourceForestIterType last, DestForestType &destForest, typename DestForestType::iterator destIter, UnaryFunction transformFunc)
template<typename SourceForestIterType, typename DestForestType, typename UnaryFunction>
void transform_forest (SourceForestIterType first, SourceForestIterType last, DestForestType &destForest, UnaryFunction transformFunc)
template<typename SourceForestType, typename DestForestType, typename UnaryFunction>
void transform_forest (SourceForestType sourceForest, DestForestType &destForest, typename DestForestType::iterator destIter, UnaryFunction transformFunc)
template<typename SourceForestType, typename DestForestType, typename UnaryFunction>
void transform_forest (SourceForestType sourceForest, DestForestType &destForest, UnaryFunction transformFunc)

Detailed Description

template<typename T>
class adobe::forest< T >
A forest is a linked structure, similiar to a list forming a number of hierarchies or trees. A forest can be traversed as a sequence, depth first, either pre-order or post-order, both forward and backward. Elements can be inserted and erased from any location in constant time. Inserting and splicing do not invalidate iterators to forest elements; erasing invalidates only the iterators that point to the elements that are erased.
For information on adobe::forest utility classes see Forest.
For additional information on the edge semantics of forest iterators, please see http://stlab.adobe.com/wiki/index.php/Edge_Interface_For_Forest_Iterators
Model Of
Type Requirements
Only those imposed by the requirements of ReversibleContainer, FrontInsertionSequence, and BackInsertionSequence.
Definitions
  • cursor : A cursor is similar to an iterator, except *(cursor) == *(cursor + 1) may be true. (e.g, in the case when the cursor pivots but does not move off the current forest node to which it points.)
Tutorial
A tutorial for forest is available.

Definition at line 555 of file forest.hpp.

Member Typedef Documentation

◆ reference

template<typename T>
typedef T& reference

Definition at line 562 of file forest.hpp.

◆ const_reference

template<typename T>
typedef const T& const_reference

Definition at line 563 of file forest.hpp.

◆ iterator

template<typename T>
typedef implementation::forest_iterator<T> iterator

Definition at line 564 of file forest.hpp.

◆ const_iterator

template<typename T>
typedef implementation::forest_const_iterator<T> const_iterator

Definition at line 565 of file forest.hpp.

◆ size_type

template<typename T>
typedef std::size_t size_type

Definition at line 566 of file forest.hpp.

◆ difference_type

template<typename T>
typedef std::ptrdiff_t difference_type

Definition at line 567 of file forest.hpp.

◆ value_type

template<typename T>
typedef T value_type

Definition at line 568 of file forest.hpp.

◆ pointer

template<typename T>
typedef T* pointer

Definition at line 569 of file forest.hpp.

◆ const_pointer

template<typename T>
typedef const T* const_pointer

Definition at line 570 of file forest.hpp.

◆ reverse_iterator

template<typename T>
typedef reverse_fullorder_iterator<iterator> reverse_iterator

Definition at line 571 of file forest.hpp.

◆ const_reverse_iterator

Definition at line 572 of file forest.hpp.

◆ child_iterator

template<typename T>
typedef adobe::child_iterator<iterator> child_iterator

Definition at line 574 of file forest.hpp.

◆ const_child_iterator

Definition at line 579 of file forest.hpp.

◆ reverse_child_iterator

template<typename T>
typedef std::reverse_iterator<child_iterator> reverse_child_iterator

Definition at line 580 of file forest.hpp.

◆ preorder_iterator

Definition at line 582 of file forest.hpp.

◆ const_preorder_iterator

Definition at line 583 of file forest.hpp.

◆ postorder_iterator

Definition at line 584 of file forest.hpp.

◆ const_postorder_iterator

Definition at line 585 of file forest.hpp.

Constructor & Destructor Documentation

◆ forest() [1/3]

template<typename T>
forest ( )
default

◆ ~forest()

template<typename T>
~forest ( )

Definition at line 589 of file forest.hpp.

◆ forest() [2/3]

template<typename T>
forest ( const forest< T > & x)

Definition at line 746 of file forest.hpp.

◆ forest() [3/3]

template<typename T>
forest ( forest< T > && x)
noexcept

Definition at line 753 of file forest.hpp.

Member Function Documentation

◆ operator=() [1/2]

template<typename T>
forest & operator= ( const forest< T > & x)

Definition at line 593 of file forest.hpp.

◆ operator=() [2/2]

template<typename T>
forest & operator= ( forest< T > && x)
noexcept

Definition at line 598 of file forest.hpp.

◆ swap()

template<typename T>
void swap ( forest< T > & x)

Definition at line 760 of file forest.hpp.

◆ size()

template<typename T>
forest< T >::size_type size ( ) const
Returns
The number of nodes in the forest.
Complexity Guarantee(s)
O(1) if size is valid. O(N) if size is not valid. Some instances of splice() result in a forest where the size of the forest is not known by the end of the call. In other cases the size of the forest is cached, thus optimizing the complexity of the size() operation.
See Also
adobe::forest::splice

Definition at line 769 of file forest.hpp.

◆ max_size()

template<typename T>
size_type max_size ( ) const

Definition at line 608 of file forest.hpp.

◆ size_valid()

template<typename T>
bool size_valid ( ) const

Definition at line 609 of file forest.hpp.

◆ empty()

template<typename T>
bool empty ( ) const

Definition at line 610 of file forest.hpp.

◆ root() [1/2]

template<typename T>
iterator root ( )
Returns
An iterator to the root of the forest. Cannot be dereferenced.

Definition at line 613 of file forest.hpp.

◆ root() [2/2]

template<typename T>
const_iterator root ( ) const

Definition at line 614 of file forest.hpp.

◆ begin() [1/2]

template<typename T>
iterator begin ( )
Returns
An iterator to the first node in the forest.

Definition at line 616 of file forest.hpp.

◆ end() [1/2]

template<typename T>
iterator end ( )
Returns
An iterator to one-past-the last node in the forest.

Definition at line 617 of file forest.hpp.

◆ begin() [2/2]

template<typename T>
const_iterator begin ( ) const
Returns
An iterator to the first node in the forest.

Definition at line 618 of file forest.hpp.

◆ end() [2/2]

template<typename T>
const_iterator end ( ) const
Returns
An iterator to one-past-the last node in the forest.

Definition at line 619 of file forest.hpp.

◆ rbegin() [1/2]

template<typename T>
reverse_iterator rbegin ( )

Definition at line 621 of file forest.hpp.

◆ rend() [1/2]

template<typename T>
reverse_iterator rend ( )

Definition at line 622 of file forest.hpp.

◆ rbegin() [2/2]

template<typename T>
const_reverse_iterator rbegin ( ) const

Definition at line 623 of file forest.hpp.

◆ rend() [2/2]

template<typename T>
const_reverse_iterator rend ( ) const

Definition at line 624 of file forest.hpp.

◆ front() [1/2]

template<typename T>
reference front ( )
Returns
The first node in the forest.

Definition at line 626 of file forest.hpp.

◆ front() [2/2]

template<typename T>
const_reference front ( ) const
Returns
The first node in the forest.

Definition at line 630 of file forest.hpp.

◆ back() [1/2]

template<typename T>
reference back ( )
Returns
The last node in the forest.

Definition at line 634 of file forest.hpp.

◆ back() [2/2]

template<typename T>
const_reference back ( ) const
Returns
The last node in the forest.

Definition at line 638 of file forest.hpp.

◆ clear()

template<typename T>
void clear ( )

Definition at line 644 of file forest.hpp.

◆ erase() [1/2]

template<typename T>
forest< T >::iterator erase ( const iterator & position)
Parameters
positionan iterator to the node to be erased.
Returns
An iterator to the node succeeding the node erased.

Definition at line 805 of file forest.hpp.

◆ erase() [2/2]

template<typename T>
forest< T >::iterator erase ( const iterator & first,
const iterator & last )

This only erases nodes if the deletion iterator passes through the node twice. See the description below on deleting a node for a more illustrative example of range-based node deletion.

Parameters
firstan iterator to the first node to be erased.
lastan iterator to one-past-the last node to be erased.
Returns
An iterator to the node succeeding the last node erased.

Definition at line 783 of file forest.hpp.

◆ insert() [1/2]

template<typename T>
iterator insert ( const iterator & position,
T x )
Parameters
positionan iterator to the position of insertion.
xa value to be copy-constructed into position.
Returns
An iterator to the new node in its new location.

Definition at line 652 of file forest.hpp.

◆ push_front()

template<typename T>
void push_front ( const T & x)

Definition at line 664 of file forest.hpp.

◆ push_back()

template<typename T>
void push_back ( const T & x)

Definition at line 665 of file forest.hpp.

◆ pop_front()

template<typename T>
void pop_front ( )

Definition at line 666 of file forest.hpp.

◆ pop_back()

template<typename T>
void pop_back ( )

Definition at line 670 of file forest.hpp.

◆ insert() [2/2]

template<typename T>
forest< T >::iterator insert ( iterator position,
const_child_iterator first,
const_child_iterator last )

Inserts the sub-forest [first.base(), last.base()) at position.

Parameters
positionan iterator to the position of insertion.
firstan iterator to the beginning of the range to be inserted
lastan iterator to the end of the range to be inserted
Returns
An iterator to the first new node.
Complexity Guarantee(s)
Linear.

Definition at line 851 of file forest.hpp.

◆ splice() [1/4]

template<typename T>
forest< T >::iterator splice ( iterator position,
forest< T > & x )

All of the elements of x are inserted before position and removed from x.

Precondition
position must be a valid iterator in *this
x must be a forest that is distinct from *this.
Returns
An iterator to the spliced range. Either an iterator to the first element of x or position if x is empty.

Definition at line 835 of file forest.hpp.

◆ splice() [2/4]

template<typename T>
forest< T >::iterator splice ( iterator position,
forest< T > & x,
iterator i )

splice moves the element(s) pointed to by i from x to *this, inserting it before position. The range denoted by i is [leading_of(i), next(trailing_of(i)) ), any children of i are also moved. If position == leading_of(i) then no splice occurs.

Precondition
position may not be within the range denoted by i.
Postcondition
If &x != *this and i has children then size() and x.size() will be invalidated.
Returns
An iterator to the spliced range (leading_of(i)).

Definition at line 843 of file forest.hpp.

◆ splice() [3/4]

template<typename T>
forest< T >::iterator splice ( iterator position,
forest< T > & x,
child_iterator first,
child_iterator last )

splice moves the elements in [first, last) from x to *this, inserting them before position. If position == first.base() then no splice occurs.

Precondition
position my not be within the range [first, last).
Postcondition
If &x != *this and [first, last) is not empty then size() and x.size() will be invalidated.
Returns
An iterator to the spliced range. Either an iterator to first or position if [first, last) is empty.

Definition at line 894 of file forest.hpp.

◆ splice() [4/4]

template<typename T>
forest< T >::iterator splice ( iterator position,
forest< T > & x,
child_iterator first,
child_iterator last,
size_type count )

splice moves the elements in [first, last) from x to *this, inserting them before position. If position == first.base() then no splice occurs. The count parameter optionally specifies the distance [first, last) and avoids invalidating the size of the forests.

Precondition
position my not be within the range [first, last).
count is the distance from [first, last) or 0.
Postcondition
If c is 0 and &x != *this and [first, last) is not empty then size() and x.size() will be invalidated.
Returns
An iterator to the spliced range. Either an iterator to first or position if [first, last) is empty.

Definition at line 864 of file forest.hpp.

◆ insert_parent()

template<typename T>
forest< T >::iterator insert_parent ( child_iterator first,
child_iterator last,
const T & x )
Precondition
last must be arriveable at from first.
Returns
An iterator to the leading edge of the inserted node.

Definition at line 902 of file forest.hpp.

◆ reverse()

template<typename T>
void reverse ( child_iterator first,
child_iterator last )

Definition at line 914 of file forest.hpp.

◆ child_adaptor< forest< T > >

template<typename T>
friend class child_adaptor< forest< T > >
friend

Definition at line 557 of file forest.hpp.

◆ unsafe::set_next_fn< iterator >

template<typename T>
friend struct unsafe::set_next_fn< iterator >
friend

Definition at line 684 of file forest.hpp.

◆ pivot()

template<typename T>
void pivot ( I & iter)
related
Parameters
iterthe iterator whose edge will be flipped

Pivots the iterator from the leading to the trailing edge, or vice versa. The iterator itself is mutated to reflect the change.

Definition at line 44 of file forest.hpp.

◆ pivot_of()

template<typename T>
I pivot_of ( I iter)
related

Pivots the iterator from the leading to the trailing edge, or vice versa.

Parameters
iterthe iterator whose edge will be flipped
Returns
An iterator identical to the one passed in, save that the edge has been flipped

Definition at line 49 of file forest.hpp.

◆ trailing_of()

template<typename T>
C trailing_of ( C cursor)
related
Parameters
cursorthe cursor whose edge will be examined
Returns
A cursor identical to the one passed in, save that it will be on the trailing edge of the node to which it points.

◆ leading_of()

template<typename T>
C leading_of ( C cursor)
related
Parameters
cursorthe cursor whose edge will be examined
Returns
A cursor identical to the one passed in, save that it will be on the leading edge of the node to which it points.

◆ has_children()

template<typename T>
bool has_children ( const C & cursor)
related
Parameters
cursorThe cursor that whose node will be examined for children
Complexity Guarantee(s)
O(1)
Returns
Whether or not the node pointed to by the cursor has any children

◆ find_parent()

template<typename T>
ForestTraveler find_parent ( ForestTraveler traveler)
related
Parameters
traveleran iterator over a given forest.
Returns
The parent of traveler or forest end.
Complexity Guarantee(s)
Linear. Will traverse the siblings of traveler from [traveler, last_sibling).
Precondition
traveler is dereferenceable (not forest end).
Todo
(sparent) Open question if precondition should be checked and and function return traveler. This would rely on a "check root" for travelers.

◆ child_begin()

template<typename T>
child_iterator< BeadIterator > child_begin ( const BeadIterator & iter)
related
Returns
the first child for the node being pointed at by the iterator

◆ child_end()

template<typename T>
child_iterator< BeadIterator > child_end ( const BeadIterator & iter)
related
Returns
one-past-the-last child for the node being pointed at by the iterator

◆ filter_fullorder_range() [1/2]

template<typename R, typename P>
auto filter_fullorder_range ( R & x,
P p ) -> boost::iterator_range< filter_fullorder_iterator<typename boost::range_iterator<R>::type, P>>
related
Parameters
xthe FullorderRange to which the filter will be applied
pthe predicate to be applied to the FullorderIterator
Returns
A filtered FullorderRange

Definition at line 991 of file forest.hpp.

◆ filter_fullorder_range() [2/2]

template<typename R, typename P>
auto filter_fullorder_range ( const R & x,
P p ) -> boost::iterator_range< filter_fullorder_iterator<typename boost::range_const_iterator<R>::type, P>>
related
Parameters
xthe const FullorderRange to which the filter will be applied
pthe predicate to be applied to value_type(R)
Returns
A filtered FullorderRange

Definition at line 1009 of file forest.hpp.

◆ reverse_fullorder_range() [1/2]

template<typename R>
auto reverse_fullorder_range ( R & x) -> boost::iterator_range<reverse_fullorder_iterator<typename boost::range_iterator<R>::type>>
related
Parameters
xthe FullorderRange which will be reversed
Returns
A reverse FullorderRange

Definition at line 1039 of file forest.hpp.

◆ reverse_fullorder_range() [2/2]

template<typename R>
boost::iterator_range< reverse_fullorder_iterator< typename boost::range_const_iterator< R >::type > > reverse_fullorder_range ( const R & x)
related
Parameters
xthe const FullorderRange which will be reversed
Returns
A const reverse FullorderRange

Definition at line 1058 of file forest.hpp.

◆ depth_range() [1/2]

template<typename R>
boost::iterator_range< depth_fullorder_iterator< typename boost::range_iterator< R >::type > > depth_range ( R & x)
related
Parameters
xthe FullorderRange which will be made into a depth FullorderRange
Returns
A depth FullorderRange

Definition at line 1078 of file forest.hpp.

◆ depth_range() [2/2]

template<typename R>
boost::iterator_range< depth_fullorder_iterator< typename boost::range_const_iterator< R >::type > > depth_range ( const R & x)
related
Parameters
xthe const FullorderRange which will be made into a const depth FullorderRange
Returns
A const depth FullorderRange

Definition at line 1096 of file forest.hpp.

◆ postorder_range() [1/2]

template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_iterator< R >::type, forest_trailing_edge > > postorder_range ( R & x)
related
Parameters
xthe FullorderRange which will be made into a postorder range
Returns
A postorder range

Definition at line 1116 of file forest.hpp.

◆ postorder_range() [2/2]

template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_const_iterator< R >::type, forest_trailing_edge > > postorder_range ( const R & x)
related
Parameters
xthe const FullorderRange which will be made into a const postorder range
Returns
A const postorder range

Definition at line 1134 of file forest.hpp.

◆ preorder_range() [1/2]

template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_iterator< R >::type, forest_leading_edge > > preorder_range ( R & x)
related
Parameters
xthe FullorderRange which will be made into a preorder range
Returns
A preorder range

Definition at line 1155 of file forest.hpp.

◆ preorder_range() [2/2]

template<typename R>
boost::iterator_range< edge_iterator< typename boost::range_const_iterator< R >::type, forest_leading_edge > > preorder_range ( const R & x)
related
Parameters
xthe const FullorderRange which will be made into a const preorder range
Returns
A const preorder range

Definition at line 1173 of file forest.hpp.

◆ transform_forest() [1/4]

template<typename SourceForestIterType, typename DestForestType, typename UnaryFunction>
void transform_forest ( SourceForestIterType first,
SourceForestIterType last,
DestForestType & destForest,
typename DestForestType::iterator destIter,
UnaryFunction transformFunc )
related

Transforms the elements in [first, last) with transformFunc and insert into destForest at destIter.

Parameters
firstiterator to the beginning of the range to be transformed
lastiterator to one-past the last element of the range to be transformed
destForestforest that the transformed elements should be inserted into
destIteriterator to the location in destForest where the transformed elements should be inserted
transformFuncfunction for transforming elements in the range

Definition at line 1198 of file forest.hpp.

◆ transform_forest() [2/4]

template<typename SourceForestIterType, typename DestForestType, typename UnaryFunction>
void transform_forest ( SourceForestIterType first,
SourceForestIterType last,
DestForestType & destForest,
UnaryFunction transformFunc )
related

Transforms the elements in [first, last) with transformFunc and insert at the end of destForest.

Parameters
firstiterator to the beginning of the range to be transformed
lastiterator to one-past the last element of the range to be transformed
destForestforest that the transformed elements should be inserted into
transformFuncfunction for transforming elements in the range

Definition at line 1233 of file forest.hpp.

◆ transform_forest() [3/4]

template<typename SourceForestType, typename DestForestType, typename UnaryFunction>
void transform_forest ( SourceForestType sourceForest,
DestForestType & destForest,
typename DestForestType::iterator destIter,
UnaryFunction transformFunc )
related

Transforms the elements in sourceForest with transformFunc and insert into destForest at destIter.

Parameters
sourceForestforest containing the elements to be transformed
destForestforest that the transformed elements should be inserted into
destIteriterator to the location in destForest where the transformed elements should be inserted
transformFuncfunction for transforming elements in the range

Definition at line 1253 of file forest.hpp.

◆ transform_forest() [4/4]

template<typename SourceForestType, typename DestForestType, typename UnaryFunction>
void transform_forest ( SourceForestType sourceForest,
DestForestType & destForest,
UnaryFunction transformFunc )
related

Transforms the elements in sourceForest with transformFunc and insert at the end of destForest.

Parameters
sourceForestforest containing the elements to be transformed
destForestforest that the transformed elements should be inserted into
transformFuncfunction for transforming elements in the range

Definition at line 1272 of file forest.hpp.