Skip to content

Commit a9e81ec

Browse files
shepmastershepmaster
committed
Unify the README and crate documentation
1 parent 0d1105f commit a9e81ec

File tree

2 files changed

+69
-137
lines changed

2 files changed

+69
-137
lines changed

‎README.md

+68-72
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,59 @@
1-
# TwoX-Hash
1+
A Rust implementation of the [xxHash] algorithm.
22

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

5-
[![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)
7+
[xxHash]: https://github.com/Cyan4973/xxHash
68

7-
[Documentation](https://docs.rs/twox-hash/)
9+
[crates-badge]: https://img.shields.io/crates/v/twox-hash.svg
10+
[crates-url]: https://crates.io/crates/twox-hash
11+
[docs-badge]: https://img.shields.io/docsrs/twox-hash
12+
[docs-url]: https://docs.rs/twox-hash/
13+
[actions-badge]: https://github.com/shepmaster/twox-hash/actions/workflows/ci.yml/badge.svg?branch=main
14+
[actions-url]: https://github.com/shepmaster/twox-hash/actions/workflows/ci.yml?query=branch%3Amain
815

9-
[XXHash]: https://github.com/Cyan4973/xxHash
16+
# Examples
1017

11-
## Examples
18+
These examples use [`XxHash64`][] but the same ideas can be used for
19+
[`XxHash32`][] or [`XxHash3_64`][].
1220

13-
### With a fixed seed
21+
## Hashing arbitrary data
22+
23+
### When all the data is available at once
1424

1525
```rust
16-
use std::hash::BuildHasherDefault;
17-
use std::collections::HashMap;
1826
use twox_hash::XxHash64;
1927

20-
let mut hash: HashMap<_, _, BuildHasherDefault<XxHash64>> = Default::default();
28+
let seed = 1234;
29+
let hash = XxHash64::oneshot(seed, b"some bytes");
30+
assert_eq!(0xeab5_5659_a496_d78b, hash);
31+
```
32+
33+
### When the data is streaming
34+
35+
```rust
36+
use std::hash::Hasher as _;
37+
use twox_hash::XxHash64;
38+
39+
let seed = 1234;
40+
let mut hasher = XxHash64::with_seed(seed);
41+
hasher.write(b"some");
42+
hasher.write(b" ");
43+
hasher.write(b"bytes");
44+
let hash = hasher.finish();
45+
assert_eq!(0xeab5_5659_a496_d78b, hash);
46+
```
47+
48+
## In a [`HashMap`](std::collections::HashMap)
49+
50+
### With a default seed
51+
52+
```rust
53+
use std::{collections::HashMap, hash::BuildHasherDefault};
54+
use twox_hash::XxHash64;
55+
56+
let mut hash = HashMap::<_, _, BuildHasherDefault<XxHash64>>::default();
2157
hash.insert(42, "the answer");
2258
assert_eq!(hash.get(&42), Some(&"the answer"));
2359
```
@@ -26,73 +62,33 @@ assert_eq!(hash.get(&42), Some(&"the answer"));
2662

2763
```rust
2864
use std::collections::HashMap;
29-
use twox_hash::RandomXxHashBuilder64;
65+
use twox_hash::xxhash64;
66+
67+
let mut hash = HashMap::<_, _, xxhash64::RandomState>::default();
68+
hash.insert(42, "the answer");
69+
assert_eq!(hash.get(&42), Some(&"the answer"));
70+
```
71+
72+
### With a fixed seed
73+
74+
```rust
75+
use std::collections::HashMap;
76+
use twox_hash::xxhash64;
3077

31-
let mut hash: HashMap<_, _, RandomXxHashBuilder64> = Default::default();
78+
let mut hash = HashMap::with_hasher(xxhash64::State::with_seed(0xdead_cafe));
3279
hash.insert(42, "the answer");
3380
assert_eq!(hash.get(&42), Some(&"the answer"));
3481
```
3582

36-
## Benchmarks
37-
38-
### 64-bit
39-
40-
| Bytes | SipHasher (MB/s) | XXHash (MB/s) | Ratio |
41-
|---------|------------------|---------------|-------|
42-
| 1 | 52 | 38 | 73% |
43-
| 4 | 210 | 148 | 70% |
44-
| 16 | 615 | 615 | 100% |
45-
| 32 | 914 | 1391 | 152% |
46-
| 128 | 1347 | 3657 | 271% |
47-
| 256 | 1414 | 5019 | 355% |
48-
| 512 | 1546 | 6168 | 399% |
49-
| 1024 | 1565 | 6206 | 397% |
50-
| 1048576 | 1592 | 7564 | 475% |
51-
52-
| Bytes | [FnvHasher][fnv] (MB/s) | XXHash (MB/s) | Ratio |
53-
|---------|-------------------------|---------------|-------|
54-
| 1 | 1000 | 38 | 4% |
55-
| 4 | 800 | 148 | 19% |
56-
| 16 | 761 | 615 | 81% |
57-
| 32 | 761 | 1391 | 183% |
58-
| 128 | 727 | 3657 | 503% |
59-
| 256 | 759 | 5019 | 661% |
60-
| 512 | 745 | 6168 | 828% |
61-
| 1024 | 741 | 6206 | 838% |
62-
| 1048576 | 745 | 7564 | 1015% |
63-
64-
### 32-bit
65-
66-
| Bytes | SipHasher (MB/s) | XXHash32 (MB/s) | Ratio |
67-
|---------|------------------|-----------------|-------|
68-
| 1 | 52 | 55 | 106% |
69-
| 4 | 210 | 210 | 100% |
70-
| 16 | 615 | 1230 | 200% |
71-
| 32 | 914 | 1882 | 206% |
72-
| 128 | 1347 | 3282 | 244% |
73-
| 256 | 1414 | 3459 | 245% |
74-
| 512 | 1546 | 3792 | 245% |
75-
| 1024 | 1565 | 3938 | 252% |
76-
| 1048576 | 1592 | 4127 | 259% |
77-
78-
| Bytes | [FnvHasher][fnv] (MB/s) | XXHash32 (MB/s) | Ratio |
79-
|---------|-------------------------|-----------------|-------|
80-
| 1 | 1000 | 55 | 6% |
81-
| 4 | 800 | 210 | 26% |
82-
| 16 | 761 | 1230 | 162% |
83-
| 32 | 761 | 1882 | 247% |
84-
| 128 | 727 | 3282 | 451% |
85-
| 256 | 759 | 3459 | 456% |
86-
| 512 | 745 | 3792 | 509% |
87-
| 1024 | 741 | 3938 | 531% |
88-
| 1048576 | 745 | 4127 | 554% |
89-
90-
91-
[fnv]: https://github.com/servo/rust-fnv
92-
93-
## Contributing
94-
95-
1. Fork it ( https://github.com/shepmaster/twox-hash/fork )
83+
# Benchmarks
84+
85+
See benchmarks in the [comparison][] README.
86+
87+
[comparison]: https://github.com/shepmaster/twox-hash/tree/main/comparison
88+
89+
# Contributing
90+
91+
1. Fork it (<https://github.com/shepmaster/twox-hash/fork>)
9692
2. Create your feature branch (`git checkout -b my-new-feature`)
9793
3. Add a failing test.
9894
4. Add code to pass the test.

‎src/lib.rs

+1-65
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,4 @@
1-
//! A Rust implementation of the [XXHash][] algorithm.
2-
//!
3-
//! [XXHash]: https://github.com/Cyan4973/xxHash
4-
//!
5-
//! ## Hashing arbitrary data
6-
//!
7-
//! ### When all the data is available at once
8-
//!
9-
//! ```rust
10-
//! use twox_hash::XxHash64;
11-
//!
12-
//! let seed = 1234;
13-
//! let hash = XxHash64::oneshot(seed, b"some bytes");
14-
//! assert_eq!(0xeab5_5659_a496_d78b, hash);
15-
//! ```
16-
//!
17-
//! ### When the data is streaming
18-
//!
19-
//! ```rust
20-
//! use std::hash::Hasher as _;
21-
//! use twox_hash::XxHash64;
22-
//!
23-
//! let seed = 1234;
24-
//! let mut hasher = XxHash64::with_seed(seed);
25-
//! hasher.write(b"some");
26-
//! hasher.write(b" ");
27-
//! hasher.write(b"bytes");
28-
//! let hash = hasher.finish();
29-
//! assert_eq!(0xeab5_5659_a496_d78b, hash);
30-
//! ```
31-
//!
32-
//! ## In a [`HashMap`](std::collections::HashMap)
33-
//!
34-
//! ### With a default seed
35-
//!
36-
//! ```rust
37-
//! use std::{collections::HashMap, hash::BuildHasherDefault};
38-
//! use twox_hash::XxHash64;
39-
//!
40-
//! let mut hash = HashMap::<_, _, BuildHasherDefault<XxHash64>>::default();
41-
//! hash.insert(42, "the answer");
42-
//! assert_eq!(hash.get(&42), Some(&"the answer"));
43-
//! ```
44-
//!
45-
//! ### With a random seed
46-
//!
47-
//! ```rust
48-
//! use std::collections::HashMap;
49-
//! use twox_hash::xxhash64;
50-
//!
51-
//! let mut hash = HashMap::<_, _, xxhash64::RandomState>::default();
52-
//! hash.insert(42, "the answer");
53-
//! assert_eq!(hash.get(&42), Some(&"the answer"));
54-
//! ```
55-
//!
56-
//! ### With a fixed seed
57-
//!
58-
//! ```rust
59-
//! use std::collections::HashMap;
60-
//! use twox_hash::xxhash64;
61-
//!
62-
//! let mut hash = HashMap::with_hasher(xxhash64::State::with_seed(0xdead_cafe));
63-
//! hash.insert(42, "the answer");
64-
//! assert_eq!(hash.get(&42), Some(&"the answer"));
65-
//! ```
1+
#![doc = include_str!("../README.md")]
662

673
#![deny(rust_2018_idioms)]
684
#![deny(missing_docs)]

0 commit comments

Comments
 (0)