src/libstd/hash.rs

   1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Generic hashing support.
  12 //!
  13 //! This module provides a generic way to compute the hash of a value. The
  14 //! simplest way to make a type hashable is to use `#[deriving(Hash)]`:
  15 //!
  16 //! # Example
  17 //!
  18 //! ```rust
  19 //! use std::hash;
  20 //! use std::hash::Hash;
  21 //!
  22 //! #[deriving(Hash)]
  23 //! struct Person {
  24 //!     id: uint,
  25 //!     name: String,
  26 //!     phone: u64,
  27 //! }
  28 //!
  29 //! let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 };
  30 //! let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 };
  31 //!
  32 //! assert!(hash::hash(&person1) != hash::hash(&person2));
  33 //! ```
  34 //!
  35 //! If you need more control over how a value is hashed, you need to implement
  36 //! the trait `Hash`:
  37 //!
  38 //! ```rust
  39 //! use std::hash;
  40 //! use std::hash::Hash;
  41 //! use std::hash::sip::SipState;
  42 //!
  43 //! struct Person {
  44 //!     id: uint,
  45 //!     name: String,
  46 //!     phone: u64,
  47 //! }
  48 //!
  49 //! impl Hash for Person {
  50 //!     fn hash(&self, state: &mut SipState) {
  51 //!         self.id.hash(state);
  52 //!         self.phone.hash(state);
  53 //!     }
  54 //! }
  55 //!
  56 //! let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 };
  57 //! let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 };
  58 //!
  59 //! assert!(hash::hash(&person1) == hash::hash(&person2));
  60 //! ```
  61
  62 #![experimental]
  63
  64 pub use core::hash::{Hash, Hasher, Writer, hash, sip};
  65
  66 use core::kinds::Sized;
  67 use default::Default;
  68 use rand::Rng;
  69 use rand;
  70
  71 /// `RandomSipHasher` computes the SipHash algorithm from a stream of bytes
  72 /// initialized with random keys.
  73 #[deriving(Clone)]
  74 pub struct RandomSipHasher {
  75     hasher: sip::SipHasher,
  76 }
  77
  78 impl RandomSipHasher {
  79     /// Construct a new `RandomSipHasher` that is initialized with random keys.
  80     #[inline]
  81     pub fn new() -> RandomSipHasher {
  82         let mut r = rand::thread_rng();
  83         let r0 = r.gen();
  84         let r1 = r.gen();
  85         RandomSipHasher {
  86             hasher: sip::SipHasher::new_with_keys(r0, r1),
  87         }
  88     }
  89 }
  90
  91 impl Hasher<sip::SipState> for RandomSipHasher {
  92     #[inline]
  93     fn hash<Sized? T: Hash<sip::SipState>>(&self, value: &T) -> u64 {
  94         self.hasher.hash(value)
  95     }
  96 }
  97
  98 #[stable]
  99 impl Default for RandomSipHasher {
 100     #[stable]
 101     #[inline]
 102     fn default() -> RandomSipHasher {
 103         RandomSipHasher::new()
 104     }
 105 }