Digest-FNV-XS/XS.pm

=head1 NAME

Digest::FNV::XS - Fowler/Noll/Vo (FNV) hashes

=head1 SYNOPSIS

 use Digest::FNV::XS; # nothing exported by default

=head1 DESCRIPTION

This module is more or less a faster version of L<Digest::FNV>,
that additionally supports binary data, incremental hashing,
more FNV variants and xorfolding. The API isn't compatible (and
neither are the generated hash values. The hash values computed by
this module match the official FNV hash values as documented on
L<http://www.isthe.com/chongo/tech/comp/fnv/>).

=over 4

=cut

package Digest::FNV::XS;

BEGIN {
   $VERSION = 0.01;
   @ISA = qw(Exporter);
   @EXPORT_OK = qw(fnv0_32 fnv0_64 fnv1_32 fnv1a_32 fnv1_64 fnv1a_64);

   require Exporter;
   Exporter::export_ok_tags(keys %EXPORT_TAGS);

   require XSLoader;
   XSLoader::load Digest::FNV::XS, $VERSION;
}

=item $hash = Digest::FNV::XS::fnv1a_32 $data[, $init]

=item $hash = Digest::FNV::XS::fnv1a_64 $data[, $init]

Compute the 32 or 64 bit FNV-1a hash of the given string.

C<$init> is the optional initialisation value, allowing incremental
hashing. If missing or C<undef> then the appropriate FNV constant is used.

The 64 bit variant is only available when perl was compiled with 64 bit support.

The FNV-1a algorithm is the preferred variant, as it has slightly higher
quality and speed then FNV-1.

=item $hash = Digest::FNV::XS::fnv1_32 $data[, $init]

=item $hash = Digest::FNV::XS::fnv1_64 $data[, $init]

Compute the 32 or 64 bit FNV-1 hash of the given string.

C<$init> is the optional initialisation value, allowing incremental
hashing. If missing or C<undef> then the appropriate FNV constant is used.

The 64 bit variant is only available when perl was compiled with 64 bit support.

The FNV-1a variant is preferable if you can choose.

=item $hash = Digest::FNV::XS::fnv0_32 $data[, $init]

=item $hash = Digest::FNV::XS::fnv0_64 $data[, $init]

The obsolete FNV-0 algorithm. Same as calling the FNV1 variant with C<$init = 0>.

C<$init> is the optional initialisation value, allowing incremental
hashing. If missing or C<undef> then the appropriate FNV constant is used.

The 64 bit variant is only available when perl was compiled with 64 bit support.

=item $hash = Digest::FNV::XS::xorfold_32 $hash, $bits

=item $hash = Digest::FNV::XS::xorfold_64 $hash, $bits

XOR-folds the 32 (64) bit FNV hash to C<$bits> bits, which can be any
value between 1 and 32 (64) inclusive.

XOR-folding is a good method to reduce the FNV hash to a power of two.

=item $hash = Digest::FNV::XS::reduce_32 $hash, $range

=item $hash = Digest::FNV::XS::reduce_64 $hash, $range

When you want to reduce a FNV hash value to a rnage that is not a power of
two, you can simply calculate C<$hash % $range>, which creates slightly
biased distribution which nevertheless is completely adequate for many
applications, especially for small C<$range>.

When a bias is not acceptable, then these two functions can be used to
reduce a 32 (64) but FNV hash to an integer in the range 0 .. C<$range>,
with reduced or nonexistent bias.

The disadvantage of these functions is that they are slower (and in fact,
have unbounded runtime), although in practise the speed difference in a
Perl program should be negligible.

=back

=head2 INCREMENTAL HASHING

You can hash data incrementally by feeding the previous hahs value as
C<$init> argument for the next call, for example:

   $hash = fnv1a_32 $data1;
   $hash = fnv1a_32 $data2, $hash; # and so on

Or in a loop (relying on the fact that C<$hash> is C<undef> initially):

   my $hash;
   $hash = fnv1a_32 $_, $hash
      for ...;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/Digest-FNV-XS.html

=cut

1

Revision:	1.1
Committed:	Thu Oct 29 10:56:00 2015 UTC (8 years, 6 months ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	Digest::FNV::XS - Fowler/Noll/Vo (FNV) hashes
4
5	=head1 SYNOPSIS
6
7	use Digest::FNV::XS; # nothing exported by default
8
9	=head1 DESCRIPTION
10
11	This module is more or less a faster version of L<Digest::FNV>,
12	that additionally supports binary data, incremental hashing,
13	more FNV variants and xorfolding. The API isn't compatible (and
14	neither are the generated hash values. The hash values computed by
15	this module match the official FNV hash values as documented on
16	L<http://www.isthe.com/chongo/tech/comp/fnv/>).
17
18	=over 4
19
20	=cut
21
22	package Digest::FNV::XS;
23
24	BEGIN {
25	$VERSION = 0.01;
26	@ISA = qw(Exporter);
27	@EXPORT_OK = qw(fnv0_32 fnv0_64 fnv1_32 fnv1a_32 fnv1_64 fnv1a_64);
28
29	require Exporter;
30	Exporter::export_ok_tags(keys %EXPORT_TAGS);
31
32	require XSLoader;
33	XSLoader::load Digest::FNV::XS, $VERSION;
34	}
35
36	=item $hash = Digest::FNV::XS::fnv1a_32 $data[, $init]
37
38	=item $hash = Digest::FNV::XS::fnv1a_64 $data[, $init]
39
40	Compute the 32 or 64 bit FNV-1a hash of the given string.
41
42	C<$init> is the optional initialisation value, allowing incremental
43	hashing. If missing or C<undef> then the appropriate FNV constant is used.
44
45	The 64 bit variant is only available when perl was compiled with 64 bit support.
46
47	The FNV-1a algorithm is the preferred variant, as it has slightly higher
48	quality and speed then FNV-1.
49
50	=item $hash = Digest::FNV::XS::fnv1_32 $data[, $init]
51
52	=item $hash = Digest::FNV::XS::fnv1_64 $data[, $init]
53
54	Compute the 32 or 64 bit FNV-1 hash of the given string.
55
56	C<$init> is the optional initialisation value, allowing incremental
57	hashing. If missing or C<undef> then the appropriate FNV constant is used.
58
59	The 64 bit variant is only available when perl was compiled with 64 bit support.
60
61	The FNV-1a variant is preferable if you can choose.
62
63	=item $hash = Digest::FNV::XS::fnv0_32 $data[, $init]
64
65	=item $hash = Digest::FNV::XS::fnv0_64 $data[, $init]
66
67	The obsolete FNV-0 algorithm. Same as calling the FNV1 variant with C<$init = 0>.
68
69	C<$init> is the optional initialisation value, allowing incremental
70	hashing. If missing or C<undef> then the appropriate FNV constant is used.
71
72	The 64 bit variant is only available when perl was compiled with 64 bit support.
73
74	=item $hash = Digest::FNV::XS::xorfold_32 $hash, $bits
75
76	=item $hash = Digest::FNV::XS::xorfold_64 $hash, $bits
77
78	XOR-folds the 32 (64) bit FNV hash to C<$bits> bits, which can be any
79	value between 1 and 32 (64) inclusive.
80
81	XOR-folding is a good method to reduce the FNV hash to a power of two.
82
83	=item $hash = Digest::FNV::XS::reduce_32 $hash, $range
84
85	=item $hash = Digest::FNV::XS::reduce_64 $hash, $range
86
87	When you want to reduce a FNV hash value to a rnage that is not a power of
88	two, you can simply calculate C<$hash % $range>, which creates slightly
89	biased distribution which nevertheless is completely adequate for many
90	applications, especially for small C<$range>.
91
92	When a bias is not acceptable, then these two functions can be used to
93	reduce a 32 (64) but FNV hash to an integer in the range 0 .. C<$range>,
94	with reduced or nonexistent bias.
95
96	The disadvantage of these functions is that they are slower (and in fact,
97	have unbounded runtime), although in practise the speed difference in a
98	Perl program should be negligible.
99
100	=back
101
102	=head2 INCREMENTAL HASHING
103
104	You can hash data incrementally by feeding the previous hahs value as
105	C<$init> argument for the next call, for example:
106
107	$hash = fnv1a_32 $data1;
108	$hash = fnv1a_32 $data2, $hash; # and so on
109
110	Or in a loop (relying on the fact that C<$hash> is C<undef> initially):
111
112	my $hash;
113	$hash = fnv1a_32 $_, $hash
114	for ...;
115
116	=head1 AUTHOR
117
118	Marc Lehmann <schmorp@schmorp.de>
119	http://software.schmorp.de/pkg/Digest-FNV-XS.html
120
121	=cut
122
123	1
124