[rustc.git] / vendor / rustc-hash / README.md

# rustc-hash

[![crates.io](https://img.shields.io/crates/v/rustc-hash.svg)](https://crates.io/crates/rustc-hash)
[![Documentation](https://docs.rs/rustc-hash/badge.svg)](https://docs.rs/rustc-hash)

A speedy hash algorithm used within rustc. The hashmap in liballoc by
default uses SipHash which isn't quite as speedy as we want. In the
compiler we're not really worried about DOS attempts, so we use a fast
non-cryptographic hash.

This is the same as the algorithm used by Firefox -- which is a
homespun one not based on any widely-known algorithm -- though
modified to produce 64-bit hash values instead of 32-bit hash
values. It consistently out-performs an FNV-based hash within rustc
itself -- the collision rate is similar or slightly worse than FNV,
but the speed of the hash function itself is much higher because it
works on up to 8 bytes at a time.

## Usage

```rust
use rustc_hash::FxHashMap;

let mut map: FxHashMap<u32, u32> = FxHashMap::default();
map.insert(22, 44);
```

### `no_std`

This crate can be used as a `no_std` crate by disabling the `std`
feature, which is on by default, as follows:

```toml
rustc-hash = { version = "1.0", default-features = false }
```

In this configuration, `FxHasher` is the only export, and the
`FxHashMap`/`FxHashSet` type aliases are omitted.
Commit	Line	Data
94b46f34 XL	1	# rustc-hash
94b46f34 XL	2
f035d41b XL	3	[![crates.io](https://img.shields.io/crates/v/rustc-hash.svg)](https://crates.io/crates/rustc-hash)
	4	[![Documentation](https://docs.rs/rustc-hash/badge.svg)](https://docs.rs/rustc-hash)
	5
94b46f34 XL	6	A speedy hash algorithm used within rustc. The hashmap in liballoc by
	7	default uses SipHash which isn't quite as speedy as we want. In the
	8	compiler we're not really worried about DOS attempts, so we use a fast
	9	non-cryptographic hash.
	10
	11	This is the same as the algorithm used by Firefox -- which is a
	12	homespun one not based on any widely-known algorithm -- though
	13	modified to produce 64-bit hash values instead of 32-bit hash
	14	values. It consistently out-performs an FNV-based hash within rustc
	15	itself -- the collision rate is similar or slightly worse than FNV,
	16	but the speed of the hash function itself is much higher because it
	17	works on up to 8 bytes at a time.
	18
	19	## Usage
	20
f035d41b	21	```rust
94b46f34	22	use rustc_hash::FxHashMap;
f035d41b XL	23
	24	let mut map: FxHashMap<u32, u32> = FxHashMap::default();
	25	map.insert(22, 44);
	26	```
	27
	28	### `no_std`
	29
	30	This crate can be used as a `no_std` crate by disabling the `std`
	31	feature, which is on by default, as follows:
	32
	33	```toml
	34	rustc-hash = { version = "1.0", default-features = false }
94b46f34	35	```
f035d41b XL	36
	37	In this configuration, `FxHasher` is the only export, and the
	38	`FxHashMap`/`FxHashSet` type aliases are omitted.