=encoding utf-8

=head1 NAME

Digest::xxHash - xxHash Implementation For Perl

=head1 SYNOPSIS

    # Functional interface (single-shot)
    use Digest::xxHash qw[
        xxhash32 xxhash32_hex
        xxhash64 xxhash64_hex
        xxh3_64  xxh3_64_hex
        xxh3_128 xxh3_128_hex
        xxh3_generate_secret
    ];

    my $hash   = xxhash32( $data, $seed );
    my $hex    = xxhash32_hex( $data, $seed );
    my $hash64 = xxhash64( $data, $seed );
    my $hex64  = xxhash64_hex( $data, $seed );

    my $xxh3_64  = xxh3_64( $data, $seed );
    my $xxh3_hex = xxh3_64_hex( $data, $seed );

    # 128-bit returns 32-char hex string
    my $xxh3_128_hex = xxh3_128_hex( $data, $seed );

    # Digest-style OO interface (streaming)
    my $ctx = Digest::xxHash->new( type => 'xxh3_64', seed => 0 );
    $ctx->add('one');
    $ctx->add('two');
    say $ctx->hexdigest;

    my $clone = $ctx->clone;
    $ctx->reset;

=head1 DESCRIPTION

xxHash is an extremely fast non-cryptographic hash algorithm that works at RAM speed limits. This module is a wrapper
around the official C xxHash library providing both a functional interface for single-shot hashing and a Digest-style
object-oriented interface for streaming/incremental hashing.

The following hash families are supported:

=over 4

=item B<XXH32> - Classic 32-bit hash (9.7 GB/s)

=item B<XXH64> - Classic 64-bit hash (19.4 GB/s)

=item B<XXH3-64> - Modern 64-bit hash, faster than XXH64 on all platforms

=item B<XXH3-128> - Modern 128-bit hash with extra strength

=back

=head1 FUNCTIONAL INTERFACE

These functions are easy to use but are not suitable for incremental hashing.

=head2 C<xxhash32( $data, $seed )>

Calculates a 32-bit hash and returns it as an unsigned 32-bit integer.

=head2 C<xxhash32_hex( $data, $seed )>

Calculates a 32-bit hash and returns it as an 8-character lowercase hex string.

=head2 C<xxhash64( $data, $seed )>

Calculates a 64-bit hash and returns it as an unsigned 64-bit integer.

=head2 C<xxhash64_hex( $data, $seed )>

Calculates a 64-bit hash and returns it as a 16-character lowercase hex string.

=head2 C<xxh3_64( $data, $seed )>

Calculates a 64-bit XXH3 hash and returns it as an unsigned 64-bit integer. This is faster than C<xxhash64(...)> on all
platforms.

=head2 C<xxh3_64_hex( $data, $seed )>

Calculates a 64-bit XXH3 hash and returns it as a 16-character lowercase hex string.

=head2 C<xxh3_128_hex( $data, $seed )>

Calculates a 128-bit XXH3 hash and returns it as a 32-character lowercase hex string.

=head2 C<xxh3_generate_secret( $seed )>

Generates a 192-byte high-entropy secret from a seed. The returned bytes can be used as the C<secret> parameter in
C<new(...)>. This is equivalent to C<XXH3_generateSecret_fromSeed(...)> in the C API.

=head1 OBJECT-ORIENTED INTERFACE

The OO interface follows the same conventions as L<Digest::MD5> and L<Digest::SHA>, making it easy to swap hash
algorithms with minimal code changes.

=head2 C<new( ... )>

    my $ctx = Digest::xxHash->new( type => 'xxh3_64', seed => 42 );

Creates a new hash context. Valid parameters:

=over 4

=item B<type> (required) - One of: C<xxh32>, C<xxh64>, C<xxh3_64>, C<xxh3_128>

=item B<seed> (optional) - A numeric seed, defaults to C<0>

=item B<secret> (optional) - Raw bytes to use as a custom secret (XXH3 types only)

=back

When C<secret> is provided for XXH3 types, it overrides C<seed>. Generate a proper secret with
C<xxh3_generate_secret(...)>.

=head2 C<add()>

    $ctx->add($data);
    $ctx->add($chunk1, $chunk2, $chunk3);

Feeds data into the hash context. Can be called multiple times. Returns the context object for method chaining.

=head2 C<digest()>

    my $bytes = $ctx->digest;

Returns the raw hash value. For 128-bit hashes, returns 16 bytes (packed two little-endian uint64s).

=head2 C<hexdigest()>

    my $hex = $ctx->hexdigest;

Returns the hash value as a lowercase hex string. Length depends on the hash type: 8 chars for XXH32, 16 for
XXH3-64/XXH64, 32 for XXH3-128.

=head2 C<b64digest()>

    my $b64 = $ctx->b64digest;

Returns the hash value as base64-encoded data. Requires L<MIME::Base64>.

=head2 C<clone()>

    my $copy = $ctx->clone;

Creates an independent copy of the hash context. Modifying C<$copy> does not affect C<$ctx>.

=head2 C<reset()>

    $ctx->reset;

Resets the context to its initial state (same seed/secret as when created). The context can then be reused for a new
hash computation.

=head1 SPEED

Thanks to xxHash, this module is significantly faster than general-purpose hashes found on CPAN. Benchmarked across 5
platforms with Perl v5.42 against L<Crypt::xxHash> and standard digest modules. Run C<eg/benchmark.pl> to reproduce.
L<Crypt::xxHash> refuses to build on macOS, so... no benchmarks there to compare.

=head2 XXH3 functional interface (MB/s, higher is better)

                         Linux x64   Win x64   macOS Intel   macOS ARM    Linux ARM
    -------------------------------------------------------------------------------
    xxh3_64                 16,438    16,550         9,968      32,279       19,854
    xxh3_128                16,346    16,442        14,204      32,989       19,747
    Crypt::xxHash xxh64      8,832     8,909            --          --           --

=head2 Streaming interface (1MB fed in 64KB chunks)

                         Linux x64   Win x64   macOS Intel   macOS ARM    Linux ARM
    -------------------------------------------------------------------------------
    xxh3_64                 13,746    13,203         6,681      13,044       16,719
    xxh3_128                13,684    13,054         6,847      13,543       16,614
    xxh64                   10,745    10,459         5,481      11,640       17,978
    xxh32                    5,731     5,670         3,530       3,079       10,139
    Crypt::xxHash stream    11,923    11,776            --          --           --
    MD5                        610       615           511         488          538

=head2 Hex output (functional, 1KB input)

                         Linux x64   Win x64   macOS Intel   macOS ARM    Linux ARM
    -------------------------------------------------------------------------------
    xxh3_64_hex              5,721     5,544         2,217       8,513        5,861
    xxh3_128_hex             5,577     5,113         2,150       7,559        5,548
    Crypt::xxh3_64_hex       4,765     2,002            --          --           --
    Crypt::xxh3_128_hex      3,912     1,544            --          --           --
    Digest::MD5::md5_hex       525       494           345         423          467

=head1 AUTHOR

Sanko Robinson L<https://github.com/sanko>

xxHash by Yann Collet L<https://xxhash.com/>

=head1 COPYRIGHT

Copyright (C) 2013 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

xxHash is covered by the BSD license.

=cut
