1Tree::Fast(3)         User Contributed Perl Documentation        Tree::Fast(3)
2
3
4

NAME

6       Tree::Fast - the fastest possible implementation of a tree in pure Perl
7

SYNOPSIS

9         my $tree = Tree::Fast->new( 'root' );
10         my $child = Tree::Fast->new( 'child' );
11         $tree->add_child( {}, $child );
12
13         $tree->add_child( { at => 0 }, Tree::Fast->new( 'first child' ) );
14         $tree->add_child( { at => -1 }, Tree::Fast->new( 'last child' ) );
15
16         my @children = $tree->children;
17         my @some_children = $tree->children( 0, 2 );
18
19         $tree->remove_child( 0 );
20
21         my @nodes = $tree->traverse( $tree->POST_ORDER );
22
23         my $traversal = $tree->traverse( $tree->POST_ORDER );
24         while ( my $node = $traversal->() ) {
25             # Do something with $node here
26         }
27
28         my $clone = $tree->clone;
29         my $mirror = $tree->clone->mirror;
30

DESCRIPTION

32       This is meant to be the core implementation for Tree, stripped down as
33       much as possible. There is no error-checking, bounds-checking, event-
34       handling, convenience methods, or anything else of the sort. If you
35       want something fuller-featured, please look at Tree, which is a wrapper
36       around Tree::Fast.
37

METHODS

39   Constructors
40   new([$value])
41       Here, [] indicate an optional parameter.
42
43       This will return a "Tree::Fast" object. It will accept one parameter
44       which, if passed, will become the value (accessible by "value()"). All
45       other parameters will be ignored.
46
47       If you call "$tree->new([$value])", it will instead call "clone()",
48       then set the value of the clone to $value.
49
50   clone()
51       This will return a clone of $tree. The clone will be a root tree, but
52       all children will be cloned.
53
54       If you call "Tree::Fast->clone([$value])", it will instead call
55       "new()".
56
57       NOTE: the value is merely a shallow copy. This means that all
58       references will be kept.
59
60   Behaviors
61   add_child($options, @nodes)
62       This will add all the @nodes as children of $tree. $options is a
63       required hashref that specifies options for "add_child()". The optional
64       parameters are:
65
66       •   at
67
68           This specifies the index to add @nodes at. If specified, this will
69           be passed into splice(). The only exceptions are if this is 0, it
70           will act as an unshift(). If it is unset or undefined, it will act
71           as a push().
72
73   remove_child($options, @nodes)
74       This will remove all the @nodes from the children of $tree. You can
75       either pass in the actual child object you wish to remove, the index of
76       the child you wish to remove, or a combination of both.
77
78       $options is a required hashref that specifies parameters for
79       remove_child().  Currently, no parameters are used.
80
81   mirror()
82       This will modify the tree such that it is a mirror of what it was
83       before. This means that the order of all children is reversed.
84
85       NOTE: This is a destructive action. It will modify the internal
86       structure of the tree. If you wish to get a mirror, yet keep the
87       original tree intact, use "my $mirror = $tree->clone->mirror".
88
89   traverse( [$order] )
90       Here, [] indicate an optional parameter.
91
92       When called in list context ("my @traversal = $tree->traverse()"), this
93       will return a list of the nodes in the given traversal order. When
94       called in scalar context ("my $traversal = $tree->traverse()"), this
95       will return a closure that will, over successive calls, iterate over
96       the nodes in the given traversal order. When finished it will return
97       false.
98
99       The default traversal order is pre-order.
100
101       The various traversal orders do the following steps:
102
103       •   Pre-order
104
105           This will return the node, then the first sub tree in pre-order
106           traversal, then the next sub tree, etc.
107
108           Use "$tree->PRE_ORDER" as the $order.
109
110       •   Post-order
111
112           This will return the each sub-tree in post-order traversal, then
113           the node.
114
115           Use "$tree->POST_ORDER" as the $order.
116
117       •   Level-order
118
119           This will return the node, then the all children of the node, then
120           all grandchildren of the node, etc.
121
122           Use "$tree->LEVEL_ORDER" as the $order.
123
124   Accessors
125   parent()
126       This will return the parent of $tree.
127
128   children( [ $idx, [$idx, ..] ] )
129       Here, [] indicate optional parameters.
130
131       This will return the children of $tree. If called in list context, it
132       will return all the children. If called in scalar context, it will
133       return the number of children.
134
135       You may optionally pass in a list of indices to retrieve. This will
136       return the children in the order you asked for them. This is very much
137       like an arrayslice.
138
139   value()
140       This will return the value stored in the node.
141
142   set_value([$value])
143       Here, [] indicate an optional parameter.
144
145       This will set the value stored in the node to $value, then return
146       $self.
147
148       If $value is not provided, undef is used.
149
150   meta()
151       This will return a hashref that can be used to store whatever metadata
152       the client wishes to store. For example, Tree::Persist::DB uses this to
153       store database row ids.
154
155       It is recommended that you store your metadata in a subhashref and not
156       in the top-level metadata hashref, keyed by your package name.
157       Tree::Persist does this, using a unique key for each persistence layer
158       associated with that tree.  This will help prevent clobbering of
159       metadata.
160

NULL TREE

162       If you call "$self->parent" on a root node, it will return a Tree::Null
163       object. This is an implementation of the Null Object pattern optimized
164       for usage with Tree::Fast. It will evaluate as false in every case
165       (using overload) and all methods called on it will return a Tree::Null
166       object.
167
168   Notes
169       •   Tree::Null does not inherit from anything. This is so that all the
170           methods will go through AUTOLOAD vs. the actual method.
171
172       •   However, calling isa() on a Tree::Null object will report that it
173           is-a any object that is either Tree or in the Tree:: hierarchy.
174
175       •   The Tree::Null object is a singleton.
176
177       •   The Tree::Null object is defined, though. I could not find a way to
178           make it evaluate as undefined. That may be a good thing.
179

CODE COVERAGE

181       Please see the relevant sections of Tree.
182

SUPPORT

184       Please see the relevant sections of Tree.
185

ACKNOWLEDGEMENTS

187       •   Stevan Little for writing Tree::Simple, upon which Tree is based.
188

AUTHORS

190       Rob Kinyon <rob.kinyon@iinteractive.com>
191
192       Stevan Little <stevan.little@iinteractive.com>
193
194       Thanks to Infinity Interactive for generously donating our time.
195

197       Copyright 2004, 2005 by Infinity Interactive, Inc.
198
199       <http://www.iinteractive.com>
200
201       This library is free software; you can redistribute it and/or modify it
202       under the same terms as Perl itself.
203
204
205
206perl v5.32.1                      2021-02-02                     Tree::Fast(3)
Impressum