Name
Tree::Multi - Multi-way tree in Pure Perl with an even or odd number of keys per node.
Synopsis
Construct and query a multi-way tree in 100% Pure Perl with a choice of an odd or an even numbers of keys per node: local $Tree::Multi::numberOfKeysPerNode = 4; # Number of keys per node - can be even
my $t = Tree::Multi::new; # Construct tree
$t->insert($_, 2 * $_) for reverse 1..32; # Load tree in reverse
is_deeply $t->print, <<END;
15 21 27
3 6 9 12
1 2
4 5
7 8
10 11
13 14
18
16 17
19 20
24
22 23
25 26
30
28 29
31 32
END
ok $t->height == 3; # Height
ok $t->find (16) == 32; # Find by key
$t->delete(16); # Delete a key
ok !$t->find (16); # Key no longer present
ok $t->find (17) == 34; # Find by key
my @k;
for(my $i = $t->iterator; $i->more; $i->next) # Iterator
{push @k, $i->key unless $i->key == 17;
}
$t->delete($_) for @k; # Delete
ok $t->find(17) == 34 && $t->size == 1; # Size
Description
Multi-way tree in Pure Perl with an even or odd number of keys per node.
Version "20210602".
The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.
Multi-way Tree
Create and use a multi-way tree.
root($tree)
Return the root node of a tree.
Parameter Description
1 $tree Tree
Example:
local $numberOfKeysPerNode = 3; my $N = 13; my $t = new;
for my $n(1..$N)
{$t->insert($n, $n);
}
is_deeply $t->leftMost ->keys, [1, 2];
is_deeply $t->rightMost->keys, [13];
ok $t->leftMost ->leaf;
ok $t->rightMost->leaf;
ok $t->root == $t; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok T($t, <<END);
6
3
1 2
4 5
9 12
7 8
10 11
13
END
leaf($tree)
Confirm that the tree is a leaf.
Parameter Description
1 $tree Tree
Example:
local $numberOfKeysPerNode = 3; my $N = 13; my $t = new;
for my $n(1..$N)
{$t->insert($n, $n);
}
is_deeply $t->leftMost ->keys, [1, 2];
is_deeply $t->rightMost->keys, [13];
ok $t->leftMost ->leaf; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok $t->rightMost->leaf; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok $t->root == $t;
ok T($t, <<END);
6
3
1 2
4 5
9 12
7 8
10 11
13
END
find($root, $key)
Find a key in a tree returning its associated data or undef if the key does not exist
Parameter Description
1 $root Root of tree
2 $key Key
Example:
local $Tree::Multi::numberOfKeysPerNode = 4; # Number of keys per node - can be even
my $t = Tree::Multi::new; # Construct tree
$t->insert($_, 2 * $_) for reverse 1..32; # Load tree in reverse
is_deeply $t->print, <<END;
15 21 27
3 6 9 12
1 2
4 5
7 8
10 11
13 14
18
16 17
19 20
24
22 23
25 26
30
28 29
31 32
END
ok $t->height == 3; # Height
ok $t->find (16) == 32; # Find by key # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->delete(16); # Delete a key
ok !$t->find (16); # Key no longer present # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok $t->find (17) == 34; # Find by key # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
my @k;
for(my $i = $t->iterator; $i->more; $i->next) # Iterator
{push @k, $i->key unless $i->key == 17;
}
$t->delete($_) for @k; # Delete
ok $t->find(17) == 34 && $t->size == 1; # Size # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
leftMost($tree)
Return the left most node below the specified one
Parameter Description
1 $tree Tree
Example:
local $numberOfKeysPerNode = 3; my $N = 13; my $t = new;
for my $n(1..$N)
{$t->insert($n, $n);
}
is_deeply $t->leftMost ->keys, [1, 2]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
is_deeply $t->rightMost->keys, [13];
ok $t->leftMost ->leaf; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok $t->rightMost->leaf;
ok $t->root == $t;
ok T($t, <<END);
6
3
1 2
4 5
9 12
7 8
10 11
13
END
rightMost($tree)
Return the right most node below the specified one
Parameter Description
1 $tree Tree
Example:
local $numberOfKeysPerNode = 3; my $N = 13; my $t = new;
for my $n(1..$N)
{$t->insert($n, $n);
}
is_deeply $t->leftMost ->keys, [1, 2];
is_deeply $t->rightMost->keys, [13]; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok $t->leftMost ->leaf;
ok $t->rightMost->leaf; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok $t->root == $t;
ok T($t, <<END);
6
3
1 2
4 5
9 12
7 8
10 11
13
END
height($tree)
Return the height of the tree
Parameter Description
1 $tree Tree
Example:
local $Tree::Multi::numberOfKeysPerNode = 3;
my $t = new; ok $t->height == 0; ok $t->leftMost->depth == 0; ok $t->size == 0; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(1, 1); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(2, 2); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(3, 3); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(4, 4); ok $t->height == 2; ok $t->leftMost->depth == 2; ok $t->size == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
depth($tree)
Return the depth of a node within a tree
Parameter Description
1 $tree Tree
Example:
local $Tree::Multi::numberOfKeysPerNode = 3;
my $t = new; ok $t->height == 0; ok $t->leftMost->depth == 0; ok $t->size == 0; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(1, 1); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(2, 2); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(3, 3); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(4, 4); ok $t->height == 2; ok $t->leftMost->depth == 2; ok $t->size == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
delete($root, $key)
Find a key in a tree, delete it, return the new tree
Parameter Description
1 $root Tree root
2 $key Key
Example:
local $Tree::Multi::numberOfKeysPerNode = 4; # Number of keys per node - can be even
my $t = Tree::Multi::new; # Construct tree
$t->insert($_, 2 * $_) for reverse 1..32; # Load tree in reverse
is_deeply $t->print, <<END;
15 21 27
3 6 9 12
1 2
4 5
7 8
10 11
13 14
18
16 17
19 20
24
22 23
25 26
30
28 29
31 32
END
ok $t->height == 3; # Height
ok $t->find (16) == 32; # Find by key
$t->delete(16); # Delete a key # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok !$t->find (16); # Key no longer present
ok $t->find (17) == 34; # Find by key
my @k;
for(my $i = $t->iterator; $i->more; $i->next) # Iterator
{push @k, $i->key unless $i->key == 17;
}
$t->delete($_) for @k; # Delete # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
ok $t->find(17) == 34 && $t->size == 1; # Size
insert($tree, $key, $data)
Insert a key and data into a tree
Parameter Description
1 $tree Tree
2 $key Key
3 $data Data
Example:
local $Tree::Multi::numberOfKeysPerNode = 4; # Number of keys per node - can be even
my $t = Tree::Multi::new; # Construct tree
$t->insert($_, 2 * $_) for reverse 1..32; # Load tree in reverse # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
is_deeply $t->print, <<END;
15 21 27
3 6 9 12
1 2
4 5
7 8
10 11
13 14
18
16 17
19 20
24
22 23
25 26
30
28 29
31 32
END
ok $t->height == 3; # Height
ok $t->find (16) == 32; # Find by key
$t->delete(16); # Delete a key
ok !$t->find (16); # Key no longer present
ok $t->find (17) == 34; # Find by key
my @k;
for(my $i = $t->iterator; $i->more; $i->next) # Iterator
{push @k, $i->key unless $i->key == 17;
}
$t->delete($_) for @k; # Delete
ok $t->find(17) == 34 && $t->size == 1; # Size
iterator($tree)
Make an iterator for a tree
Parameter Description
1 $tree Tree
Example:
local $numberOfKeysPerNode = 3; my $N = 256; my $e = 0; my $t = new;
for my $n(0..$N)
{$t->insert($n, $n);
my @n; for(my $i = $t->iterator; $i->more; $i->next) {push @n, $i->key} # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
++$e unless dump(\@n) eq dump [0..$n];
}
is_deeply $e, 0;
local $Tree::Multi::numberOfKeysPerNode = 4; # Number of keys per node - can be even
my $t = Tree::Multi::new; # Construct tree
$t->insert($_, 2 * $_) for reverse 1..32; # Load tree in reverse
is_deeply $t->print, <<END;
15 21 27
3 6 9 12
1 2
4 5
7 8
10 11
13 14
18
16 17
19 20
24
22 23
25 26
30
28 29
31 32
END
ok $t->height == 3; # Height
ok $t->find (16) == 32; # Find by key
$t->delete(16); # Delete a key
ok !$t->find (16); # Key no longer present
ok $t->find (17) == 34; # Find by key
my @k;
for(my $i = $t->iterator; $i->more; $i->next) # Iterator # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
{push @k, $i->key unless $i->key == 17;
}
$t->delete($_) for @k; # Delete
ok $t->find(17) == 34 && $t->size == 1; # Size
Tree::Multi::Iterator::next($iter)
Find the next key
Parameter Description
1 $iter Iterator
Example:
local $numberOfKeysPerNode = 3; my $N = 256; my $e = 0; my $t = new;
for my $n(0..$N)
{$t->insert($n, $n);
my @n; for(my $i = $t->iterator; $i->more; $i->next) {push @n, $i->key}
++$e unless dump(\@n) eq dump [0..$n];
}
is_deeply $e, 0;
reverseIterator($tree)
Create a reverse iterator for a tree
Parameter Description
1 $tree Tree
Example:
local $numberOfKeysPerNode = 3; my $N = 64; my $e = 0;
for my $n(0..$N)
{my $t = new;
for my $i(0..$n)
{$t->insert($i, $i);
}
my @n;
for(my $i = $t->reverseIterator; $i->less; $i->prev) # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
{push @n, $i->key;
}
++$e unless dump(\@n) eq dump [reverse 0..$n];
}
is_deeply $e, 0;
Tree::Multi::ReverseIterator::prev($iter)
Find the previous key
Parameter Description
1 $iter Iterator
Example:
local $numberOfKeysPerNode = 3; my $N = 64; my $e = 0;
for my $n(0..$N)
{my $t = new;
for my $i(0..$n)
{$t->insert($i, $i);
}
my @n;
for(my $i = $t->reverseIterator; $i->less; $i->prev)
{push @n, $i->key;
}
++$e unless dump(\@n) eq dump [reverse 0..$n];
}
is_deeply $e, 0;
print($tree, $i)
Print the keys in a tree optionally marking the active key
Parameter Description
1 $tree Tree
2 $i Optional index of active key
Example:
local $Tree::Multi::numberOfKeysPerNode = 4; # Number of keys per node - can be even
my $t = Tree::Multi::new; # Construct tree
$t->insert($_, 2 * $_) for reverse 1..32; # Load tree in reverse
is_deeply $t->print, <<END; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
15 21 27
3 6 9 12
1 2
4 5
7 8
10 11
13 14
18
16 17
19 20
24
22 23
25 26
30
28 29
31 32
END
ok $t->height == 3; # Height
ok $t->find (16) == 32; # Find by key
$t->delete(16); # Delete a key
ok !$t->find (16); # Key no longer present
ok $t->find (17) == 34; # Find by key
my @k;
for(my $i = $t->iterator; $i->more; $i->next) # Iterator
{push @k, $i->key unless $i->key == 17;
}
$t->delete($_) for @k; # Delete
ok $t->find(17) == 34 && $t->size == 1; # Size
size($tree)
Count the number of keys in a tree
Parameter Description
1 $tree Tree
Example:
local $Tree::Multi::numberOfKeysPerNode = 3;
my $t = new; ok $t->height == 0; ok $t->leftMost->depth == 0; ok $t->size == 0; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(1, 1); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 1; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(2, 2); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 2; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(3, 3); ok $t->height == 1; ok $t->leftMost->depth == 1; ok $t->size == 3; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert(4, 4); ok $t->height == 2; ok $t->leftMost->depth == 2; ok $t->size == 4; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
Tree::Multi Definition
Iterator
Output fields
count
Counter
data
Data at this position
key
Key at this position
keys
Array of key items for this node
less
Iteration not yet finished
more
Iteration not yet finished
node
Current node within tree
number
Number of the node for debugging purposes
pos
Current position within node
tree
Tree we are iterating over
up
Parent node
Private Methods
new()
Create a new multi-way tree node.
Example:
local $Tree::Multi::numberOfKeysPerNode = 4; # Number of keys per node - can be even
my $t = Tree::Multi::new; # Construct tree # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
$t->insert($_, 2 * $_) for reverse 1..32; # Load tree in reverse
is_deeply $t->print, <<END;
15 21 27
3 6 9 12
1 2
4 5
7 8
10 11
13 14
18
16 17
19 20
24
22 23
25 26
30
28 29
31 32
END
ok $t->height == 3; # Height
ok $t->find (16) == 32; # Find by key
$t->delete(16); # Delete a key
ok !$t->find (16); # Key no longer present
ok $t->find (17) == 34; # Find by key
my @k;
for(my $i = $t->iterator; $i->more; $i->next) # Iterator
{push @k, $i->key unless $i->key == 17;
}
$t->delete($_) for @k; # Delete
ok $t->find(17) == 34 && $t->size == 1; # Size
minimumNumberOfKeys()
Minimum number of keys per node.
maximumNumberOfKeys()
Maximum number of keys per node.
maximumNumberOfNodes()
Maximum number of children per parent.
full($tree)
Confirm that a node is full.
Parameter Description
1 $tree Tree
halfFull($tree)
Confirm that a node is half full.
Parameter Description
1 $tree Tree
separateKeys($node)
Return ([lower], center, [upper]) keys.
Parameter Description
1 $node Node to split
separateData($node)
Return ([lower], center, [upper]) data
Parameter Description
1 $node Node to split
separateNode($node)
Return ([lower], [upper]) children
Parameter Description
1 $node Node to split
reUp($node, @children)
Reconnect the children to their new parent
Parameter Description
1 $node Node
2 @children Children
splitNode($node)
Split a full node in half assuming it has a non full parent
Parameter Description
1 $node Node to split
splitRootNode($node)
Split a full root
Parameter Description
1 $node Node to split
splitFullNode($node)
Split a full node
Parameter Description
1 $node Node to split
splitLeafNode($node)
Split a full leaf node in assuming it has a non full parent
Parameter Description
1 $node Node to split
splitRootLeafNode($node)
Split a full root that is also a leaf
Parameter Description
1 $node Node to split
findAndSplit($root, $key)
Find a key in a tree splitting full nodes along the path to the key
Parameter Description
1 $root Root of tree
2 $key Key
indexInParent($tree)
Get the index of a node in its parent
Parameter Description
1 $tree Tree
fillFromLeftOrRight($n, $dir)
Fill a node from the specified sibling
Parameter Description
1 $n Node to fill
2 $dir Node to fill from 0 for left or 1 for right
mergeWithLeftOrRight($n, $dir)
Merge two adjacent nodes
Parameter Description
1 $n Node to merge into
2 $dir Node to merge is on right if 1 else left
mergeOrFill($tree)
make a node larger than a half node
Parameter Description
1 $tree Tree
deleteLeafKey($tree, $i)
Delete a (key, pair) in a leaf
Parameter Description
1 $tree Tree
2 $i Index to delete at
deleteKey($tree, $i)
Delete a (key, data) pair in a node
Parameter Description
1 $tree Tree
2 $i Index to delete at
flat($tree, @title)
Print the keys in a tree in a flat manner
Parameter Description
1 $tree Tree
2 @title Title
T($tree, $expected)
Write a result to the log file
Parameter Description
1 $tree Tree
2 $expected Expected print
disordered($n, $N)
Disordered but stable insertions
Parameter Description
1 $n Keys per node
2 $N Nodes
disorderedCheck($t, $n, $N)
Check disordered insertions
Parameter Description
1 $t Tree to check
2 $n Keys per node
3 $N Nodes
randomCheck($n, $N, $T)
Random insertions
Parameter Description
1 $n Keys per node
2 $N Log 10 nodes
3 $T Log 10 number of tests
Index
1 delete - Find a key in a tree, delete it, return the new tree
2 deleteKey - Delete a (key, data) pair in a node
3 deleteLeafKey - Delete a (key, pair) in a leaf
4 depth - Return the depth of a node within a tree
5 disordered - Disordered but stable insertions
6 disorderedCheck - Check disordered insertions
7 fillFromLeftOrRight - Fill a node from the specified sibling
8 find - Find a key in a tree returning its associated data or undef if the key does not exist
9 findAndSplit - Find a key in a tree splitting full nodes along the path to the key
10 flat - Print the keys in a tree in a flat manner
11 full - Confirm that a node is full.
12 halfFull - Confirm that a node is half full.
13 height - Return the height of the tree
14 indexInParent - Get the index of a node in its parent
15 insert - Insert a key and data into a tree
16 iterator - Make an iterator for a tree
17 leaf - Confirm that the tree is a leaf.
18 leftMost - Return the left most node below the specified one
19 maximumNumberOfKeys - Maximum number of keys per node.
20 maximumNumberOfNodes - Maximum number of children per parent.
21 mergeOrFill - make a node larger than a half node
22 mergeWithLeftOrRight - Merge two adjacent nodes
23 minimumNumberOfKeys - Minimum number of keys per node.
24 new - Create a new multi-way tree node.
25 print - Print the keys in a tree optionally marking the active key
26 randomCheck - Random insertions
27 reUp - Reconnect the children to their new parent
28 reverseIterator - Create a reverse iterator for a tree
29 rightMost - Return the right most node below the specified one
30 root - Return the root node of a tree.
31 separateData - Return ([lower], center, [upper]) data
32 separateKeys - Return ([lower], center, [upper]) keys.
33 separateNode - Return ([lower], [upper]) children
34 size - Count the number of keys in a tree
35 splitFullNode - Split a full node
36 splitLeafNode - Split a full leaf node in assuming it has a non full parent
37 splitNode - Split a full node in half assuming it has a non full parent
38 splitRootLeafNode - Split a full root that is also a leaf
39 splitRootNode - Split a full root
40 T - Write a result to the log file
41 Tree::Multi::Iterator::next - Find the next key
42 Tree::Multi::ReverseIterator::prev - Find the previous key
Installation
This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:
sudo cpan install Tree::Multi
Author
Copyright
Copyright (c) 2016-2021 Philip R Brenan.
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.