DESCRIPTION

  A virtual class used to build a virtual forest of Trees (yuk yuk).

SYNOPSIS or See the Trees for the Forest

  $myTree = new Tree::MyTree;           # Create a new tree of type MyTree
  $myTree->insert('key', 'value');      # Add a new key/value pair.
                                                                                                                                                # or change an existing one.
  $myTree->delete('key');                       # Delete a key/value pair
  $value = $myTree->find('key');        # Find the value of a key
  $myTree->exists('key');                       # Does the given key exist?
  $myTree->clear;                                               # Delete the entire tree.
  @sortedKeys   = $myTree->keys([lowerKey],[upperKey]);
  @sortedValues = $myTree->values([lowerKey], [upperKey]);

  # Works kinda like each().
  ($key, $value)        = $myTree->next([key]);
  ($key, $value)        = $myTree->prev([key]);
  $myTree->reset;                       # Resets the default key used
                                                                                        # for next() and prev()
                                                                
  ($key, $value)  = $myTree->least;
  ($key, $value)        = $myTree->greatest;

  $myTree->debug(level);                # Sets the debugging level
  # UNIMPLEMENTED
  $myTree->sortby(&cmp);                # Sets how the tree is sorted
  # UNIMPLEMENTED

EFFICIENCIES or Be a Tree Hugger.

  Tree methods vs. their hash equivelents.
  (Orders are average and for a balanced tree.  Orders given in []'s 
  are for Splay trees using a commonly accessed key, or in {}'s are for 
  BTrees with a sufficiently high B.  These are only shown if different.)

  $myTree       = new MyTree;   # O(1)
  (%myHash = ();)                               # O(1)
        
  $myTree->insert(key, value);# O(logn)
  ($myHash{key} = value;)       # O(1)
        
  $myTree->delete(key);         # O(logn) [ O(1) ]
  (delete $myHash{key};)        # O(1)
        
  $myTree->find(key);           # O(logn) [ O(1) ]
  ($myHash{key};)                               # O(1)
        
  $myTree->exists(key);         # O(logn) [ O(1) ]
  (exists $myHash{key};)        # O(1)
        
  $myTree->clear;                       # O(n)          As a result of the internal chaining,
                                                                                #       each node in the tree must be unlinked
                                                                                #       manually to prevent memory leaks.
  (%myhash = undef;)            # O(1)
        
  $myTree->keys([lowerKey], [upperKey]); # O(n)
  (sort keys %myHash;)          # O(nlogn)
        
  $myTree->values([lowerKey], [upperKey]); # O(n)
  (foreach $key (sort keys %myHash) { # O(nlogn)
     push @values, $myHash{$key};
   }  )
        
  $myTree->next([key]);         # O(1), O(logn) if key is 
                                                                                                        # given
  (something... (sort keys %myHash);) # O(nlogn)
        
  $myTree->prev([key]);         # same as next
        
  $myTree->reset;                               # reset the state of the tree
  (can't do it)
  
  $myTree->least;                                               # O(logn)
  ((sort keys %myHash)[0];)     # O(nlogn)
  $myTree->greatest;                            # same as least
  (pop(sort keys %myHash);)     # same as least
  
  So as you can see, if you ever find yourself sorting a hash, use a tree.