NAME
Digest::xxHash - xxHash Implementation For Perl
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;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:
- XXH32 - Classic 32-bit hash (9.7 GB/s)
- XXH64 - Classic 64-bit hash (19.4 GB/s)
- XXH3-64 - Modern 64-bit hash, faster than XXH64 on all platforms
- XXH3-128 - Modern 128-bit hash with extra strength
FUNCTIONAL INTERFACE
These functions are easy to use but are not suitable for incremental hashing.
xxhash32( $data, $seed )
Calculates a 32-bit hash and returns it as an unsigned 32-bit integer.
xxhash32_hex( $data, $seed )
Calculates a 32-bit hash and returns it as an 8-character lowercase hex string.
xxhash64( $data, $seed )
Calculates a 64-bit hash and returns it as an unsigned 64-bit integer.
xxhash64_hex( $data, $seed )
Calculates a 64-bit hash and returns it as a 16-character lowercase hex string.
xxh3_64( $data, $seed )
Calculates a 64-bit XXH3 hash and returns it as an unsigned 64-bit integer. This is faster than xxhash64(...) on all platforms.
xxh3_64_hex( $data, $seed )
Calculates a 64-bit XXH3 hash and returns it as a 16-character lowercase hex string.
xxh3_128_hex( $data, $seed )
Calculates a 128-bit XXH3 hash and returns it as a 32-character lowercase hex string.
xxh3_generate_secret( $seed )
Generates a 192-byte high-entropy secret from a seed. The returned bytes can be used as the secret parameter in new(...). This is equivalent to XXH3_generateSecret_fromSeed(...) in the C API.
OBJECT-ORIENTED INTERFACE
The OO interface follows the same conventions as Digest::MD5 and Digest::SHA, making it easy to swap hash algorithms with minimal code changes.
new( ... )
my $ctx = Digest::xxHash->new( type => 'xxh3_64', seed => 42 );Creates a new hash context. Valid parameters:
- type (required) - One of:
xxh32,xxh64,xxh3_64,xxh3_128 - seed (optional) - A numeric seed, defaults to
0 - secret (optional) - Raw bytes to use as a custom secret (XXH3 types only)
When secret is provided for XXH3 types, it overrides seed. Generate a proper secret with xxh3_generate_secret(...).
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.
digest()
my $bytes = $ctx->digest;Returns the raw hash value. For 128-bit hashes, returns 16 bytes (packed two little-endian uint64s).
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.
b64digest()
my $b64 = $ctx->b64digest;Returns the hash value as base64-encoded data. Requires MIME::Base64.
clone()
my $copy = $ctx->clone;Creates an independent copy of the hash context. Modifying $copy does not affect $ctx.
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.
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 Crypt::xxHash and standard digest modules. Run eg/benchmark.pl to reproduce. Crypt::xxHash refuses to build on macOS, so... no benchmarks there to compare.
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 -- -- --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 538Hex 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 467AUTHOR
Sanko Robinson https://github.com/sanko
xxHash by Yann Collet https://xxhash.com/
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.