Document IterBytes, Eq, Cmp, Hash. Close #3449.
This commit is contained in:
parent
7a6df9c90f
commit
37cf649311
|
@ -5,6 +5,14 @@
|
|||
/// Interfaces used for comparison.
|
||||
|
||||
// Awful hack to work around duplicate lang items in core test.
|
||||
|
||||
/**
|
||||
* Trait for values that can be compared for a sort-order.
|
||||
*
|
||||
* Eventually this may be simplified to only require
|
||||
* an `le` method, with the others generated from
|
||||
* default implementations.
|
||||
*/
|
||||
#[cfg(notest)]
|
||||
#[lang="ord"]
|
||||
trait Ord {
|
||||
|
@ -24,6 +32,14 @@ trait Ord {
|
|||
|
||||
#[cfg(notest)]
|
||||
#[lang="eq"]
|
||||
/**
|
||||
* Trait for values that can be compared for equality
|
||||
* and inequality.
|
||||
*
|
||||
* Eventually this may be simplified to only require
|
||||
* an `eq` method, with the other generated from
|
||||
* a default implementation.
|
||||
*/
|
||||
trait Eq {
|
||||
pure fn eq(&&other: self) -> bool;
|
||||
pure fn ne(&&other: self) -> bool;
|
||||
|
|
|
@ -34,8 +34,31 @@ export hash_u16;
|
|||
export hash_u8;
|
||||
export hash_uint;
|
||||
|
||||
/// Types that can meaningfully be hashed should implement this.
|
||||
/**
|
||||
* Types that can meaningfully be hashed should implement this.
|
||||
*
|
||||
* Note that this trait is likely to change somewhat as it is
|
||||
* closely related to `to_bytes::IterBytes` and in almost all
|
||||
* cases presently the two are (and must be) used together.
|
||||
*
|
||||
* In general, most types only need to implement `IterBytes`,
|
||||
* and the implementation of `Hash` below will take care of
|
||||
* the rest. This is the recommended approach, since constructing
|
||||
* good keyed hash functions is quite difficult.
|
||||
*/
|
||||
trait Hash {
|
||||
/**
|
||||
* Compute a "keyed" hash of the value implementing the trait,
|
||||
* taking `k0` and `k1` as "keying" parameters that randomize or
|
||||
* otherwise perturb the hash function in such a way that a
|
||||
* hash table built using such "keyed hash functions" cannot
|
||||
* be made to perform linearly by an attacker controlling the
|
||||
* hashtable's contents.
|
||||
*
|
||||
* In practical terms, we implement this using the SipHash 2-4
|
||||
* function and require most types to only implement the
|
||||
* IterBytes trait, that feeds SipHash.
|
||||
*/
|
||||
pure fn hash_keyed(k0: u64, k1: u64) -> u64;
|
||||
}
|
||||
|
||||
|
|
|
@ -6,7 +6,28 @@ use io::Writer;
|
|||
|
||||
type Cb = fn(buf: &[const u8]) -> bool;
|
||||
|
||||
/**
|
||||
* A trait to implement in order to make a type hashable;
|
||||
* This works in combination with the trait `Hash::Hash`, and
|
||||
* may in the future be merged with that trait or otherwise
|
||||
* modified when default methods and trait inheritence are
|
||||
* completed.
|
||||
*/
|
||||
trait IterBytes {
|
||||
/**
|
||||
* Call the provided callback `f` one or more times with
|
||||
* byte-slices that should be used when computing a hash
|
||||
* value or otherwise "flattening" the structure into
|
||||
* a sequence of bytes. The `lsb0` parameter conveys
|
||||
* whether the caller is asking for little-endian bytes
|
||||
* (`true`) or big-endian (`false`); this should only be
|
||||
* relevant in implementations that represent a single
|
||||
* multi-byte datum such as a 32 bit integer or 64 bit
|
||||
* floating-point value. It can be safely ignored for
|
||||
* larger structured types as they are usually processed
|
||||
* left-to-right in declaration order, regardless of
|
||||
* underlying memory endianness.
|
||||
*/
|
||||
pure fn iter_bytes(lsb0: bool, f: Cb);
|
||||
}
|
||||
|
||||
|
|
Loading…
Reference in New Issue