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

NULL TREE

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

CODE COVERAGE

180       Please see the relevant sections of Tree.
181

SUPPORT

183       Please see the relevant sections of Tree.
184

ACKNOWLEDGEMENTS

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

AUTHORS

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

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