    {-# LANGUAGE Rank2Types #-}
    -----------------------------------------------------------------------------
    -- |
    -- Module      :  System.Random.Dice
    -- Copyright   :  Peter Robinson 2014
    -- License     :  LGPL
    --
    -- Maintainer  :  Peter Robinson <peter.robinson@monoid.at>
    -- Stability   :  experimental
    -- Portability :  portable
    --
    -- This module implements an @n@-sided dice and provides sampling from a given
    -- integer range.
    -- The algorithm uses rejection sampling and attempts to keep the total number
    -- of used random bits as close as possible to the information theoretic lower
    -- bound of @ln(n) / ln(2)@ (for a range of size @n@).
    --
    -- The implementation exposes streams of random values as conduits, see
    -- 'diceRolls' and 'randomRs'. We also provide IO wrappers around these
    -- functions, see 'getDiceRolls' and 'getRandomRs'.
    -- The conduit interface allows us to use a specific entropy source, which has
    -- type 'Producer' 'IO' 'Word'.
    --
    -- /Usage:/
    --
    -- If we wanted to use the system-specific entropy source ('systemEntropy') to
    -- produce 10 dice rolls of a 6-sided dice (i.e. range [0,5]), we could write:
    --
    -- > > systemEntropy $$ diceRolls 6 =$= CL.take 10
    -- > [5,1,3,3,0,5,3,2,2,1]
    --
    -- The function 'testPerformance' yields the actual number of consumed random
    -- bits:
    --
    -- > > testPerformance 12 10000
    -- > Generated 10000 random samples in range [0,11]
    -- > Average number of bits used: 3.5904
    -- > Entropy lower bound on the number of required bits: 3.5849625007211565
    -- > Performance ratio: 1.0015167520658164
    --
    -----------------------------------------------------------------------------
    module System.Random.Dice( diceRolls
                             , randomRs
                             , getDiceRolls
                             , getRandomRs
                             -- , testPerformance
                             , systemEntropy
                             )
    where
    import System.Random.Dice.Internal