diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-06-07 05:48:48 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-06-07 05:48:48 +0000 |
commit | ef24de24a82fe681581cc130f342363c47c0969a (patch) | |
tree | 0d494f7e1a38b95c92426f58fe6eaa877303a86c /vendor/derivative/doc/Hash.md | |
parent | Releasing progress-linux version 1.74.1+dfsg1-1~progress7.99u1. (diff) | |
download | rustc-ef24de24a82fe681581cc130f342363c47c0969a.tar.xz rustc-ef24de24a82fe681581cc130f342363c47c0969a.zip |
Merging upstream version 1.75.0+dfsg1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'vendor/derivative/doc/Hash.md')
-rw-r--r-- | vendor/derivative/doc/Hash.md | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/vendor/derivative/doc/Hash.md b/vendor/derivative/doc/Hash.md new file mode 100644 index 000000000..71c6f0867 --- /dev/null +++ b/vendor/derivative/doc/Hash.md @@ -0,0 +1,83 @@ +# Custom attributes +The `Hash` trait supports the following attributes: + +* **Container attributes** + * [`Hash(bound="<where-clause or empty>")`](#custom-bound) +* **Field attributes** + * [`Hash(bound="<where-clause or empty>")`](#custom-bound) + * [`Hash(hash_with="<path>")`](#hash-with) + * [`Hash="ignore"`](#ignoring-a-field) + +# Ignoring a field + +You can use *derivative* to ignore fields from a `Hash` implementation: + +```rust +# extern crate derivative; +# use derivative::Derivative; +#[derive(Derivative)] +#[derivative(Hash)] +struct Foo { + foo: u8, + #[derivative(Hash="ignore")] + bar: i32, +} + +#[derive(Hash)] +struct Bar { + foo: u8, +} + +# fn hash<T: std::hash::Hash>(t: &T) -> u64 { +# use std::hash::Hasher; +# let mut s = std::collections::hash_map::DefaultHasher::new(); +# t.hash(&mut s); +# s.finish() +# } +# +assert_eq!(hash(&Foo { foo: 42, bar: -1337 }), hash(&Bar { foo: 42 })); +``` + +# Hash with + +You can pass a field to a hash function: + +```rust +# extern crate derivative; +# use derivative::Derivative; +# mod path { +# pub struct SomeTypeThatMightNotBeHash; +# pub mod to { +# pub fn my_hash_fn<H>(_: &super::SomeTypeThatMightNotBeHash, state: &mut H) where H: std::hash::Hasher { unimplemented!() } +# } +# } +# use path::SomeTypeThatMightNotBeHash; +#[derive(Derivative)] +#[derivative(Hash)] +struct Foo { + foo: u32, + #[derivative(Hash(hash_with="path::to::my_hash_fn"))] + bar: SomeTypeThatMightNotBeHash, +} +``` + +The field `bar` will be hashed with `path::to::my_hash_fn(&bar, &mut state)` +where `state` is the current [`Hasher`]. + +The function must the following prototype: + +```rust,ignore +fn my_hash_fn<H>(&T, state: &mut H) where H: Hasher; +``` + +# Limitations + +On structure, `derivative(Hash)` will produce the same hash as `derive(Hash)`. +On unions however, it will produces the same hashes *only for unitary +variants*! + +# Custom bound +As most other traits, `Hash` supports a custom bound on container and fields. +See [`Debug`'s documentation](Debug.md#custom-bound) for more information. + +[`Hasher`]: https://doc.rust-lang.org/std/hash/trait.Hasher.html |