NAME

Tie::LLHash.pm - ordered hashes

DESCRIPTION

This class implements an ordered hash-like object. It's a cross between a Perl hash and a linked list. Use it whenever you want the speed and structure of a Perl hash, but the orderedness of a list.

Don't use it if you want to be able to address your hash entries by number, like you can in a real list ($list[5]).

See also Tie::IxHash by Gurusamy Sarathy. It's similar (it does ordered hashes), but it has a different internal data structure and a different flavor of usage. It makes your hash behave more like a list than this does.

SYNOPSIS

use Tie::LLHash;

tie (%hash, "Tie::LLHash"); # A new empty hash
tie (%hash2, "Tie::LLHash", "key1"=>$val1, "key2"=>$val2); # A new hash with stuff in it

# Add some entries:
(tied %hash)->first('the' => 'hash');
(tied %hash)->insert('here' => 'now', 'the'); 
(tied %hash)->first('All' => 'the');
(tied %hash)->insert('are' => 'right', 'the');
(tied %hash)->insert('things' => 'in', 'All');
(tied %hash)->last('by' => 'gum');

$value = $hash{'things'}; # Look up a value
$hash{'here'} = 'NOW';    # Set the value of an EXISTING RECORD!


$key = (tied %hash)->key_before('in');  # Returns the previous key
$key = (tied %hash)->key_after('in');   # Returns the next key


# Luxury routines:
$key = (tied %hash)->current_key;
$val = (tied %hash)->current_value;
(tied %hash)->next;
(tied %hash)->prev;
(tied %hash)->reset;

ITERATION TECHNIQUES

Here is a smattering of ways you can iterate over the hash. I include it here simply because iteration is probably important to people who need ordered data.

while (($key, $val) = each %hash) {
   print ("$key: $val\n");
}

foreach $key (keys %hash) {
   print ("$key: $hash{$key}\n");
}

my $obj = tied %hash;  # For the following examples

$key = $obj->reset;
while (exists $hash{$key}) {
   print ("$key: $hash{$key}\n");
   $key = $obj->next;
}

$obj->reset;
while (exists $hash{$obj->current_key}) {
   $key = $obj->current_key;
   print ("$key: $hash{$key}\n");
   $obj->next;
}

WARNINGS

• Don't add new elements to the hash by simple assignment, a la <$hash{$new_key} = $value>, because LLHash won't know where in the order to put the new element.

TO DO

I need to write documentation for all the functions here.

I might make $hash{$new_key} = $new_value a synonym for 
(tied %hash)->last($new_key, $new_value) when $new_key doesn't exist 
already.  This behavior would be optional.  In some cases it could be
dangerous, for example if you thought an element was already in the 
hash but it wasn't, or vice versa.

I could speed up the keys() routine in a scalar context if I kept
track of how many entries were in the hash.

I may also want to add a method for... um, I forgot.

AUTHOR

Ken Williams <ken@forum.swarthmore.edu>

Copyright (c) 1998 Swarthmore College. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.