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


-- | Integer library based on GMP
--   
--   Integer library based on GMP
@package integer-gmp
@version 1.0.0.1

module GHC.Integer.Logarithms

-- | Compute base-2 log of <a>Word#</a>
--   
--   This is internally implemented as count-leading-zeros machine
--   instruction.
wordLog2# :: Word# -> Int#

-- | Calculate the integer base 2 logarithm of an <a>Integer</a>. The
--   calculation is more efficient than for the general case, on platforms
--   with 32- or 64-bit words much more efficient.
--   
--   The argument must be strictly positive, that condition is <i>not</i>
--   checked.
integerLog2# :: Integer -> Int#

-- | Calculate the integer logarithm for an arbitrary base.
--   
--   The base must be greater than <tt>1</tt>, the second argument, the
--   number whose logarithm is sought, shall be positive, otherwise the
--   result is meaningless.
--   
--   The following property holds
--   
--   <pre>
--   base ^ <a>integerLogBase#</a> base m &lt;= m &lt; base ^(<a>integerLogBase#</a> base m + 1)
--   </pre>
--   
--   for <tt>base &gt; 1</tt> and <tt>m &gt; 0</tt>.
--   
--   Note: Internally uses <a>integerLog2#</a> for base 2
integerLogBase# :: Integer -> Integer -> Int#


-- | The <a>Integer</a> type.
--   
--   This module exposes the <i>portable</i> <a>Integer</a> API. See
--   <a>GHC.Integer.GMP.Internals</a> for the <tt>integer-gmp</tt>-specific
--   internal representation of <a>Integer</a> as well as optimized
--   GMP-specific operations.
module GHC.Integer

-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
--   <a>S#</a>
--   
--   Useful properties resulting from the invariants:
--   
--   <ul>
--   <li><pre>abs (<a>S#</a> _) &lt;= abs (<a>Jp#</a> _)</pre></li>
--   <li><pre>abs (<a>S#</a> _) &lt; abs (<a>Jn#</a> _)</pre></li>
--   </ul>
data Integer

-- | Construct <a>Integer</a> value from list of <a>Int</a>s.
--   
--   This function is used by GHC for constructing <a>Integer</a> literals.
mkInteger :: Bool -> [Int] -> Integer

-- | Should rather be called <tt>intToInteger</tt>
smallInteger :: Int# -> Integer
wordToInteger :: Word# -> Integer
word64ToInteger :: Word64# -> Integer
int64ToInteger :: Int64# -> Integer
integerToWord :: Integer -> Word#

-- | Truncates <a>Integer</a> to least-significant <a>Int#</a>
integerToInt :: Integer -> Int#
integerToWord64 :: Integer -> Word64#
integerToInt64 :: Integer -> Int64#
encodeFloatInteger :: Integer -> Int# -> Float#
floatFromInteger :: Integer -> Float#
encodeDoubleInteger :: Integer -> Int# -> Double#
decodeDoubleInteger :: Double# -> (# Integer, Int# #)
doubleFromInteger :: Integer -> Double#

-- | Add two <a>Integer</a>s
plusInteger :: Integer -> Integer -> Integer

-- | Subtract two <a>Integer</a>s from each other.
minusInteger :: Integer -> Integer -> Integer

-- | Multiply two <a>Integer</a>s
timesInteger :: Integer -> Integer -> Integer

-- | Negate <a>Integer</a>
negateInteger :: Integer -> Integer

-- | Compute absolute value of an <a>Integer</a>
absInteger :: Integer -> Integer

-- | Return <tt>-1</tt>, <tt>0</tt>, and <tt>1</tt> depending on whether
--   argument is negative, zero, or positive, respectively
signumInteger :: Integer -> Integer

-- | Simultaneous <a>divInteger</a> and <a>modInteger</a>.
--   
--   Divisor must be non-zero otherwise the GHC runtime will terminate with
--   a division-by-zero fault.
divModInteger :: Integer -> Integer -> (# Integer, Integer #)
divInteger :: Integer -> Integer -> Integer
modInteger :: Integer -> Integer -> Integer

-- | Simultaneous <a>quotInteger</a> and <a>remInteger</a>.
--   
--   Divisor must be non-zero otherwise the GHC runtime will terminate with
--   a division-by-zero fault.
quotRemInteger :: Integer -> Integer -> (# Integer, Integer #)
quotInteger :: Integer -> Integer -> Integer
remInteger :: Integer -> Integer -> Integer
eqInteger :: Integer -> Integer -> Bool

-- | Not-equal predicate.
neqInteger :: Integer -> Integer -> Bool
leInteger :: Integer -> Integer -> Bool
gtInteger :: Integer -> Integer -> Bool
ltInteger :: Integer -> Integer -> Bool
geInteger :: Integer -> Integer -> Bool
compareInteger :: Integer -> Integer -> Ordering
eqInteger# :: Integer -> Integer -> Int#
neqInteger# :: Integer -> Integer -> Int#
leInteger# :: Integer -> Integer -> Int#
gtInteger# :: Integer -> Integer -> Int#
ltInteger# :: Integer -> Integer -> Int#
geInteger# :: Integer -> Integer -> Int#

-- | Bitwise AND operation
andInteger :: Integer -> Integer -> Integer

-- | Bitwise OR operation
orInteger :: Integer -> Integer -> Integer

-- | Bitwise XOR operation
xorInteger :: Integer -> Integer -> Integer

-- | Bitwise <tt>NOT</tt> operation
complementInteger :: Integer -> Integer

-- | Shift-left operation
--   
--   Even though the shift-amount is expressed as <a>Int#</a>, the result
--   is undefined for negative shift-amounts.
shiftLInteger :: Integer -> Int# -> Integer

-- | Arithmetic shift-right operation
--   
--   Even though the shift-amount is expressed as <a>Int#</a>, the result
--   is undefined for negative shift-amounts.
shiftRInteger :: Integer -> Int# -> Integer

-- | Test if <i>n</i>-th bit is set.
testBitInteger :: Integer -> Int# -> Bool
hashInteger :: Integer -> Int#


-- | This modules provides access to the <a>Integer</a> constructors and
--   exposes some highly optimized GMP-operations.
--   
--   Note that since <tt>integer-gmp</tt> does not depend on <tt>base</tt>,
--   error reporting via exceptions, <tt>error</tt>, or <tt>undefined</tt>
--   is not available. Instead, the low-level functions will crash the
--   runtime if called with invalid arguments.
--   
--   See also <a>GHC Commentary: Libraries/Integer</a>.
module GHC.Integer.GMP.Internals

-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
--   <a>S#</a>
--   
--   Useful properties resulting from the invariants:
--   
--   <ul>
--   <li><pre>abs (<a>S#</a> _) &lt;= abs (<a>Jp#</a> _)</pre></li>
--   <li><pre>abs (<a>S#</a> _) &lt; abs (<a>Jn#</a> _)</pre></li>
--   </ul>
data Integer

-- | iff value in <tt>[minBound::<a>Int</a>, maxBound::<a>Int</a>]</tt>
--   range
S# :: !Int# -> Integer

-- | iff value in <tt>]maxBound::<a>Int</a>, +inf[</tt> range
Jp# :: {-# UNPACK #-} !BigNat -> Integer

-- | iff value in <tt>]-inf, minBound::<a>Int</a>[</tt> range
Jn# :: {-# UNPACK #-} !BigNat -> Integer

-- | Test whether all internal invariants are satisfied by <a>Integer</a>
--   value
--   
--   Returns <tt>1#</tt> if valid, <tt>0#</tt> otherwise.
--   
--   This operation is mostly useful for test-suites and/or code which
--   constructs <a>Integer</a> values directly.
isValidInteger# :: Integer -> Int#

-- | <a>Integer</a> for which only <i>n</i>-th bit is set. Undefined
--   behaviour for negative <i>n</i> values.
bitInteger :: Int# -> Integer

-- | Count number of set bits. For negative arguments returns negative
--   population count of negated argument.
popCountInteger :: Integer -> Int#

-- | Compute greatest common divisor.
gcdInteger :: Integer -> Integer -> Integer

-- | Extended euclidean algorithm.
--   
--   For <tt><i>a</i></tt> and <tt><i>b</i></tt>, compute their greatest
--   common divisor <tt><i>g</i></tt> and the coefficient <tt><i>s</i></tt>
--   satisfying <tt><i>a</i><i>s</i> + <i>b</i><i>t</i> = <i>g</i></tt>.
gcdExtInteger :: Integer -> Integer -> (# Integer, Integer #)

-- | Compute least common multiple.
lcmInteger :: Integer -> Integer -> Integer

-- | Square <a>Integer</a>
sqrInteger :: Integer -> Integer

-- | "<tt><a>powModInteger</a> <i>b</i> <i>e</i> <i>m</i></tt>" computes
--   base <tt><i>b</i></tt> raised to exponent <tt><i>e</i></tt> modulo
--   <tt>abs(<i>m</i>)</tt>.
--   
--   Negative exponents are supported if an inverse modulo
--   <tt><i>m</i></tt> exists.
--   
--   <b>Warning</b>: It's advised to avoid calling this primitive with
--   negative exponents unless it is guaranteed the inverse exists, as
--   failure to do so will likely cause program abortion due to a
--   divide-by-zero fault. See also <a>recipModInteger</a>.
--   
--   Future versions of <tt>integer_gmp</tt> may not support negative
--   <tt><i>e</i></tt> values anymore.
powModInteger :: Integer -> Integer -> Integer -> Integer

-- | "<tt><a>recipModInteger</a> <i>x</i> <i>m</i></tt>" computes the
--   inverse of <tt><i>x</i></tt> modulo <tt><i>m</i></tt>. If the inverse
--   exists, the return value <tt><i>y</i></tt> will satisfy <tt>0 &lt;
--   <i>y</i> &lt; abs(<i>m</i>)</tt>, otherwise the result is <tt>0</tt>.
recipModInteger :: Integer -> Integer -> Integer
wordToNegInteger :: Word# -> Integer
bigNatToInteger :: BigNat -> Integer
bigNatToNegInteger :: BigNat -> Integer

-- | Type representing <i>raw</i> arbitrary-precision Naturals
--   
--   This is common type used by <tt>Natural</tt> and <a>Integer</a>. As
--   this type consists of a single constructor wrapping a
--   <a>ByteArray#</a> it can be unpacked.
--   
--   Essential invariants:
--   
--   <ul>
--   <li><a>ByteArray#</a> size is an exact multiple of <a>Word#</a>
--   size</li>
--   <li>limbs are stored in least-significant-limb-first order,</li>
--   <li>the most-significant limb must be non-zero, except for</li>
--   <li><tt>0</tt> which is represented as a 1-limb.</li>
--   </ul>
data BigNat
BN# :: ByteArray# -> BigNat

-- | Type representing a GMP Limb
type GmpLimb = Word
type GmpLimb# = Word#

-- | Count of <a>GmpLimb</a>s, must be positive (unless specified
--   otherwise).
type GmpSize = Int
type GmpSize# = Int#

-- | Test whether all internal invariants are satisfied by <a>BigNat</a>
--   value
--   
--   Returns <tt>1#</tt> if valid, <tt>0#</tt> otherwise.
--   
--   This operation is mostly useful for test-suites and/or code which
--   constructs <a>Integer</a> values directly.
isValidBigNat# :: BigNat -> Int#

-- | Return number of limbs contained in <a>BigNat</a>.
sizeofBigNat# :: BigNat -> GmpSize#

-- | CAF representing the value <tt>0 :: BigNat</tt>
zeroBigNat :: BigNat

-- | CAF representing the value <tt>1 :: BigNat</tt>
oneBigNat :: BigNat

-- | Special 0-sized bigNat returned in case of arithmetic underflow
--   
--   This is currently only returned by the following operations:
--   
--   <ul>
--   <li><a>minusBigNat</a></li>
--   <li><a>minusBigNatWord</a></li>
--   </ul>
--   
--   Other operations such as <a>quotBigNat</a> may return
--   <a>nullBigNat</a> as well as a dummy/place-holder value instead of
--   <tt>undefined</tt> since we can't throw exceptions. But that behaviour
--   should not be relied upon.
--   
--   NB: <tt>isValidBigNat# nullBigNat</tt> is false
nullBigNat :: BigNat

-- | Construct <a>BigNat</a> from existing <a>ByteArray#</a> containing
--   <i>n</i> <a>GmpLimb</a>s in least-significant-first order.
--   
--   If possible <a>ByteArray#</a>, will be used directly (i.e. shared
--   <i>without</i> cloning the <a>ByteArray#</a> into a newly allocated
--   one)
--   
--   Note: size parameter (times <tt>sizeof(GmpLimb)</tt>) must be less or
--   equal to its <a>sizeofByteArray#</a>.
byteArrayToBigNat# :: ByteArray# -> GmpSize# -> BigNat

-- | Construct 1-limb <a>BigNat</a> from <a>Word#</a>
wordToBigNat :: Word# -> BigNat

-- | Construct BigNat from 2 limbs. The first argument is the
--   most-significant limb.
wordToBigNat2 :: Word# -> Word# -> BigNat

-- | Equivalent to <tt><a>word2Int#</a> . <a>bigNatToWord</a></tt>
bigNatToInt :: BigNat -> Int#

-- | Same as <tt><a>indexBigNat#</a> bn 0#</tt>
bigNatToWord :: BigNat -> Word#

-- | Extract <i>n</i>-th (0-based) limb in <a>BigNat</a>. <i>n</i> must be
--   less than size as reported by <a>sizeofBigNat#</a>.
indexBigNat# :: BigNat -> GmpSize# -> GmpLimb#
plusBigNat :: BigNat -> BigNat -> BigNat
plusBigNatWord :: BigNat -> GmpLimb# -> BigNat

-- | Returns <a>nullBigNat</a> (see <a>isNullBigNat#</a>) in case of
--   underflow
minusBigNat :: BigNat -> BigNat -> BigNat

-- | Returns <a>nullBigNat</a> (see <a>isNullBigNat#</a>) in case of
--   underflow
minusBigNatWord :: BigNat -> GmpLimb# -> BigNat
timesBigNat :: BigNat -> BigNat -> BigNat
timesBigNatWord :: BigNat -> GmpLimb# -> BigNat

-- | Square <a>BigNat</a>
sqrBigNat :: BigNat -> BigNat

-- | If divisor is zero, <tt>(# <a>nullBigNat</a>, <a>nullBigNat</a>
--   #)</tt> is returned
quotRemBigNat :: BigNat -> BigNat -> (# BigNat, BigNat #)

-- | Note: Result of div/0 undefined
quotRemBigNatWord :: BigNat -> GmpLimb# -> (# BigNat, GmpLimb# #)
quotBigNatWord :: BigNat -> GmpLimb# -> BigNat
quotBigNat :: BigNat -> BigNat -> BigNat
remBigNat :: BigNat -> BigNat -> BigNat

-- | div/0 not checked
remBigNatWord :: BigNat -> GmpLimb# -> Word#
gcdBigNat :: BigNat -> BigNat -> BigNat
gcdBigNatWord :: BigNat -> Word# -> Word#

-- | Version of <a>powModInteger</a> operating on <a>BigNat</a>s
powModBigNat :: BigNat -> BigNat -> BigNat -> BigNat

-- | Version of <a>powModInteger</a> for <a>Word#</a>-sized moduli
powModBigNatWord :: BigNat -> BigNat -> GmpLimb# -> GmpLimb#

-- | Version of <a>recipModInteger</a> operating on <a>BigNat</a>s
recipModBigNat :: BigNat -> BigNat -> BigNat
shiftRBigNat :: BigNat -> Int# -> BigNat
shiftLBigNat :: BigNat -> Int# -> BigNat
testBitBigNat :: BigNat -> Int# -> Bool
andBigNat :: BigNat -> BigNat -> BigNat
xorBigNat :: BigNat -> BigNat -> BigNat
popCountBigNat :: BigNat -> Int#
orBigNat :: BigNat -> BigNat -> BigNat

-- | Specialised version of
--   
--   <pre>
--   bitBigNat = shiftLBigNat (wordToBigNat 1##)
--   </pre>
--   
--   avoiding a few redundant allocations
bitBigNat :: Int# -> BigNat

-- | Test if <a>BigNat</a> value is equal to zero.
isZeroBigNat :: BigNat -> Bool

-- | Test for special 0-sized <a>BigNat</a> representing underflows.
isNullBigNat# :: BigNat -> Int#
compareBigNatWord :: BigNat -> GmpLimb# -> Ordering
compareBigNat :: BigNat -> BigNat -> Ordering
eqBigNatWord :: BigNat -> GmpLimb# -> Bool
eqBigNatWord# :: BigNat -> GmpLimb# -> Int#
eqBigNat :: BigNat -> BigNat -> Bool
eqBigNat# :: BigNat -> BigNat -> Int#
gtBigNatWord# :: BigNat -> GmpLimb# -> Int#

-- | Compute greatest common divisor.
--   
--   <b>Warning</b>: result may become negative if (at least) one argument
--   is <tt>minBound</tt>
gcdInt :: Int# -> Int# -> Int#

-- | Compute greatest common divisor.
gcdWord :: Word# -> Word# -> Word#

-- | Version of <a>powModInteger</a> operating on <a>Word#</a>s
powModWord :: GmpLimb# -> GmpLimb# -> GmpLimb# -> GmpLimb#

-- | Version of <a>recipModInteger</a> operating on <a>Word#</a>s
recipModWord :: GmpLimb# -> GmpLimb# -> GmpLimb#

-- | Probalistic Miller-Rabin primality test.
--   
--   "<tt><a>testPrimeInteger</a> <i>n</i> <i>k</i></tt>" determines
--   whether <tt><i>n</i></tt> is prime and returns one of the following
--   results:
--   
--   <ul>
--   <li><tt>2#</tt> is returned if <tt><i>n</i></tt> is definitely
--   prime,</li>
--   <li><tt>1#</tt> if <tt><i>n</i></tt> is a <i>probable prime</i>,
--   or</li>
--   <li><tt>0#</tt> if <tt><i>n</i></tt> is definitely not a prime.</li>
--   </ul>
--   
--   The <tt><i>k</i></tt> argument controls how many test rounds are
--   performed for determining a <i>probable prime</i>. For more details,
--   see <a>GMP documentation for `mpz_probab_prime_p()`</a>.
testPrimeInteger :: Integer -> Int# -> Int#

-- | Version of <a>testPrimeInteger</a> operating on <a>BigNat</a>s
testPrimeBigNat :: BigNat -> Int# -> Int#

-- | Version of <a>testPrimeInteger</a> operating on <a>Word#</a>s
testPrimeWord# :: GmpLimb# -> Int# -> Int#

-- | Compute next prime greater than <tt><i>n</i></tt> probalistically.
--   
--   According to the GMP documentation, the underlying function
--   <tt>mpz_nextprime()</tt> "uses a probabilistic algorithm to identify
--   primes. For practical purposes it's adequate, the chance of a
--   composite passing will be extremely small."
nextPrimeInteger :: Integer -> Integer

-- | Version of <tt>nextPrimeInteger</tt> operating on <a>BigNat</a>s
nextPrimeBigNat :: BigNat -> BigNat

-- | Version of <a>nextPrimeInteger</a> operating on <a>Word#</a>s
nextPrimeWord# :: GmpLimb# -> GmpLimb#

-- | Version of <a>sizeInBaseInteger</a> operating on <a>BigNat</a>
sizeInBaseBigNat :: BigNat -> Int# -> Word#

-- | Compute number of digits (without sign) in given <tt><i>base</i></tt>.
--   
--   This function wraps <tt>mpz_sizeinbase()</tt> which has some
--   implementation pecularities to take into account:
--   
--   <ul>
--   <li>"<tt><a>sizeInBaseInteger</a> 0 <i>base</i> = 1</tt>" (see also
--   comment in <a>exportIntegerToMutableByteArray</a>).</li>
--   <li>This function is only defined if <tt><i>base</i> &gt;= 2#</tt> and
--   <tt><i>base</i> &lt;= 256#</tt> (Note: the documentation claims that
--   only <tt><i>base</i> &lt;= 62#</tt> is supported, however the actual
--   implementation supports up to base 256).</li>
--   <li>If <tt><i>base</i></tt> is a power of 2, the result will be exact.
--   In other cases (e.g. for <tt><i>base</i> = 10#</tt>), the result
--   <i>may</i> be 1 digit too large sometimes.</li>
--   <li>"<tt><a>sizeInBaseInteger</a> <i>i</i> 2#</tt>" can be used to
--   determine the most significant bit of <tt><i>i</i></tt>.</li>
--   </ul>
sizeInBaseInteger :: Integer -> Int# -> Word#

-- | Version of <a>sizeInBaseInteger</a> operating on <a>Word#</a>
sizeInBaseWord# :: Word# -> Int# -> Word#

-- | Version of <a>exportIntegerToAddr</a> operating on <a>BigNat</a>s.
exportBigNatToAddr :: BigNat -> Addr# -> Int# -> IO Word

-- | Dump <a>Integer</a> (without sign) to <tt><i>addr</i></tt> in base-256
--   representation.
--   
--   <pre>
--   <a>exportIntegerToAddr</a> <i>i</i> <i>addr</i> <i>e</i>
--   </pre>
--   
--   See description of <a>exportIntegerToMutableByteArray</a> for more
--   details.
exportIntegerToAddr :: Integer -> Addr# -> Int# -> IO Word

-- | Version of <a>exportIntegerToAddr</a> operating on <a>Word</a>s.
exportWordToAddr :: Word -> Addr# -> Int# -> IO Word

-- | Version of <a>exportIntegerToMutableByteArray</a> operating on
--   <a>BigNat</a>s.
exportBigNatToMutableByteArray :: BigNat -> MutableByteArray# RealWorld -> Word# -> Int# -> IO Word

-- | Dump <a>Integer</a> (without sign) to mutable byte-array in base-256
--   representation.
--   
--   The call
--   
--   <pre>
--   <a>exportIntegerToMutableByteArray</a> <i>i</i> <i>mba</i> <i>offset</i> <i>msbf</i>
--   </pre>
--   
--   writes
--   
--   <ul>
--   <li>the <a>Integer</a> <tt><i>i</i></tt></li>
--   <li>into the <a>MutableByteArray#</a> <tt><i>mba</i></tt> starting at
--   <tt><i>offset</i></tt></li>
--   <li>with most significant byte first if <tt>msbf</tt> is <tt>1#</tt>
--   or least significant byte first if <tt>msbf</tt> is <tt>0#</tt>,
--   and</li>
--   <li>returns number of bytes written.</li>
--   </ul>
--   
--   Use "<tt><a>sizeInBaseInteger</a> <i>i</i> 256#</tt>" to compute the
--   exact number of bytes written in advance for <tt><i>i</i> /= 0</tt>.
--   In case of <tt><i>i</i> == 0</tt>,
--   <a>exportIntegerToMutableByteArray</a> will write and report zero
--   bytes written, whereas <a>sizeInBaseInteger</a> report one byte.
--   
--   It's recommended to avoid calling
--   <a>exportIntegerToMutableByteArray</a> for small integers as this
--   function would currently convert those to big integers in msbf to call
--   <tt>mpz_export()</tt>.
exportIntegerToMutableByteArray :: Integer -> MutableByteArray# RealWorld -> Word# -> Int# -> IO Word

-- | Version of <a>exportIntegerToMutableByteArray</a> operating on
--   <a>Word</a>s.
exportWordToMutableByteArray :: Word -> MutableByteArray# RealWorld -> Word# -> Int# -> IO Word

-- | Version of <a>importIntegerFromAddr</a> constructing a <a>BigNat</a>
importBigNatFromAddr :: Addr# -> Word# -> Int# -> IO BigNat

-- | Read <a>Integer</a> (without sign) from memory location at
--   <tt><i>addr</i></tt> in base-256 representation.
--   
--   <pre>
--   <a>importIntegerFromAddr</a> <i>addr</i> <i>size</i> <i>msbf</i>
--   </pre>
--   
--   See description of <a>importIntegerFromByteArray</a> for more details.
importIntegerFromAddr :: Addr# -> Word# -> Int# -> IO Integer

-- | Version of <a>importIntegerFromByteArray</a> constructing a
--   <a>BigNat</a>
importBigNatFromByteArray :: ByteArray# -> Word# -> Word# -> Int# -> BigNat

-- | Read <a>Integer</a> (without sign) from byte-array in base-256
--   representation.
--   
--   The call
--   
--   <pre>
--   <a>importIntegerFromByteArray</a> <i>ba</i> <i>offset</i> <i>size</i> <i>msbf</i>
--   </pre>
--   
--   reads
--   
--   <ul>
--   <li><tt><i>size</i></tt> bytes from the <a>ByteArray#</a>
--   <tt><i>ba</i></tt> starting at <tt><i>offset</i></tt></li>
--   <li>with most significant byte first if <tt><i>msbf</i></tt> is
--   <tt>1#</tt> or least significant byte first if <tt><i>msbf</i></tt> is
--   <tt>0#</tt>, and</li>
--   <li>returns a new <a>Integer</a></li>
--   </ul>
importIntegerFromByteArray :: ByteArray# -> Word# -> Word# -> Int# -> Integer
