Also write documentation

[digest-highwayhash.git] / lib / Digest / HighwayHash.pm

diff --git a/lib/Digest/HighwayHash.pm b/lib/Digest/HighwayHash.pm
index 108021b4fc71dd320a1191725316a9a5414cb67f..201886db98cb7672140ee16fc6b662283cc56a16 100644 (file)
--- a/lib/Digest/HighwayHash.pm
+++ b/lib/Digest/HighwayHash.pm
@@ -8,7 +8,7 @@ use parent qw/Exporter/;
 our @EXPORT_OK = qw/highway_hash64 highway_hash128 highway_hash256/;
 our @EXPORT = @EXPORT_OK;
 
-our $VERSION = '0.000_001';
+our $VERSION = '0.001001';
 
 use Math::Int64;
 
@@ -22,7 +22,7 @@ __END__
 
 =head1 NAME
 
-Digest::HighwayHash - fast strong hash function
+Digest::HighwayHash - XS fast strong keyed hash function
 
 =head1 SYNOPSIS
 
@@ -34,11 +34,72 @@ Digest::HighwayHash - fast strong hash function
   say join ' ', @{highway_hash256([1, 2, 3, 4], 'hello')};
   # 8099666330974151427 17027479935588128037 4015249936799013189 10027181291351549853
 
+  my $state = Digest::HighwayHash->new([1, 2, 3, 4]);
+  $state->append('he');
+  $state->append('llo');
+  say join ' ', @{$state->finish128};
+  # 3048112761216189476 13900443277579286659
+
 =head1 DESCRIPTION
 
-HighwayHash is a fast and strong hash function, documented at
+HighwayHash is a fast and strong keyed hash function, documented at
 L<https://github.com/google/highwayhash>.
 
+This module has a procedural interface (used to hash an entire
+message) and an OO interface (used to hash a message bit by bit). The
+procedural interface is made of three functions, all exported by
+default:
+
+=over
+
+=item B<highway_hash64> I<\@key>, I<$input>
+
+Compute the 64-bit HighwayHash of I<$input>, using I<\@key> as a key.
+The key must be a 4-element arrayref, with each element either a
+number or (on Perls without 64-bit numbers) a L<Math::Int64> object. The result is a single number or (on Perls without 64-bit numbers) a L<Math::Int64> object.
+
+=item B<highway_hash128> I<\@key>, I<$input>
+
+Compute the 128-bit HighwayHash of I<$input>, using I<\@key> as a key.
+The key must be a 4-element arrayref, with each element either a
+number or (on Perls without 64-bit numbers) a L<Math::Int64> object. The result is an array of exactly two numbers or (on Perls without 64-bit numbers) L<Math::Int64> objects.
+
+=item B<highway_hash256> I<\@key>, I<$input>
+
+Compute the 256-bit HighwayHash of I<$input>, using I<\@key> as a key.
+The key must be a 4-element arrayref, with each element either a
+number or (on Perls without 64-bit numbers) a L<Math::Int64> object. The result is an array of exactly four numbers or (on Perls without 64-bit numbers) L<Math::Int64> objects.
+
+
+=back
+
+The OO interface has these methods:
+
+=over
+
+=item Digest::HighwayHash->B<new>(I<\@key>)
+
+Initialize a new C<Digest::HighwayHash> state with a given key. The
+B<append> method will be called with this state and parts of the
+message, and then one of the B<finish*> methods will be called to
+compute the result.
+
+=item $state->B<append>(I<$input>)
+
+Append I<$input> to the message to be hashed by $state.
+
+=item $state->B<finish64>
+
+=item $state->B<finish128>
+
+=item $state->B<finish256>
+
+Compute and return the 64-bit, 128-bit, or respectively 256-bit
+HighwayHash of this state. The return values are the same as in the
+procedural interface.
+
+=back
+
 =head1 SEE ALSO
 
 L<https://github.com/google/highwayhash>