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


-- | Efficient rounded log2 algorithms on integral and rational types.
--   
--   This provides a user-facing API for the GHC primitive 'integerLog2#',
--   in the form of functions computing the floor, ceiling, or other
--   rounded form of the base-2 logarithm of <a>Integral</a> or
--   <a>Rational</a> types.
@package numeric-logarithms
@version 0.1.0.0


-- | Rounded base-2 logarithms of <a>Integral</a> and <a>Real</a> types.
module Numeric.Logarithms

-- | Returns the floor of the base-2 logarithm of a <a>Real</a> argument.
log2Floor :: (HasCallStack, Real a) => a -> Int

-- | Returns the ceiling of the base-2 logarithm of a <a>Real</a> argument.
log2Ceiling :: (HasCallStack, Real a) => a -> Int

-- | Returns an approximate base-2 logarithm of the argument.
--   
--   The returned <tt>Int</tt> is one of the two nearest integers to the
--   exact result, and the returned <tt>Ordering</tt> tells whether the
--   exact result is greater than, equal to, or less than the <tt>Int</tt>.
--   <a>LT</a> means the exact result is less than the rounded result.
--   
--   This effectively gives results like "between 7 and 8" and leaves it up
--   to the caller to decide how (or whether) to round the result. See also
--   <a>log2With</a> for a version that will always round, but leaves the
--   particular rounding strategy up to the caller.
log2Approx :: (HasCallStack, Real a) => a -> (Int, Ordering)

-- | Returns the base-2 logarithm with custom rounding.
--   
--   The first parameter is a rounding adjustment function: given the
--   approximate result and an <a>Ordering</a> indicating its relation to
--   the exact result, return the rounded result.
--   
--   This could be useful if you want something other than floor or ceil,
--   e.g. round-towards-0, round-towards-even, etc.
log2With :: (HasCallStack, Real a) => (Int -> Ordering -> Int) -> a -> Int

-- | Returns the floor of the base-2 logarithm of an <a>Integral</a>
--   argument.
ilog2Floor :: (HasCallStack, Integral a) => a -> Int

-- | Returns the ceiling of the base-2 logarithm of an <a>Integral</a>
--   argument.
ilog2Ceiling :: (HasCallStack, Integral a) => a -> Int

-- | Returns the approximate base-2 logarithm of an <a>Integral</a>
--   argument.
ilog2Approx :: (HasCallStack, Integral a) => a -> (Int, Ordering)

-- | Returns the base-2 logarithm of an <a>Integral</a> with custom
--   rounding.
ilog2With :: (HasCallStack, Integral a) => (Int -> Ordering -> Int) -> a -> Int