Parano...AVLTree(3pm)

📦
version 2.10 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💅 Parano...AVLTree(3pm) — ok bestie, let's talk AVL trees 🎀

it's your girl, coming at you from the User Contributed Perl Documentation corner of the 3pm manual section, here to explain Paranoid::Data::AVLTree like we're texting at 2am. grab a snack 🍓

✨ NAME ✨

Paranoid::Data::AVLTree — the AVL-Balanced Tree Class, no cap 🌳👑

🌈 VERSION 🌈

this is the one you're reading:

$Id: lib/Paranoid/Data/AVLTree.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $

version 2.10, and yes it's giving very "timestamps that are oddly specific." we stan 🙈

🦋 SYNOPSIS 🦋

here's the whole vibe, verbatim, no edits from me 💖

# Preferred use
tie %tree, 'Paranoid::Data::AVLTree';

# Or, purely as an object
$tree   = new Paranoid::Data::AVLTree;
$count  = $tree->count;
$height = $tree->height;
@keys   = $tree->nodeKeys;
$rv     = $tree->nodeExists($key):
$val    = $tree->fetchVal($key);
$rv     = $tree->addPair($key, $value);
$rv     = $tree->delNode($key);
$rv     = $tree->purgeNodes;

$tree->dumpKeys;
$tree->profile(1);
%stats = $tree->stats;

$rv = $tree->save2File($filename);
$rv = $tree->loadFromFile($filename);

(yes, that nodeExists line ends in a colon in the original. i am not touching it. character for character, that's the rule. 💀)

🫶 DESCRIPTION 🫶

so, this class gives you a whole AVL-balanced tree implementation, bestie. it can run as an independent object or as a tied hash — pick your fighter, both slay ✨

heads up: future versions will include methods to allow for simple spooling to and from disk. that's a future thing, okay? don't come for me.

NOTE: ok this part is important, so listen. these objects do support assignment of any arbitrary value to each node. BUT — spooling to and from files only supports the use of scalar values. any object/code references, globs, or nested data structures will not survive save/load functionality. gone. poof. 😭 so keep your scalars close and your refs closer.

⭐ SUBROUTINES/METHODS ⭐

🎀 new

$tree   = new Paranoid::Data::AVLTree;

this creates a new tree object. fresh tree, fresh start, main character energy 🌸

🎀 profile

$rv     = $obj->profile(1);
$rv     = $obj->profile(0);

this method enables or disables performance profiling — lil basic statistics on the internal operations, if you're nosy like me 👀. and whenever profiling is enabled the counters get reset. clean slate, periodt.

🎀 stats

%stats = $obj->stats;

this method returns a hash of various performance counters. right now the contents of that hash are exactly these:

  • insertions — number of node insertions
  • deletions — number of node deletions
  • rebalances — number of rebalances triggered
  • rotations — number of branch rotations triggered

🎀 count

$count  = $tree->count;

returns a count of all the nodes in the tree. every single one. icon behavior 👑

🎀 height

$height = $tree->height;

returns the height of the tree. how tall is she? 💅

🎀 nodeKeys

@keys   = $tree->nodeKeys;

returns a list of all keys for all nodes in the tree. the whole guest list 🎟️

🎀 nodeExists

$rv     = $tree->nodeExists($key):

returns a boolean value indicating whether a node exists wtih a matching key. (also: that colon at the end is straight from the original. we don't fix, we preserve. 🫡)

🎀 fetchVal

$val    = $tree->fetchVal($key);

returns the associated value for the passed key. and just like hashes, it'll hand you back undef for nonexistant keys. no drama, just undef 💀

🎀 addPair

$rv     = $tree->addPair($key, $value);

adds the requested key/value pair, or updates an existing node with the same key. it returns a boolean false if the key is an invalid value. so like, bad key = no thank you ✋

🎀 delNode

$rv     = $tree->delNode($key);

deletes the specified node if it exists. returns boolean false should no matching node exist. so if the node wasn't even there, you get a false and honestly? mood. 🙈

🎀 purgeNodes

$rv     = $tree->purgeNodes;

this purges all nodes from the tree. total wipe. 🧹✨

🎀 dumpKeys

$tree->dumpKeys;

this method exists purely for diagnostic purposes. it dumps a formatted tree structure to STDERR showing all keys in the tree, along with the relative branch height and balance of every node, along with what side of the tree each node is attached. it's giving "x-ray vision" 🔍

🎀 save2File

$rv = $tree->save2File($filename);

saves the current contents of the AVL Tree to the specified file. and here's the smart part: it attempts to save the nodes in an order which minimizes the number of rotations when read, to maximize loading performance. it's planning ahead, bestie 🧠✨

🎀 loadFromFile

$rv = $tree->loadFromFile($filename);

loads the contents of the named file into memory. it does only the most rudimentary validation of records upon loading 📝

also, note that the current contents of the AVL Tree get purged prior to loading, so that the contents after loading reflect precisely what is in the file. that said—

⚠️ if there is any kind of file corruption in the middle of the file, it can mean the AVL Tree is only partially loaded after a failed attempt. so, y'know, corruption = half a tree. we don't love that. 😭

🎀 TIE METHODS

these methods aren't intended for direct use, okay? they exist to support tied hashes. here's the full roster 🫶

  • CLEAR
  • DELETE
  • EXISTS
  • FETCH
  • FIRSTKEY
  • NEXTKEY
  • SCALAR
  • STORE
  • TIEHASH
  • UNTIE

🌸 DEPENDENCIES 🌸

the squad it rolls with:

  • Carp
  • Paranoid
  • Paranoid::Debug
  • Paranoid::Data::AVLTree::AVLNode

💀 BUGS AND LIMITATIONS 💀

...so this section is literally empty in the original. nothing listed. nothing claimed. just vibes and silence 🤐✨

💖 AUTHOR 💖

Arthur Corliss (corliss@digitalmages.com)

this software is free software. similar to Perl, you can redistribute it and/or modify it under the terms of either:

subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark.

(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2020, Paranoid Inc. (www.paranoid.com)

ok that's the whole page, and lemme just say — the footer on this one is perl v5.38.2, dated 2024-03-07, and it's signing off as Parano...AVLTree(3pm). that's the tea, bestie. go balance something 💅🌟

📦 where this page comes from