mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-01 15:01:51 +00:00
Rollup merge of #96828 - scottmcm:clarify-hasher-write, r=Amanieu
Further elaborate the lack of guarantees from `Hasher` I realized that I got too excited in #94598 by adding new methods, and forgot to do the documentation to really answer the core question in #94026. This PR just has that doc update. r? `@Amanieu`
This commit is contained in:
commit
2c4d7a5463
@ -268,10 +268,29 @@ pub use macros::Hash;
|
||||
/// instance (with [`write`] and [`write_u8`] etc.). Most of the time, `Hasher`
|
||||
/// instances are used in conjunction with the [`Hash`] trait.
|
||||
///
|
||||
/// This trait makes no assumptions about how the various `write_*` methods are
|
||||
/// This trait provides no guarantees about how the various `write_*` methods are
|
||||
/// defined and implementations of [`Hash`] should not assume that they work one
|
||||
/// way or another. You cannot assume, for example, that a [`write_u32`] call is
|
||||
/// equivalent to four calls of [`write_u8`].
|
||||
/// equivalent to four calls of [`write_u8`]. Nor can you assume that adjacent
|
||||
/// `write` calls are merged, so it's possible, for example, that
|
||||
/// ```
|
||||
/// # fn foo(hasher: &mut impl std::hash::Hasher) {
|
||||
/// hasher.write(&[1, 2]);
|
||||
/// hasher.write(&[3, 4, 5, 6]);
|
||||
/// # }
|
||||
/// ```
|
||||
/// and
|
||||
/// ```
|
||||
/// # fn foo(hasher: &mut impl std::hash::Hasher) {
|
||||
/// hasher.write(&[1, 2, 3, 4]);
|
||||
/// hasher.write(&[5, 6]);
|
||||
/// # }
|
||||
/// ```
|
||||
/// end up producing different hashes.
|
||||
///
|
||||
/// Thus to produce the same hash value, [`Hash`] implementations must ensure
|
||||
/// for equivalent items that exactly the same sequence of calls is made -- the
|
||||
/// same methods with the same parameters in the same order.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
Loading…
Reference in New Issue
Block a user