Also write documentation

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

package Digest::HighwayHash;

use 5.014000;
use strict;
use warnings;
use parent qw/Exporter/;

our @EXPORT_OK = qw/highway_hash64 highway_hash128 highway_hash256/;
our @EXPORT = @EXPORT_OK;

our $VERSION = '0.001001';

use Math::Int64;

require XSLoader;
XSLoader::load('Digest::HighwayHash', $VERSION);

1;
__END__

=encoding utf-8

=head1 NAME

Digest::HighwayHash - XS fast strong keyed hash function

=head1 SYNOPSIS

  use Digest::HighwayHash;
  say highway_hash64 [1, 2, 3, 4], 'hello';
  # 11956820856122239241
  say join ' ', @{highway_hash128([1, 2, 3, 4], 'hello')};
  # 3048112761216189476 13900443277579286659
  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 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>

=head1 AUTHOR

Marius Gavrilescu, E<lt>marius@ieval.roE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2018 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.24.1 or,
at your option, any later version of Perl 5 you may have available.


=cut