NAME

Tie::Hash::Sorted - Presents hashes in sorted order

VERSION

Version 0.07 released on 11 Sept 2003

SYNOPSIS

 use Tie::Hash::Sorted;

 my %ages = (
     'John'   => 33,
     'Jacob'  => 29,
     'Jingle' => 15,
     'Heimer' => 48,
     'Smitz'  => 12,
 );

 my $sort_by_numeric_value = sub {
     my $hash = shift;
     [ sort {$hash->{$b} <=> $hash->{$a}} keys %$hash ];
 };

 tie my %sorted_ages, 'Tie::Hash::Sorted',
     'Hash'         => \ %ages,
     'Sort_Routine' => $sort_by_numeric_value;

 for my $name ( keys %sorted_ages ) {
     print "$name is $sorted_ages{$name} years old.\n";
 }

 ### OUTPUT ###
 Heimer is 48 ears old.
 John is 33 ears old.
 Jacob is 29 ears old.
 Jingle is 15 ears old.
 Smitz is 12 ears old.

DESCRIPTION

This module presents hashes in sorted order.

SYNTAX

In order to "tie()" your hash to "Tie::Hash::Sorted":

 tie HASH, 'Tie::Hash::Sorted', [OPTIONS => VALUE];

 HASHREF = tie HASH, 'Tie::Hash::Sorted', [OPTIONS => VALUE];

OPTIONS

Hash

If you do not want to start with an empty hash, you can specify a hash reference

Sort_Routine

If you do not want to use the default sort routine, you can specify a code reference. The sub is very flexible with the following two requirements. It must accept a hash reference as its only argument and it must return an array reference.

The funtion is passed a reference to an unsorted hash and is expected to return the correct order for the hash's keys.

 sub {
     my $unsorted_hash = shift;
     return [ sort keys %$unsorted_hash ];
 }

Optimization

There are four different kinds of optimization.

default: By default, the hash will remain sorted until a re-sort is required. Changes will set a flag to re-sort the hash the next time it is iterated over.
none: This will cause the hash to be re-sorted once every time you iterate over the hash. Use it if the sort routine depends on something that can't be detected in the tied hash. Perhaps you have a hash of hashes (HoH) sorted by the number of second level keys.
Even if you fall into this category, you may be able to use the default optimization. You can use "Resort" after any change you know the tied hash can't detect.
keys: This optimization works the same as the default except it will not set the flag for re-sorting if the only change detected is to an already existing value.
values: This optimization works the same as the default except it will not set the flag for re-sorting if the new value is the same as the old value.

METHODS

Sort_Routine

You can change the sort routine at any time. The change will take affect when you iterate over the hash.

 tie my %sorted_hash, 'Tie::Hash::Sorted', 'Hash' => \%hash;
 my $sort = sub {
     my $hash = shift;
     return [ sort { $a cmp $b || $a <=> $b } keys %$hash ];
 };
 tied( %sorted_hash ) -> Sort_Routine( $sort );

Optimization

You can change the optimization promise at any time.

 tie my %sorted_hash, 'Tie::Hash::Sorted', 'Hash' => \%hash;
 my $sort = sub {
     my $hash = shift;
     return [ sort { $a cmp $b || $a <=> $b } keys %$hash ];
 };
 tied( %sorted_hash ) -> Optimization( 'keys' );

Resort

This method sets the flags for re-sorting the next time you iterate over the hash. It would typically only be used in with Optimization => 'none'. Call this method after changes that you don't expect Tie::Hash::Sorted to be able to notice.

 my @months = qw(January March April June August December);
 my (%data, %order);

 @data{@months} = (33, 29, 15, 48, 23, 87);
 @order{@months} = (1, 3, 4, 6, 8, 12);

 my $sort = sub {
     my $hash = shift;    
     return [ sort {$order{$a} <=> $order{$b}} keys %$hash ];
 };

 tie my %sorted_data, 'Tie::Hash::Sorted', 
     'Hash'         => \%data,
     'Sort_Routine' => $sort,
     'Optimization' => 'none';

 for my $month ( keys %sorted_data ) {
     print "$month had $sorted_data{$month} million sales.\n";
 }
 # More code that iterates over the hash
 # Since there are no changes, you get the benefits of no re-sorting

 @order{@months} = (12, 8, 6, 4, 3, 1);

 # Tie::Hash::Sorted doesn't know that %order just changed so we'll force
 # the issue.
 tied( %sorted_data ) -> Resort;

 for my $month ( keys %sorted_data ) {
     print "$month had $sorted_data{$month} million sales.\n";
 }

Count

Current versions of perl (so far, 5.8.1 and below) implement "scalar keys %tied_hash" poorly. Use the Count method instead to get the number of elements in the hash.

 my %data = ( a=>1, b=>2, c=>3, d=>4 );
 tie my %sorted_data, 'Tie::Hash::Sorted', 'Hash' => \%data;
 print tied( %sorted_data ) -> Count, "\n";

AUTHORS

Joshua Gatcomb, <Limbic_Region_2000@Yahoo.com>

Joshua Jore, <jjore@cpan.org>

Currently maintained by Joshua Gatcomb, <Limbic_Region_2000@Yahoo.com>

ACKNOWLEDGEMENTS

This module was inspired by Tie::SortHash.

Various people from PerlMonks (<http://www.perlmonks.org>) provided invaluable input.

BUGS

None known. Bug reports, fixes, and feedback are desired.

CAVEATS

As of this release, tied hashes always return 0 in scalar context and false in boolean context. You might want to consider using "Count" as an alternative.

COPYRIGHT

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