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


-- | fast multi-dimensional unboxed bit packed Bool arrays
--   
@package bitwise
@version 0.1.0.2


-- | Lifting boolean operations on <a>Bool</a> to bitwise operations on
--   <a>Bits</a>.
--   
--   Packing bits into words, and unpacking words into bits.
module Data.Bits.Bitwise

-- | Lift a boolean constant to a bitwise constant.
repeat :: (Num b, Bits b) => Bool -> b

-- | Lift a unary boolean operation to a bitwise operation.
--   
--   The implementation is by exhaustive input/output case analysis: thus
--   the operation provided must be total.
map :: (Num b, Bits b) => (Bool -> Bool) -> b -> b

-- | Lift a binary boolean operation to a bitwise operation.
--   
--   The implementation is by exhaustive input/output case analysis: thus
--   the operation provided must be total.
zipWith :: (Num b, Bits b) => (Bool -> Bool -> Bool) -> b -> b -> b

-- | True when any bit is set.
or :: (Num b, Bits b) => b -> Bool

-- | True when all bits are set.
and :: (Num b, Bits b) => b -> Bool

-- | True when the predicate is true for any bit.
any :: (Num b, Bits b) => (Bool -> Bool) -> b -> Bool

-- | True when the predicate is true for all bits.
all :: (Num b, Bits b) => (Bool -> Bool) -> b -> Bool

-- | Determine if a <a>Bits</a> is all 1s, all 0s, or neither.
isUniform :: (Num b, Bits b) => b -> Maybe Bool

-- | A mask with count least significant bits set.
mask :: (Num b, Bits b) => Int -> b

-- | Split a word into (lsb, msb). Ensures lsb has no set bits above the
--   split point.
splitAt :: (Num b, Bits b) => Int -> b -> (b, b)

-- | Join lsb with msb to make a word. Assumes lsb has no set bits above
--   the join point.
joinAt :: (Num b, Bits b) => Int -> b -> b -> b

-- | The least significant bit.
fromBool :: (Num b, Bits b) => Bool -> b

-- | Convert a little-endian list of bits to <a>Bits</a>.
fromListLE :: (Num b, Bits b) => [Bool] -> b

-- | Convert a <a>Bits</a> (with a defined <a>bitSize</a>) to a list of
--   bits, in little-endian order.
toListLE :: (Num b, Bits b) => b -> [Bool]

-- | Convert a big-endian list of bits to <a>Bits</a>.
fromListBE :: (Num b, Bits b) => [Bool] -> b

-- | Convert a <a>Bits</a> (with a defined <a>bitSize</a>) to a list of
--   bits, in big-endian order.
toListBE :: (Num b, Bits b) => b -> [Bool]

-- | Pack bits into a byte in little-endian order.
packWord8LE :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Word8

-- | Extract the bits from a byte in little-endian order.
unpackWord8LE :: Word8 -> (Bool, Bool, Bool, Bool, Bool, Bool, Bool, Bool)

-- | Pack bits into a byte in big-endian order.
packWord8BE :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Word8

-- | Extract the bits from a byte in big-endian order.
unpackWord8BE :: Word8 -> (Bool, Bool, Bool, Bool, Bool, Bool, Bool, Bool)


-- | Unboxed mutable bit arrays in the <a>IO</a> monad.
module Data.Array.BitArray.IO

-- | The type of mutable bit arrays in the <a>IO</a> monad.
data IOBitArray i

-- | Get the bounds of a bit array.
getBounds :: Ix i => IOBitArray i -> IO (i, i)

-- | Create a new array filled with an initial value.
newArray :: Ix i => (i, i) -> Bool -> IO (IOBitArray i)

-- | Create a new array filled with unspecified initial values.
newArray_ :: Ix i => (i, i) -> IO (IOBitArray i)

-- | Create a new array filled with values from a list.
newListArray :: Ix i => (i, i) -> [Bool] -> IO (IOBitArray i)

-- | Read from an array at an index.
readArray :: Ix i => IOBitArray i -> i -> IO Bool

-- | Write to an array at an index.
writeArray :: Ix i => IOBitArray i -> i -> Bool -> IO ()

-- | Alias for <a>map</a>.
mapArray :: Ix i => (Bool -> Bool) -> IOBitArray i -> IO (IOBitArray i)

-- | Create a new array by reading from another.
mapIndices :: (Ix i, Ix j) => (i, i) -> (i -> j) -> IOBitArray j -> IO (IOBitArray i)

-- | Get a list of all elements of an array.
getElems :: Ix i => IOBitArray i -> IO [Bool]

-- | Get a list of all (index, element) pairs.
getAssocs :: Ix i => IOBitArray i -> IO [(i, Bool)]

-- | Snapshot the array into an immutable form.
freeze :: Ix i => IOBitArray i -> IO (BitArray i)

-- | Convert an array from immutable form.
thaw :: Ix i => BitArray i -> IO (IOBitArray i)

-- | Copy an array.
copy :: Ix i => IOBitArray i -> IO (IOBitArray i)

-- | Fill an array with a uniform value.
fill :: Ix i => IOBitArray i -> Bool -> IO ()

-- | Short-circuit bitwise reduction: True when any bit is True.
or :: Ix i => IOBitArray i -> IO Bool

-- | Short-circuit bitwise reduction: False when any bit is False.
and :: Ix i => IOBitArray i -> IO Bool

-- | Short-circuit bitwise reduction: <a>Nothing</a> when any bits differ,
--   <a>Just</a> when all bits are the same.
isUniform :: Ix i => IOBitArray i -> IO (Maybe Bool)

-- | Bitwise reduction with an associative commutative boolean operator.
--   Implementation lifts from <a>Bool</a> to <tt>Bits</tt> and folds large
--   chunks at a time. Each bit is used as a source exactly once.
fold :: Ix i => (Bool -> Bool -> Bool) -> IOBitArray i -> IO (Maybe Bool)

-- | Bitwise map. Implementation lifts from <a>Bool</a> to <tt>Bits</tt>
--   and maps large chunks at a time.
map :: Ix i => (Bool -> Bool) -> IOBitArray i -> IO (IOBitArray i)

-- | Bitwise zipWith. Implementation lifts from <a>Bool</a> to
--   <tt>Bits</tt> and combines large chunks at a time.
--   
--   The bounds of the source arrays must be identical.
zipWith :: Ix i => (Bool -> Bool -> Bool) -> IOBitArray i -> IOBitArray i -> IO (IOBitArray i)

-- | Read from an array at an index without bounds checking. Unsafe.
unsafeReadArray :: Ix i => IOBitArray i -> i -> IO Bool

-- | Get a list of all elements of an array. Unsafe when the source array
--   can be modified later.
unsafeGetElems :: Ix i => IOBitArray i -> IO [Bool]

-- | Snapshot the array into an immutable form. Unsafe when the source
--   array can be modified later.
unsafeFreeze :: Ix i => IOBitArray i -> IO (BitArray i)

-- | Convert an array from immutable form. Unsafe to modify the result
--   unless the source array is never used later.
unsafeThaw :: Ix i => BitArray i -> IO (IOBitArray i)


-- | Unboxed mutable bit arrays in the <a>ST</a> monad.
module Data.Array.BitArray.ST

-- | The type of mutable bit arrays.
data STBitArray s i

-- | Get the bounds of a bit array.
getBounds :: Ix i => STBitArray s i -> ST s (i, i)

-- | Create a new array filled with an initial value.
newArray :: Ix i => (i, i) -> Bool -> ST s (STBitArray s i)

-- | Create a new array filled with a default initial value (<a>False</a>).
newArray_ :: Ix i => (i, i) -> ST s (STBitArray s i)

-- | Create a new array filled with values from a list.
newListArray :: Ix i => (i, i) -> [Bool] -> ST s (STBitArray s i)

-- | Read from an array at an index.
readArray :: Ix i => STBitArray s i -> i -> ST s Bool

-- | Write to an array at an index.
writeArray :: Ix i => STBitArray s i -> i -> Bool -> ST s ()

-- | Alias for <a>map</a>.
mapArray :: Ix i => (Bool -> Bool) -> STBitArray s i -> ST s (STBitArray s i)

-- | Create a new array by reading from another.
mapIndices :: (Ix i, Ix j) => (i, i) -> (i -> j) -> STBitArray s j -> ST s (STBitArray s i)

-- | Get a list of all elements of an array.
getElems :: Ix i => STBitArray s i -> ST s [Bool]

-- | Get a list of all (index, element) pairs.
getAssocs :: Ix i => STBitArray s i -> ST s [(i, Bool)]

-- | Snapshot the array into an immutable form.
freeze :: Ix i => STBitArray s i -> ST s (BitArray i)

-- | Convert an array from immutable form.
thaw :: Ix i => BitArray i -> ST s (STBitArray s i)

-- | Copy an array.
copy :: Ix i => STBitArray s i -> ST s (STBitArray s i)

-- | Fill an array with a uniform value.
fill :: Ix i => STBitArray s i -> Bool -> ST s ()

-- | Short-circuit bitwise reduction: True when any bit is True.
or :: Ix i => STBitArray s i -> ST s Bool

-- | Short-circuit bitwise reduction: False when any bit is False.
and :: Ix i => STBitArray s i -> ST s Bool

-- | Short-circuit bitwise reduction: <a>Nothing</a> when any bits differ,
--   <a>Just</a> when all bits are the same.
isUniform :: Ix i => STBitArray s i -> ST s (Maybe Bool)

-- | Bitwise reduction with an associative commutative boolean operator.
--   Implementation lifts from <a>Bool</a> to <tt>Bits</tt> and folds large
--   chunks at a time. Each bit is used as a source exactly once.
fold :: Ix i => (Bool -> Bool -> Bool) -> STBitArray s i -> ST s (Maybe Bool)

-- | Bitwise map. Implementation lifts from <a>Bool</a> to <tt>Bits</tt>
--   and maps large chunks at a time.
map :: Ix i => (Bool -> Bool) -> STBitArray s i -> ST s (STBitArray s i)

-- | Bitwise zipWith. Implementation lifts from <a>Bool</a> to
--   <tt>Bits</tt> and combines large chunks at a time.
--   
--   The bounds of the source arrays must be identical.
zipWith :: Ix i => (Bool -> Bool -> Bool) -> STBitArray s i -> STBitArray s i -> ST s (STBitArray s i)

-- | Read from an array at an index without bounds checking. Unsafe.
unsafeReadArray :: Ix i => STBitArray s i -> i -> ST s Bool

-- | Get a list of all elements of an array without copying. Unsafe when
--   the source array can be modified later.
unsafeGetElems :: Ix i => STBitArray s i -> ST s [Bool]

-- | Snapshot the array into an immutable form. Unsafe when the source
--   array can be modified later.
unsafeFreeze :: Ix i => STBitArray s i -> ST s (BitArray i)

-- | Convert an array from immutable form. Unsafe to modify the result
--   unless the source array is never used later.
unsafeThaw :: Ix i => BitArray i -> ST s (STBitArray s i)


-- | Immutable unboxed packed bit arrays using bitwise operations to
--   manipulate large chunks at a time much more quickly than individually
--   unpacking and repacking bits would allow.
module Data.Array.BitArray

-- | The type of immutable bit arrays.
data BitArray i

-- | The bounds of an array.
bounds :: Ix i => BitArray i -> (i, i)

-- | Create an array from a list of (index, element) pairs.
array :: Ix i => (i, i) -> [(i, Bool)] -> BitArray i

-- | Create an array from a list of elements.
listArray :: Ix i => (i, i) -> [Bool] -> BitArray i

-- | Create an array by accumulating a list of (index, operand) pairs from
--   a default seed with an operation.
accumArray :: Ix i => (Bool -> a -> Bool) -> Bool -> (i, i) -> [(i, a)] -> BitArray i

-- | Bit array indexing.
(!) :: Ix i => BitArray i -> i -> Bool

-- | A list of all the valid indices for this array.
indices :: Ix i => BitArray i -> [i]

-- | A list of the elements in this array.
elems :: Ix i => BitArray i -> [Bool]

-- | A list of the (index, element) pairs in this array.
assocs :: Ix i => BitArray i -> [(i, Bool)]

-- | A new array with updated values at the supplied indices.
(//) :: Ix i => BitArray i -> [(i, Bool)] -> BitArray i

-- | Accumulate with an operation and a list of (index, operand).
accum :: Ix i => (Bool -> a -> Bool) -> BitArray i -> [(i, a)] -> BitArray i

-- | Alias for <a>map</a>.
amap :: Ix i => (Bool -> Bool) -> BitArray i -> BitArray i

-- | Create a new array by mapping indices into a source array..
ixmap :: (Ix i, Ix j) => (i, i) -> (i -> j) -> BitArray j -> BitArray i

-- | A uniform array of bits.
fill :: Ix i => (i, i) -> Bool -> BitArray i

-- | A uniform array of <a>False</a>.
false :: Ix i => (i, i) -> BitArray i

-- | A uniform array of <a>True</a>.
true :: Ix i => (i, i) -> BitArray i

-- | Short-circuit bitwise reduction: True if any bit is True.
or :: Ix i => BitArray i -> Bool

-- | Short-circuit bitwise reduction: False if any bit is False.
and :: Ix i => BitArray i -> Bool

-- | Short-circuit bitwise reduction: Nothing if any bits differ.
isUniform :: Ix i => BitArray i -> Maybe Bool

-- | Bitwise reduction with an associative commutative boolean operator.
--   Implementation lifts from <a>Bool</a> to <tt>Bits</tt> and folds large
--   chunks at a time. Each bit is used as a source exactly once.
fold :: Ix i => (Bool -> Bool -> Bool) -> BitArray i -> Maybe Bool

-- | Bitwise map. Implementation lifts from <a>Bool</a> to <tt>Bits</tt>
--   and maps large chunks at a time.
map :: Ix i => (Bool -> Bool) -> BitArray i -> BitArray i

-- | Bitwise zipWith. Implementation lifts from <a>Bool</a> to
--   <tt>Bits</tt> and combines large chunks at a time.
--   
--   The bounds of the source arrays must be identical.
zipWith :: Ix i => (Bool -> Bool -> Bool) -> BitArray i -> BitArray i -> BitArray i

-- | Bounds checking combined with array indexing.
(!?) :: Ix i => BitArray i -> i -> Maybe Bool

-- | Bit array indexing without bounds checking. Unsafe.
(!!!) :: Ix i => BitArray i -> i -> Bool


-- | Copy bit array data to and from ByteStrings.
module Data.Array.BitArray.ByteString

-- | Copy to a ByteString. The most significant bits of the last byte are
--   padded with 0 unless the array was a multiple of 8 bits in size.
toByteString :: Ix i => BitArray i -> ByteString

-- | Copy from a ByteString. Much like <tt>listArray</tt> but with packed
--   bits.
fromByteString :: Ix i => (i, i) -> ByteString -> BitArray i

-- | Copy to a ByteString. The most significant bits of the last byte are
--   padded with 0 unless the array was a multiple of 8 bits in size.
toByteStringIO :: Ix i => IOBitArray i -> IO ByteString

-- | Copy from a ByteString. Much like <tt>newListArray</tt> but with
--   packed bits.
fromByteStringIO :: Ix i => (i, i) -> ByteString -> IO (IOBitArray i)


-- | Encode and decode both versions (binary P4 and plain P1) of PBM: the
--   portable bitmap lowest common denominator monochrome image file
--   format.
--   
--   References:
--   
--   <ul>
--   <li>pbm(5)</li>
--   <li>The PBM Format
--   <a>http://netpbm.sourceforge.net/doc/pbm.html</a></li>
--   </ul>
--   
--   Bugs:
--   
--   <ul>
--   <li>This implementation is not fully compliant with the PBM
--   specification, with respect to point 8 in the second reference above
--   which states that <i>a comment can actually be in the middle of what
--   you might consider a token</i> Such a pathological PBM file might be
--   rejected by <a>decodePBM</a>, but may instead be wrongly decoded if
--   (for example) the comment were in the middle of the image width token,
--   leading to it being interpreted as a (smaller) width and height.</li>
--   </ul>
module Codec.Image.PBM

-- | A decoded PBM image. <a>pbmWidth</a> must be less or equal to the
--   width of the <a>pbmPixels</a> array (which has its first index in Y
--   and the second in X, with lowest coordinates at the top left).
--   
--   False pixels are white, True pixels are black. Pixels to the right of
--   <a>pbmWidth</a> are don't care padding bits. However, these padding
--   bits are likely to invalidate aggregrate <a>fold</a> operations. See
--   <a>trimPBM</a>.
data PBM
PBM :: !Int -> !(BitArray (Int, Int)) -> PBM
pbmWidth :: PBM -> !Int
pbmPixels :: PBM -> !(BitArray (Int, Int))

-- | Encode a binary PBM (P4) image, padding rows to multiples of 8 bits as
--   necessary.
encodePBM :: BitArray (Int, Int) -> ByteString

-- | Encode a plain PBM (P1) image.
--   
--   No restrictions on pixels array size, but the file format is
--   exceedingly wasteful of space.
encodePlainPBM :: BitArray (Int, Int) -> String

-- | Possible reasons for encoding to fail.
data EncodeError

-- | array width is not a multiple of 8 bits
BadPixelWidth :: PBM -> EncodeError
encErrPBM :: EncodeError -> PBM

-- | image width is too smaller than array width
BadSmallWidth :: PBM -> EncodeError
encErrPBM :: EncodeError -> PBM

-- | image width is larger than array width
BadLargeWidth :: PBM -> EncodeError
encErrPBM :: EncodeError -> PBM

-- | Encode a pre-padded <a>PBM</a> to a binary PBM (P4) image.
--   
--   The pixels array must have a multiple of 8 bits per row. The image
--   width may be less than the pixel array width, with up to 7 padding
--   bits at the end of each row.
encodePBM' :: PBM -> Either EncodeError ByteString

-- | Possible reasons for decoding to fail, with the input that failed.
data DecodeError a

-- | First character was not P.
BadMagicP :: a -> DecodeError a

-- | Second character was not 4 (binary) or 1 (plain).
BadMagicN :: a -> DecodeError a

-- | The width could not be parsed, or was non-positive.
BadWidth :: a -> DecodeError a

-- | The height could not be parsed, or was non-positive.
BadHeight :: a -> DecodeError a

-- | Parsing failed at the space before the pixel data.
BadSpace :: a -> DecodeError a

-- | There weren't enough bytes of pixel data.
BadPixels :: a -> DecodeError a

-- | Decode a binary PBM (P4) image.
decodePBM :: ByteString -> Either (DecodeError ByteString) (PBM, ByteString)

-- | Decode a plain PBM (P1) image.
--   
--   Note that the pixel array size is kept as-is (with the width not
--   necessarily a multiple of 8 bits).
decodePlainPBM :: String -> Either (DecodeError String) (PBM, String)

-- | Decode a sequence of binary PBM (P4) images.
--   
--   Keeps decoding until end of input (in which case the <a>snd</a> of the
--   result is <a>Nothing</a>) or an error occurred.
decodePBMs :: ByteString -> ([PBM], Maybe (DecodeError ByteString))

-- | Add padding bits at the end of each row to make the array width a
--   multiple of 8 bits, required for binary PBM (P4) encoding.
padPBM :: PBM -> PBM

-- | Trim any padding bits, required for <tt>fold</tt> operations to give
--   meaningful results.
--   
--   Fails for invalid <a>PBM</a> with image width greater than array
--   width.
trimPBM :: PBM -> Maybe PBM

-- | Trim then pad. The resulting <a>PBM</a> (if any) is suitable for
--   encoding to binary PBM (P4), moreover its padding bits will be
--   cleared.
repadPBM :: PBM -> Maybe PBM
instance Eq a => Eq (DecodeError a)
instance Ord a => Ord (DecodeError a)
instance Read a => Read (DecodeError a)
instance Show a => Show (DecodeError a)