119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
A Rust implementation of the [xxHash] algorithm.
|
|
|
|
[![Crates.io][crates-badge]][crates-url]
|
|
[![Documentation][docs-badge]][docs-url]
|
|
[![Build Status][actions-badge]][actions-url]
|
|
|
|
[xxHash]: https://github.com/Cyan4973/xxHash
|
|
|
|
[crates-badge]: https://img.shields.io/crates/v/twox-hash.svg
|
|
[crates-url]: https://crates.io/crates/twox-hash
|
|
[docs-badge]: https://img.shields.io/docsrs/twox-hash
|
|
[docs-url]: https://docs.rs/twox-hash/
|
|
[actions-badge]: https://github.com/shepmaster/twox-hash/actions/workflows/ci.yml/badge.svg?branch=main
|
|
[actions-url]: https://github.com/shepmaster/twox-hash/actions/workflows/ci.yml?query=branch%3Amain
|
|
|
|
# Examples
|
|
|
|
These examples use [`XxHash64`][] but the same ideas can be
|
|
used for [`XxHash32`][], [`XxHash3_64`][], or [`XxHash3_128`][].
|
|
|
|
## Hashing arbitrary data
|
|
|
|
### When all the data is available at once
|
|
|
|
```rust
|
|
use twox_hash::XxHash64;
|
|
|
|
let seed = 1234;
|
|
let hash = XxHash64::oneshot(seed, b"some bytes");
|
|
assert_eq!(0xeab5_5659_a496_d78b, hash);
|
|
```
|
|
|
|
### When the data is streaming
|
|
|
|
```rust
|
|
use std::hash::Hasher as _;
|
|
use twox_hash::XxHash64;
|
|
|
|
let seed = 1234;
|
|
let mut hasher = XxHash64::with_seed(seed);
|
|
hasher.write(b"some");
|
|
hasher.write(b" ");
|
|
hasher.write(b"bytes");
|
|
let hash = hasher.finish();
|
|
assert_eq!(0xeab5_5659_a496_d78b, hash);
|
|
```
|
|
|
|
## In a [`HashMap`][]
|
|
|
|
### With a default seed
|
|
|
|
```rust
|
|
use std::{collections::HashMap, hash::BuildHasherDefault};
|
|
use twox_hash::XxHash64;
|
|
|
|
let mut hash = HashMap::<_, _, BuildHasherDefault<XxHash64>>::default();
|
|
hash.insert(42, "the answer");
|
|
assert_eq!(hash.get(&42), Some(&"the answer"));
|
|
```
|
|
|
|
### With a random seed
|
|
|
|
```rust
|
|
use std::collections::HashMap;
|
|
use twox_hash::xxhash64;
|
|
|
|
let mut hash = HashMap::<_, _, xxhash64::RandomState>::default();
|
|
hash.insert(42, "the answer");
|
|
assert_eq!(hash.get(&42), Some(&"the answer"));
|
|
```
|
|
|
|
### With a fixed seed
|
|
|
|
```rust
|
|
use std::collections::HashMap;
|
|
use twox_hash::xxhash64;
|
|
|
|
let mut hash = HashMap::with_hasher(xxhash64::State::with_seed(0xdead_cafe));
|
|
hash.insert(42, "the answer");
|
|
assert_eq!(hash.get(&42), Some(&"the answer"));
|
|
```
|
|
|
|
# Feature Flags
|
|
|
|
| name | description |
|
|
|-------------|-------------------------------------------------------------------------------------------------------------------------------|
|
|
| xxhash32 | Include the [`XxHash32`][] algorithm |
|
|
| xxhash64 | Include the [`XxHash64`][] algorithm |
|
|
| xxhash3_64 | Include the [`XxHash3_64`][] algorithm |
|
|
| xxhash3_128 | Include the [`XxHash3_128`][] algorithm |
|
|
| random | Create random instances of the hashers |
|
|
| serialize | Serialize and deserialize hasher state with Serde |
|
|
| std | Use the Rust standard library. Enable this if you want SIMD support in [`XxHash3_64`][] or [`XxHash3_128`][] |
|
|
| alloc | Use the Rust allocator library. Enable this if you want to create [`XxHash3_64`][] or [`XxHash3_128`][] with dynamic secrets |
|
|
|
|
# Benchmarks
|
|
|
|
See benchmarks in the [comparison][] README.
|
|
|
|
[comparison]: https://github.com/shepmaster/twox-hash/tree/main/comparison
|
|
|
|
# Contributing
|
|
|
|
1. Fork it (<https://github.com/shepmaster/twox-hash/fork>)
|
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
3. Add a failing test.
|
|
4. Add code to pass the test.
|
|
5. Commit your changes (`git commit -am 'Add some feature'`)
|
|
6. Ensure tests pass.
|
|
7. Push to the branch (`git push origin my-new-feature`)
|
|
8. Create a new Pull Request
|
|
|
|
|
|
[`Hashmap`]: std::collections::HashMap
|
|
[`XxHash32`]: crate::XxHash32
|
|
[`XxHash64`]: crate::XxHash64
|
|
[`XxHash3_64`]: crate::XxHash3_64
|
|
[`XxHash3_128`]: crate::XxHash3_128
|