-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Bit-vectors library
--
-- Bit-vectors implemented as a wrapper over integers.
@package bv
@version 0.1.0
-- | Implementation of bit-vectors as wrappers over Integer.
--
--
-- - Bit-vectors are interpreted as unsigned integers (i.e. natural
-- numbers) except for some very specific cases.
-- - Bit-vectors are size-polymorphic insofar as most operations
-- treat a bit-vector of size k as of size n for n >=
-- k if required.
--
--
-- For documentation purposes we will write [n]k to denote a
-- bit-vector of size n representing the natural number
-- k.
module Data.BitVector
-- | An alias for BV.
type BitVector = BV
-- | Big-endian pseudo size-polymorphic bit-vectors.
data BV
-- | The size of a bit-vector.
size :: BV -> Int
-- | An alias for size.
width :: BV -> Int
-- | The value of a bit-vector, as a natural number.
nat :: BV -> Integer
-- | An alias for nat.
uint :: BV -> Integer
-- | 2's complement value of a bit-vector.
int :: BV -> Integer
-- | Create a bit-vector given a size and an integer value.
--
--
-- >>> bitVec 4 3
-- [4]3
--
--
-- This function also handles negative values.
--
--
-- >>> bitVec 4 (-1)
-- [4]15
--
bitVec :: Integral a => Int -> a -> BV
-- | Create a mask of ones.
ones :: Int -> BV
-- | Create a mask of zeros.
zeros :: Int -> BV
-- | Fixed-size equality.
--
-- In contrast with ==, which is size-polymorphic, this
-- equality requires both bit-vectors to be of equal size.
--
--
-- >>> [n]k ==. [m]k
-- False
--
--
--
-- >>> [n]k == [n]k
-- True
--
(==.) :: BV -> BV -> Bool
-- | Fixed-size inequality.
--
-- The negated version of ==..
(/=.) :: BV -> BV -> Bool
-- | Bit indexing.
--
-- u @. i stands for the i-th bit of u.
--
--
-- >>> [4]2 @. 0
-- False
--
--
--
-- >>> [4]2 @. 1
-- True
--
(@.) :: BV -> Int -> Bool
-- | Bit-string extraction.
--
--
-- u @@ (j,i) == fromBits (map (u @.) [j,j-1..i])
--
--
--
-- >>> [4]7 @@ (3,1)
-- [3]3
--
(@@) :: BV -> (Int, Int) -> BV
-- | Reverse bit-indexing.
--
-- Index from the end of the sequenc
--
--
-- u !. i == u @. (size u - i - 1)
--
--
--
-- >>> [3]3 !. 0
-- False
--
(!.) :: BV -> Int -> Bool
-- | Take least significant bits.
--
--
-- least m u == u @@ (m-1,0)
--
least :: Int -> BV -> BV
-- | Take most significant bits.
--
--
-- most m u == u @@ (n-1,n-m)
--
most :: Int -> BV -> BV
-- | Most significant bit.
--
--
-- msb u == u !. 0
--
msb :: BV -> Bool
-- | Least significant bit.
--
--
-- lsb u == u @. 0
--
lsb :: BV -> Bool
-- | Most significant 1-bit.
--
-- Pre: input must be non-zero.
--
--
-- >>> msb1 [4]2
-- 1
--
--
--
-- >>> msb1 [4]4
-- 2
--
msb1 :: BV -> Int
-- | 2's complement signed division.
sdiv :: BV -> BV -> BV
-- | 2's complement signed remainder (sign follows dividend).
srem :: BV -> BV -> BV
-- | 2's complement signed remainder (sign follows divisor).
smod :: BV -> BV -> BV
-- | Ceiling logarithm base 2.
--
-- Pre: input bit-vector must be non-zero.
lg2 :: BV -> BV
-- | Concatenation of two bit-vectors.
(#) :: BV -> BV -> BV
-- | Logical extension.
--
--
-- >>> zeroExtend 3 [1]1
-- [4]1
--
zeroExtend :: Int -> BV -> BV
-- | Arithmetic extension.
--
--
-- >>> signExtend 2 [2]1
-- [4]1
--
--
--
-- >>> signExtend 2 [2]3
-- [4]15
--
signExtend :: Int -> BV -> BV
-- |
-- foldl_ f z (fromBits [un, ..., u1, u0]) == ((((z `f` un) `f` ...) `f` u1) `f` u0)
--
--
--
-- foldl_ f e = fromBits . foldl f e . toBits
--
foldl_ :: (a -> Bool -> a) -> a -> BV -> a
-- |
-- foldr_ f z (fromBits [un, ..., u1, u0]) == un f (... f (u1 `f` (u0 `f` z)))
--
--
--
-- foldr_ f e = fromBits . foldr f e . toBits
--
foldr_ :: (Bool -> a -> a) -> a -> BV -> a
-- |
-- reverse_ == fromBits . reverse . toBits
--
reverse_ :: BV -> BV
-- | Pre: if replicate_ n u then n > 0 must
-- hold.
--
--
-- replicate_ n == fromBits . concat . replicate n . toBits
--
replicate_ :: Int -> BV -> BV
-- | An alias for complement.
not_ :: BV -> BV
-- | Negated .&..
nand :: BV -> BV -> BV
-- | Negated .|..
nor :: BV -> BV -> BV
-- | Negated xor.
xnor :: BV -> BV -> BV
-- | Left shift.
(<<.) :: BV -> BV -> BV
-- | Logical right shift.
(>>.) :: BV -> BV -> BV
-- | Arithmetic right shift
ashr :: BV -> BV -> BV
-- | Rotate left.
(<<<.) :: BV -> BV -> BV
-- | Rotate right.
(>>>.) :: BV -> BV -> BV
-- | Create a bit-vector from a big-endian list of bits.
--
--
-- >>> fromBits [False, False, True]
-- [3]1
--
fromBits :: [Bool] -> BV
-- | Create a big-endian list of bits from a bit-vector.
--
--
-- >>> toBits [4]11
-- [True, False, True, True]
--
toBits :: BV -> [Bool]
-- | Greatest natural number representable with n bits.
maxNat :: Integral a => Int -> a
-- | Minimum width of a bit-vector to represent a given integer number.
--
--
-- >>> integerWith 4
-- 3
--
--
--
-- >>> integerWith (-4)
-- 4
--
integerWidth :: Integer -> Int
instance Bits BV
instance Integral BV
instance Enum BV
instance Real BV
instance Num BV
instance Ord BV
instance Eq BV
instance Show BV