Skip to content

Commit

Permalink
Unify the README and crate documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@shepmaster
shepmaster committed Oct 17, 2024
1 parent 0d1105f commit a9e81ec
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 137 deletions.
140 changes: 68 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,59 @@
# TwoX-Hash
A Rust implementation of the [xxHash] algorithm.

A Rust implementation of the [XXHash] algorithm.
[![Crates.io][crates-badge]][crates-url]
[![Documentation][docs-badge]][docs-url]
[![Build Status][actions-badge]][actions-url]

[![Build Status](https://travis-ci.org/shepmaster/twox-hash.svg)](https://travis-ci.org/shepmaster/twox-hash) [![Current Version](https://img.shields.io/crates/v/twox-hash.svg)](https://crates.io/crates/twox-hash)
[xxHash]: https://github.com/Cyan4973/xxHash

[Documentation](https://docs.rs/twox-hash/)
[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

[XXHash]: https://github.com/Cyan4973/xxHash
# Examples

## Examples
These examples use [`XxHash64`][] but the same ideas can be used for
[`XxHash32`][] or [`XxHash3_64`][].

### With a fixed seed
## Hashing arbitrary data

### When all the data is available at once

```rust
use std::hash::BuildHasherDefault;
use std::collections::HashMap;
use twox_hash::XxHash64;

let mut hash: HashMap<_, _, BuildHasherDefault<XxHash64>> = Default::default();
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`](std::collections::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"));
```
Expand All @@ -26,73 +62,33 @@ assert_eq!(hash.get(&42), Some(&"the answer"));

```rust
use std::collections::HashMap;
use twox_hash::RandomXxHashBuilder64;
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<_, _, RandomXxHashBuilder64> = Default::default();
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"));
```

## Benchmarks

### 64-bit

| Bytes | SipHasher (MB/s) | XXHash (MB/s) | Ratio |
|---------|------------------|---------------|-------|
| 1 | 52 | 38 | 73% |
| 4 | 210 | 148 | 70% |
| 16 | 615 | 615 | 100% |
| 32 | 914 | 1391 | 152% |
| 128 | 1347 | 3657 | 271% |
| 256 | 1414 | 5019 | 355% |
| 512 | 1546 | 6168 | 399% |
| 1024 | 1565 | 6206 | 397% |
| 1048576 | 1592 | 7564 | 475% |

| Bytes | [FnvHasher][fnv] (MB/s) | XXHash (MB/s) | Ratio |
|---------|-------------------------|---------------|-------|
| 1 | 1000 | 38 | 4% |
| 4 | 800 | 148 | 19% |
| 16 | 761 | 615 | 81% |
| 32 | 761 | 1391 | 183% |
| 128 | 727 | 3657 | 503% |
| 256 | 759 | 5019 | 661% |
| 512 | 745 | 6168 | 828% |
| 1024 | 741 | 6206 | 838% |
| 1048576 | 745 | 7564 | 1015% |

### 32-bit

| Bytes | SipHasher (MB/s) | XXHash32 (MB/s) | Ratio |
|---------|------------------|-----------------|-------|
| 1 | 52 | 55 | 106% |
| 4 | 210 | 210 | 100% |
| 16 | 615 | 1230 | 200% |
| 32 | 914 | 1882 | 206% |
| 128 | 1347 | 3282 | 244% |
| 256 | 1414 | 3459 | 245% |
| 512 | 1546 | 3792 | 245% |
| 1024 | 1565 | 3938 | 252% |
| 1048576 | 1592 | 4127 | 259% |

| Bytes | [FnvHasher][fnv] (MB/s) | XXHash32 (MB/s) | Ratio |
|---------|-------------------------|-----------------|-------|
| 1 | 1000 | 55 | 6% |
| 4 | 800 | 210 | 26% |
| 16 | 761 | 1230 | 162% |
| 32 | 761 | 1882 | 247% |
| 128 | 727 | 3282 | 451% |
| 256 | 759 | 3459 | 456% |
| 512 | 745 | 3792 | 509% |
| 1024 | 741 | 3938 | 531% |
| 1048576 | 745 | 4127 | 554% |


[fnv]: https://github.com/servo/rust-fnv

## Contributing

1. Fork it ( https://github.com/shepmaster/twox-hash/fork )
# 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.
Expand Down
66 changes: 1 addition & 65 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,4 @@
//! A Rust implementation of the [XXHash][] algorithm.
//!
//! [XXHash]: https://github.com/Cyan4973/xxHash
//!
//! ## 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`](std::collections::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"));
//! ```
#![doc = include_str!("../README.md")]

#![deny(rust_2018_idioms)]
#![deny(missing_docs)]
Expand Down

0 comments on commit a9e81ec

Please sign in to comment.