-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | fast multi-dimensional unboxed bit packed Bool arrays -- -- Unboxed multidimensional bit packed Bool arrays with fast aggregate -- operations based on lifting Bool operations to bitwise operations. -- -- There are many other bit packed structures out there, but none met all -- of these requirements: -- --
    --
  1. unboxed bit packed Bool array,
    2. --
  2. multi-dimensional indexing,
    3. --
  3. fast (de)serialization, or interoperable with foreign code,
    4. --
  4. fast aggregate operations (fold, map, zip).
    5. --
-- -- Quick tour of the bitwise library: -- -- -- -- Very rough performance benchmarks: -- -- @package bitwise @version 0.1 -- | Lifting boolean operations on Bool to bitwise operations on -- Bits. -- -- Packing bits into words, and unpacking words into bits. module Data.Bits.Bitwise -- | Lift a boolean constant to a bitwise constant. repeat :: 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 :: 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 :: Bits b => (Bool -> Bool -> Bool) -> b -> b -> b -- | True when any bit is set. or :: Bits b => b -> Bool -- | True when all bits are set. and :: Bits b => b -> Bool -- | True when the predicate is true for any bit. any :: Bits b => (Bool -> Bool) -> b -> Bool -- | True when the predicate is true for all bits. all :: Bits b => (Bool -> Bool) -> b -> Bool -- | Determine if a Bits is all 1s, all 0s, or neither. isUniform :: Bits b => b -> Maybe Bool -- | A mask with count least significant bits set. mask :: Bits b => Int -> b -- | Split a word into (lsb, msb). Ensures lsb has no set bits above the -- split point. splitAt :: 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 :: Bits b => Int -> b -> b -> b -- | The least significant bit. fromBool :: Bits b => Bool -> b -- | Convert a little-endian list of bits to Bits. fromListLE :: Bits b => [Bool] -> b -- | Convert a Bits (with a defined bitSize) to a list of -- bits, in little-endian order. toListLE :: Bits b => b -> [Bool] -- | Convert a big-endian list of bits to Bits. fromListBE :: Bits b => [Bool] -> b -- | Convert a Bits (with a defined bitSize) to a list of -- bits, in big-endian order. toListBE :: 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 IO monad. module Data.Array.BitArray.IO -- | The type of mutable bit arrays in the IO 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 map. 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: Nothing when any bits differ, -- Just 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 Bool to Bits 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 Bool to Bits -- and maps large chunks at a time. map :: Ix i => (Bool -> Bool) -> IOBitArray i -> IO (IOBitArray i) -- | Bitwise zipWith. Implementation lifts from Bool to -- Bits 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 ST 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 (False). 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 map. 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: Nothing when any bits differ, -- Just 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 Bool to Bits 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 Bool to Bits -- 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 Bool to -- Bits 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 map. 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 False. false :: Ix i => (i, i) -> BitArray i -- | A uniform array of True. 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 Bool to Bits 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 Bool to Bits -- and maps large chunks at a time. map :: Ix i => (Bool -> Bool) -> BitArray i -> BitArray i -- | Bitwise zipWith. Implementation lifts from Bool to -- Bits 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 listArray 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 newListArray 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: -- -- -- -- Bugs: -- -- module Codec.Image.PBM -- | A decoded PBM image. pbmWidth must be less or equal to the -- width of the pbmPixels 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 -- pbmWidth are don't care padding bits. However, these padding -- bits are likely to invalidate aggregrate fold operations. See -- trimPBM. 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 PBM 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 snd of the -- result is Nothing) 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 fold operations to give -- meaningful results. -- -- Fails for invalid PBM with image width greater than array -- width. trimPBM :: PBM -> Maybe PBM -- | Trim then pad. The resulting PBM (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)