NAME
Tree::RB::XS::Node
SYNOPSIS
my $node= $tree->get_node('x');
my $node= $tree->nth(4);
$node->value(7);
$node->value++;
$node->mark_newest if $node->recent_tracked;
$node->prune if $node->tree && $node->key =~ /foo/;DESCRIPTION
Node objects represent an internal node of the Red/Black tree. A tree node exists as lightweight C struct until you access it from Perl, at which time it inflates to become a blessed hashref object. This object does not hold a strong reference to the tree; if the tree goes out of scope, the node object remains but no longer has a relation to other nodes.
Nodes can only be created by a tree, and cannot be re-inserted once pruned.
ATTRIBUTES
key
The sort key. Writing this attribute will re-key the node, but will not affect it's placement in the 'recent' list. Beware that it is possible to create a mutable key (using tie, or using custom compare functions on references), and altering the value of the key without calling this accessor will corrupt the sorting of your tree. Also beware that in trees where duplicates are not allowed, setting this to the same key as another node will automatically prune the other node from the tree.
Depending on the compare function, keys may be restricted to integers, numbers, strings or other limitations.
value
The data associated with the node. Read/Write. This also returns an lvalue so you can directly modify or assign new values to the accessor.
index
The integer position of this node within its tree, as if the tree were an array.
prev
The previous node in the sequence of keys. Alias predecessor for Tree::RB::Node compat.
next
The next node in the sequence of keys. Alias successor for Tree::RB::Node compat.
recent_tracked
Returns whether node has its insertion order tracked, or not. This attribute can also be written. Disabling recent_tracked removes it from the list of insertion order. Enabling recent_tracked causes the node to be placed as the newest inserted node, the same as "mark_newest".
mark_newest
Promote this node to the end of the insertion-order tracking list as if it has just been inserted.
older
$older= $node->older;
$node->older($insert_before);The previous node in insertion-order. Always undef unless node is "recent_tracked". When written, it places that node before this node in the "recent" list.
newer
$older= $node->newer;
$node->newer($insert_after);The next node in insertion-order. Always undef unless node is "recent_tracked". When written, it places that node after this node in the "recent" list.
tree
The tree this node belongs to. This becomes undef if the tree is freed or if the node is pruned from the tree.
left
The left sub-tree.
left_leaf
The left-most leaf of the sub-tree. Alias min for Tree::RB::Node compat.
right
The right sub-tree.
right_leaf
The right-most child of the sub-tree. Alias max for Tree::RB::Node compat.
parent
The parent node, if any.
color
0 = black, 1 = red.
count
The number of items in the tree rooted at this node (inclusive). This becomes 0 if the node is no longer in the tree.
METHODS
prune
Remove this single node from the tree. The node will still have its key and value, but all attributes linking to other nodes will become undef, and "count" becomes zero.
strip
Remove all children of this node, optionally calling a callback for each. For compat with "strip" in Tree::RB::Node.
as_lol
Return sub-tree as list-of-lists. (array of arrays rather?) For compat with "as_lol" in Tree::RB::Node.
iter
Shortcut for $node->tree->iter($node).
rev_iter
Shortcut for $node->tree->rev_iter($node).
iter_newer
Shortcut for $node->tree->iter_old_to_new($node).
iter_older
Shortcut for $node->tree->iter_new_to_old($node).
VERSION
version 0.20
AUTHOR
Michael Conrad <mike@nrdvana.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2025 by Michael Conrad.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.