Joshua Gatcomb > Tie-Hash-Sorted-0.10 > Tie::Hash::Sorted

Download:
Tie-Hash-Sorted-0.10.tar.gz

Dependencies

Annotate this POD (2)

Related Modules

Tie::IxHash
Data::Dumper
Tie::SortHash
Tie::Hash
HTML::Template
Sort::Fields
MIME::Lite
XML::Twig
Class::DBI
Scalar::Util
more...
By perlmonks.org

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.10   Source  

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];

or

 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.

SEE ALSO ^

perl(1), perltie

README for a comparison to Tie::IxHash and Tie::SortHash

syntax highlighting: