CityHash-sys
Rust bindings to Google CityHash's C++ API.
CityHash-sys do not load the standard library (a.k.a no_std
).
Introduction
CityHash provides hash functions for strings. Functions mix the input bits thoroughly but are not suitable for cryptography. CityHash-sys is tested on little-endian but should work on big-endian architecture.
Hash functions without x86_64 CRC-32 intrinsic
Rust bindings provides a safe interface to all Google's CityHash hash functions:
Retrieves a 32-bit hash:
; // Call `uint32 CityHash32(const char *, size_t);`
Retrieves a 64-bit hash:
; // Call `uint64 CityHash64(const char *, size_t);`
; // Call ``uint64 CityHash64WithSeed(const char *, size_t, uint64);`
; // Call `uint64 CityHash64WithSeeds(const char *, size_t, uint64, uint64);`
Retrieves 128-bit hash:
Note: Depending on your compiler and hardware, it's likely faster than CityHash64() on sufficiently long strings. It's slower than necessary on shorter strings.
Hash functions with x86_64 CRC-32 intrinsic
Some functions are available only if the target is x86_64
and support at least sse4.2
target feature because of the usage of CRC-32 intrinsic _mm_crc32_u64
. If we want to enable those functions use -C target-feature=+sse4.2
or above (avx
or avx2
).
Note that depending of the length of the buffer you want to hash, it can be faster to use the non-intrinsic version.
If the buffer to hash is less than 900 bytes, CityHashCrc128WithSeed
and CityHashCrc128
will respectivelly internally call CityHash128WithSeed
and CityHash128
, in this case, it is better to call directly CityHash128WithSeed
or CityHash128
.
Retrieves 128-bit hash with CRC-32 intrinsic:
; // Call `uint128 CityHashCrc128(const char *, size_t);`
; // Call `uint128 CityHashCrc128WithSeed(const char *, size_t, uint128);`
Retrievse 256-bit hash with CRC-32 intrinsic:
; // Call `CityHashCrc256(const char *, size_t, uint64 *);`
Rust convenient traits
CityHash-sys provides convenient traits to hash.
CityHash
trait provides hash functions that do not used the CRC-32 intrinsics.
use CityHash;
// Hash the slice with CityHash64
let hash_slice: u64 = .city_hash_64;
assert_eq!;
// Hash the str with CityHash64
let hash_str: u64 = "hash me!".city_hash_64;
assert_eq!;
CityHashCrc
trait provides hash implementation for [u8]
and str
types with x86_64
CRC-32 intrinsic. (Only available with target-feature=+sse4.2
)
use CityHashCrc;
// Hash the slice with CityHashCrc128
let hash_crc_slice: u128 = .city_hash_crc_128;
// Hash the str with CityHashCrc128
let hash_crc_slice: u128 = "hash me!".city_hash_crc_128;
Performance
On 64-bits hardware, CityHash is suitable for short string hashing, e.g., most hash table keys, especially city_hash_64
that is faster than city_hash_128
.
On 32-bits hardware, CityHash is the nearest competitor of Murmur3 on x86.
For more information
See the Google Cityhash README