The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Digest-FNV-PurePerl-0.03
River stage zero No dependents
++
/ Digest::FNV::PurePerl

NAME

Digest::FNV::PurePerl - PurePerl implementation of Digest::FNV hashing algorithm.

VERSION

Version 0.01

SYNOPSIS

    use Digest::FNV::PurePerl qw( fnv fnv32 fnv32a fnv64 fnv64a );

    my $fnv32hash = fnv("abc123");
    
    my $fnv32hash = fnv32("abc123"); # This does the same as the previous example
    
    my $hashref = fnv64("abc123");
    $hashref->{bits};     # 32 for 32 bit systems, 64 for 64 bit systems
    $hashref->{upper};    # Upper 32 bits
    $hashref->{lower};    # Lower 32 bits
    $hashref->{bigint}    # use bigint; version of this possibly large number
    $hashref->{longlong}; # 64 bit representation (i.e. (upper << 32) | lower)
                          # This value is useless on 32 bit systems

DESCRIPTION

FNV is a hashing algorithm for short to medium length strings. It is best suited for strings that are typically around 1024 bytes or less (URLs, IP addresses, hostnames, etc). This implementation is based on the code provided by Landon Curt Noll.

There are two slightly different algorithms. One is called FNV-1, and the other is FNV-1a. Both algorithms are provided for each of 32 and 64 bit hash values.

For full information on this algorithm please visit http://isthe.com/chongo/tech/comp/fnv/

The original Digest::FNV was written by Tan D Nguyen <tnguyen@cpan.org>. This version is a drop-in replacement (all existing code should continue to work). However, it is a complete rewrite.

This new version works on both 32 and 64 bit platforms.

CAVEATS

Part of the challenge of supporting this module are the differences between 32-bit and 64-bit architectures.

In practice the values returned by these algorithms are often further processed further algorithms. It is for that reason that the nature of what the fnv64/fnv64a functions return is exposed. When trying to support both 64 and 32 bit architectures it is necessary.

You cannot rely on only $hashref->{bigint} if you plan to perform and further math on that value on 32 bit systems. You also cannot rely on $hashref->{longlong} unless you know the architecture.

This module attempts to provide all of the necessary information to arrive at a true 64-bit value. Often times you're passing values to other software (a database, for example), and that database probably provides 64-bit left shift operations.

EXPORT

fnv fnv32 fnv32a fnv64 fnv64a

FUNCTIONS

fnv fnv32 fnv32a

    use Digest::FNV::PurePerl;

    my $url = "http://www.google.com/";
    print fnv($url),"\n";
        #-> 1088293357

    print fnv32($url),"\n";
        #-> 1088293357

    print fnv32a($url),"\n";
        #-> 912201313

fnv64 fnv64a

    use Digest::FNV::PurePerl;
    use Data::Dumper;

    my $url = "http://www.google.com/";
    my $fnv64hash = fnv64($url);
    print Dumper($fnv64hash);
        #-> $VAR1 = {
        #->          'bigint' => bless( {
        #->                               'value' => [
        #->                                            290527405,
        #->                                            988083964,
        #->                                            9
        #->                                          ],
        #->                               'sign' => '+'
        #->                             }, 'Math::BigInt' ),
        #->          'upper' => 2325532018,
        #->          'lower' => 1179644077,
        #->          'longlong' => '9988083964290527405',
        #->          'bits' => 64
        #->        };

    fnv65a($url);

AUTHOR

Jeffrey Webster, <jeff.webster at zogmedia.com>

BUGS

Please report any bugs or feature requests to bug-digest-fnv-pureperl at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Digest-FNV-PurePerl. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Digest::FNV::PurePerl

You can also look for information at:

ACKNOWLEDGEMENTS

Inspired by Fowler, Noll, and Vo for their nifty little hashing algorithm.

Thanks to Tan Nguyen for handing over control of Digest::FNV

COPYRIGHT & LICENSE

Copyright 2010 Jeffrey Webster.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.