-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Principled, portable & extensible hashing of data and types, including an implementation of the FNV-1a and SipHash algorithms.
--   
--   This package is a rewrite of the <tt>hashable</tt> library by Milan
--   Straka and Johan Tibell, having the following goals:
--   
--   <ul>
--   <li>Extensibility; it should be easy to implement a new hashing
--   algorithm on any <tt>Hashable</tt> type; in this package we provide
--   SipHash and FNV-1a.</li>
--   <li>Honest hashing of values, and principled hashing of algebraic data
--   types (see e.g. hashable issues 30)</li>
--   <li>Cross-platform consistent hash values, with a versioning
--   guarantee. Where possible we ensure morally identical data hashes to
--   indentical values regardless of processor word size and
--   endianness.</li>
--   <li>Make implementing identical hash routines in other languages as
--   painless as possible. In addition to SipHash, we provide an
--   implementation of a simple hashing algorithm (FNV-1a) and make an
--   effort to define Hashable instances in a way that is well-documented
--   and sensible, so that e.g. one can easily implement a string hashing
--   routine in JavaScript that will match the way we hash strings
--   here.</li>
--   </ul>
--   
--   <i>Versioning</i>: Except for instances where we specifically note
--   that we make no promise of consistency, changes to hash values (and
--   consequently changes to <tt>StableHashable</tt> values, where
--   applicable) entail a major version number bump.
@package hashabler
@version 1.2

module Data.Hashabler
newtype Hash32 a
Hash32 :: Word32 -> Hash32 a
[hashWord32] :: Hash32 a -> Word32
newtype Hash64 a
Hash64 :: Word64 -> Hash64 a
[hashWord64] :: Hash64 a -> Word64
data Hash128 a
Hash128 :: !Word64 -> !Word64 -> Hash128 a
[hashWord128_0] :: Hash128 a -> !Word64
[hashWord128_1] :: Hash128 a -> !Word64

-- | A 128-bit secret key. This should be generated randomly and must be
--   kept secret.
data SipKey
SipKey :: !Word64 -> !Word64 -> SipKey

-- | An implementation of 64-bit siphash-2-4.
--   
--   This function is fast on 64-bit machines, and provides very good
--   hashing properties and protection against hash flooding attacks.
siphash64 :: Hashable a => SipKey -> a -> Hash64 a

-- | An implementation of 128-bit siphash-2-4.
--   
--   This function is fast on 64-bit machines, and provides very good
--   hashing properties and protection against hash flooding attacks.
siphash128 :: Hashable a => SipKey -> a -> Hash128 a

-- | Hash a value using the standard spec-prescribed 32-bit seed value.
--   
--   <pre>
--   hashFNV32 = <a>Hash32</a> . fnv32 . <a>hash</a> <a>fnvOffsetBasis32</a>
--   </pre>
hashFNV32 :: Hashable a => a -> Hash32 a

-- | Hash a value using the standard spec-prescribed 64-bit seed value.
--   This may be slow on 32-bit machines.
--   
--   <pre>
--   hashFNV64 = <a>Hash64</a> . fnv64 . <a>hash</a> <a>fnvOffsetBasis64</a>
--   </pre>
hashFNV64 :: Hashable a => a -> Hash64 a
fnvPrime32 :: Word32
fnvPrime64 :: Word64
fnvOffsetBasis32 :: FNV32
fnvOffsetBasis64 :: FNV64

-- | A class of types that can be converted into a hash value. We expect
--   all instances to display "good" hashing properties (w<i>r</i>t
--   avalanche, bit independence, etc.) when passed to an ideal hash
--   function.
--   
--   We try to ensure that bytes are extracted from values in a way that is
--   portable across architectures (where possible), and straightforward to
--   replicate on other platforms and in other languages. Portable
--   instances are also instances of <a>StableHashable</a>, and
--   non-portable instances are <b>NOTE</b>-ed in instance docs here as
--   well.
--   
--   See the section <a>"Defining Hashable instances"</a> for details of
--   what we expect from instances.
class Hashable a

-- | Add the bytes from the second argument into the hash, producing a new
--   hash value. This is essentially a left fold of the methods of
--   <a>HashState</a> over individual bytes extracted from <tt>a</tt>.
--   
--   For some instances of <a>HashState</a>, this method might be a
--   complete hashing algorithm, or might comprise the core of a hashing
--   algorithm (perhaps with some final mixing), or might do something
--   completely apart from hashing (e.g. simply cons bytes into a list for
--   debugging).
--   
--   Implementations must ensure that, for the same data:
--   
--   <ul>
--   <li><tt>Word16/32/64</tt> arguments passed into the methods of
--   <a>HashState</a>, and...</li>
--   <li>the choice of <tt>mix</tt> function itself...</li>
--   </ul>
--   
--   ...are consistent across architectures of different word size and
--   endianness. For example do not define an instance which conditionally
--   implements <a>mix64</a> only on 64-bit architectures.
hash :: (Hashable a, HashState h) => h -> a -> h

-- | <pre>
--   mixConstructor n h = h `mix8` (0xFF - n)
--   </pre>
mixConstructor :: (HashState h) => Word8 -> h -> h

-- | Types whose hashes can be compared across platforms. This is somewhat
--   like a limited, but cross-platform <a>Typeable</a>.
--   
--   Instances are expected to be universally-unique, and should be
--   generated randomly. Type parameters can be hashed together using
--   <a>mixType</a>, like:
--   
--   <pre>
--   instance (StableHashable b) =&gt; StableHashable (A b) where
--       typeHash = mixType (TypeHash 530184177609460980)
--   </pre>
--   
--   When <a>Hashable</a> instances change, the <a>TypeHash</a> must be
--   changed to a new random value. This lets us "version" a set of hashes;
--   if we store a <a>TypeHash</a> along with a set of hashes in program
--   <i>A</i>, in program <i>B</i> we can compare the stored value with our
--   own <a>TypeHash</a> and verify that hashes we generate in program
--   <i>B</i> can be meaningfully compared.
--   
--   Note, obviously this doesn't ensure that values were hashed with the
--   same hashing algorithm, and you should come up with your own means to
--   serialize that information if you need to.
class Hashable a => StableHashable a
typeHash :: StableHashable a => TypeHash a

-- | A value that uniquely identifies a <a>StableHashable</a> type. This
--   serves to both version a type with respect to its <a>Hashable</a>
--   instance, and distinguish types from each other (similar to
--   <a>TypeRep</a>) across program runs, platforms and library versions.
newtype TypeHash (a :: k)
TypeHash :: Word64 -> TypeHash
[typeHashWord] :: TypeHash -> Word64

-- | A helper for implementing <a>typeHash</a> by <a>xor</a>-ing type
--   parameters with a new random hash value. E.g.:
--   
--   <pre>
--   instance (StableHashable a, StableHashable b) =&gt; StableHashable (a, b) where
--       typeHash = mixType (mixType (TypeHash 12071780118071628513))
--                                             __ a new random value for (,)
--                              ____ mix in the type hash for <tt>a</tt>
--                      __ mix in the type hash for <tt>b</tt>
--   </pre>
mixType :: StableHashable a => TypeHash t -> TypeHash (t a)
typeHashOf :: StableHashable a => a -> TypeHash a
typeHashOfProxy :: StableHashable a => proxy a -> TypeHash a

-- | A class for defining how a hash function consumes input data. Bytes
--   are fed to these methods in our <a>Hashable</a> instances, which
--   promise to call these methods in a platform-independent way.
--   
--   Instances of <a>HashState</a> only need to define <a>mix8</a>, but may
--   additionally handle <tt>mix</tt>-ing in larger word chunks for
--   performance reasons. For instance a hash function which operates on
--   four bytes at a time might make use of <a>mix32</a>, and perhaps in
--   <a>mix8</a> pad with three additional 0s.
--   
--   Endianness is normalized in <a>Hashable</a> instances, so these mix
--   methods can expect to receive identical words across platforms.
class HashState h where mix16 h = \ wd16 -> let (wd8_0, wd8_1) = bytes16 wd16 in h `mix8` wd8_0 `mix8` wd8_1 mix32 h = \ wd32 -> let (b0, b1, b2, b3) = bytes32 wd32 in h `mix8` b0 `mix8` b1 `mix8` b2 `mix8` b3 mix64 h = \ wd64 -> let (w32_0, w32_1) = words32 wd64 in h `mix32` w32_0 `mix32` w32_1

-- | Mix in one byte.
mix8 :: HashState h => h -> Word8 -> h

-- | Mix in a 2-byte word. Defaults to two <a>mix8</a> on bytes from most
--   to least significant.
mix16 :: HashState h => h -> Word16 -> h

-- | Mix in a 4-byte word. Defaults to four <a>mix8</a> on bytes from most
--   to least significant.
mix32 :: HashState h => h -> Word32 -> h

-- | Mix in a 8-byte word. Defaults to two <a>mix32</a> on 32-byte words
--   from most to least significant.
mix64 :: HashState h => h -> Word64 -> h