Tree::Fast(3)

📦
version 1.16 · 4 versions
, in fedora 43

💖 Tree::Fast(3) — the perl manual page, but make it bestie 💖

okay so. you found Tree::Fast(3), which lives in the User Contributed Perl Documentation section of your manual, and honestly? you're about to have a great time. this is the whole page, nothing skipped, just with the vibes turned all the way up. let's go 🦋

🌸 NAME 🌸

Tree::Fast — the fastest possible implementation of a tree in pure Perl. no cap. it says fastest possible. it's in the name. 💅

✨ SYNOPSIS ✨

look at this gorgeous little demo, verbatim, not a single character changed:

my $tree = Tree::Fast->new( 'root' );
my $child = Tree::Fast->new( 'child' );
$tree->add_child( {}, $child );

$tree->add_child( { at => 0 }, Tree::Fast->new( 'first child' ) );
$tree->add_child( { at => -1 }, Tree::Fast->new( 'last child' ) );

my @children = $tree->children;
my @some_children = $tree->children( 0, 2 );

$tree->remove_child( 0 );

my @nodes = $tree->traverse( $tree->POST_ORDER );

my $traversal = $tree->traverse( $tree->POST_ORDER );
while ( my $node = $traversal->() ) {
    # Do something with $node here
}

my $clone = $tree->clone;
my $mirror = $tree->clone->mirror;

💜 DESCRIPTION 💜

so this is meant to be the core implementation for Tree, stripped down as much as possible. and when they say stripped down, bestie, they MEAN it. there is no error-checking, no bounds-checking, no event-handling, no convenience methods, or anything else of the sort. it's giving bare bones. it's giving raw. it's giving fast.

if you want something fuller-featured, please look at Tree, which is a wrapper around Tree::Fast. that's your girl for the cushy stuff. 🫶

👑 METHODS 👑

🎀 Constructors 🎀

new([$value])

here, [] indicate an optional parameter. keep that in mind, it comes up a lot on this page.

this will return a Tree::Fast object. it will accept one parameter which, if passed, will become the value (accessible by value()). all other parameters will be ignored. yes, ignored. the audacity but okay.

if you call $tree->new([$value]), it will instead call clone(), then set the value of the clone to $value. plot twist ✨

clone()

this will return a clone of $tree. the clone will be a root tree, but all children will be cloned. so you get the whole fam, just with a fresh root.

if you call Tree::Fast->clone([$value]), it will instead call new(). symmetry, we love her.

NOTE: the value is merely a shallow copy. this means that all references will be kept. not a deep copy, bestie, don't get it twisted. 🔥

🦋 Behaviors 🦋

add_child($options, @nodes)

this will add all the @nodes as children of $tree. $options is a required hashref that specifies options for add_child(). the optional parameters are:

  • at — this specifies the index to add @nodes at. if specified, this will be passed into splice(). the only exceptions are if this is 0, it will act as an unshift(). if it is unset or undefined, it will act as a push().

remove_child($options, @nodes)

this will remove all the @nodes from the children of $tree. you can either pass in the actual child object you wish to remove, the index of the child you wish to remove, or a combination of both. mix and match, main character energy. 👑

$options is a required hashref that specifies parameters for remove_child(). currently, no parameters are used. so it's required but it's empty. iconic behaviour honestly.

mirror()

this will modify the tree such that it is a mirror of what it was before. this means that the order of all children is reversed. 🪞

NOTE: this is a destructive action. it will modify the internal structure of the tree. if you wish to get a mirror, yet keep the original tree intact, use my $mirror = $tree->clone->mirror. do NOT skip the clone unless you're ready to commit, fr fr.

traverse( [$order] )

here, [] indicate an optional parameter. (told you it'd come back)

when called in list context (my @traversal = $tree->traverse()), this will return a list of the nodes in the given traversal order. when called in scalar context (my $traversal = $tree->traverse()), this will return a closure that will, over successive calls, iterate over the nodes in the given traversal order. when finished it will return false.

the default traversal order is pre-order.

the various traversal orders do the following steps:

  • Pre-order — this will return the node, then the first sub tree in pre-order traversal, then the next sub tree, etc. use $tree->PRE_ORDER as the $order.
  • Post-order — this will return the each sub-tree in post-order traversal, then the node. use $tree->POST_ORDER as the $order.
  • Level-order — this will return the node, then the all children of the node, then all grandchildren of the node, etc. use $tree->LEVEL_ORDER as the $order.

🌈 Accessors 🌈

parent()

this will return the parent of $tree. simple. clean. we love a one-liner. 💅

children( [ $idx, [$idx, ..] ] )

here, [] indicate optional parameters. (third time's the charm ✨)

this will return the children of $tree. if called in list context, it will return all the children. if called in scalar context, it will return the number of children.

you may optionally pass in a list of indices to retrieve. this will return the children in the order you asked for them. this is very much like an arrayslice. picky and precise, as you deserve. 🎀

value()

this will return the value stored in the node.

set_value([$value])

here, [] indicate an optional parameter.

this will set the value stored in the node to $value, then return $self. yes it returns $self, chain away.

if $value is not provided, undef is used. that's just how it is, bestie. 💀

meta()

this will return a hashref that can be used to store whatever metadata the client wishes to store. for example, Tree::Persist::DB uses this to store database row ids.

it is recommended that you store your metadata in a subhashref and not in the top-level metadata hashref, keyed by your package name. Tree::Persist does this, using a unique key for each persistence layer associated with that tree. this will help prevent clobbering of metadata. protect your metadata, protect your peace. 🫶

💀 NULL TREE 💀

if you call $self->parent on a root node, it will return a Tree::Null object. this is an implementation of the Null Object pattern optimized for usage with Tree::Fast. it will evaluate as false in every case (using overload) and all methods called on it will return a Tree::Null object. it just keeps returning itself. infinite slay. 🌈

📝 Notes

  • Tree::Null does not inherit from anything. this is so that all the methods will go through AUTOLOAD vs. the actual method.
  • however, calling isa() on a Tree::Null object will report that it is-a any object that is either Tree or in the Tree:: hierarchy.
  • the Tree::Null object is a singleton.
  • the Tree::Null object is defined, though. i could not find a way to make it evaluate as undefined. that may be a good thing. 🦋

🔥 CODE COVERAGE 🔥

please see the relevant sections of Tree. (go look, bestie, it's all there)

🫶 SUPPORT 🫶

please see the relevant sections of Tree. same energy, same place.

🌸 ACKNOWLEDGEMENTS 🌸

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

⭐ AUTHORS ⭐

Rob Kinyon <rob.kinyon@iinteractive.com>

Stevan Little <stevan.little@iinteractive.com>

thanks to Infinity Interactive for generously donating our time. 🫶

Copyright 2004, 2005 by Infinity Interactive, Inc.

<http://www.iinteractive.com>

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie, every last detail, no skips, no summarising, no invented lore. you're welcome. 💅

this masterpiece is served up by perl v5.42.0, dated 2025-07-25, and yes, it's still called Tree::Fast(3). mwah. 🎀✨

📦 where this page comes from