diff --git a/bits-extra.cabal b/bits-extra.cabal --- a/bits-extra.cabal +++ b/bits-extra.cabal @@ -1,22 +1,21 @@ -cabal-version: 2.2 +cabal-version: 2.2 -name: bits-extra -version: 0.0.1.4 -synopsis: Useful bitwise operations -description: Please see the README on Github at -category: Data, Bit -homepage: https://github.com/haskell-works/bits-extra#readme -bug-reports: https://github.com/haskell-works/bits-extra/issues -author: John Ky -maintainer: newhoggy@gmail.com -copyright: 2018-2019 John Ky -license: BSD-3-Clause -license-file: LICENSE -tested-with: GHC == 8.8.1, GHC == 8.6.5, GHC == 8.4.4, GHC == 8.2.2 -build-type: Simple -extra-source-files: - ChangeLog.md - README.md +name: bits-extra +version: 0.0.1.5 +synopsis: Useful bitwise operations +description: Please see the README on Github at +category: Data, Bit +homepage: https://github.com/haskell-works/bits-extra#readme +bug-reports: https://github.com/haskell-works/bits-extra/issues +author: John Ky +maintainer: newhoggy@gmail.com +copyright: 2018-2019 John Ky +license: BSD-3-Clause +license-file: LICENSE +tested-with: GHC == 8.8.1, GHC == 8.6.5, GHC == 8.4.4, GHC == 8.2.2 +build-type: Simple +extra-source-files: ChangeLog.md + README.md source-repository head type: git @@ -27,68 +26,82 @@ manual: False default: False -common base { build-depends: base >= 4.8 && < 5 } -common criterion { build-depends: criterion >= 1.3 && < 1.6 } -common ghc-prim { build-depends: ghc-prim >= 0.5 && < 0.6 } -common hedgehog { build-depends: hedgehog >= 0.5.3 && < 1.1 } -common hspec { build-depends: hspec >= 2.4 && < 2.8 } -common hw-hedgehog { build-depends: hw-hedgehog >= 0.1 && < 0.2 } -common hw-hspec-hedgehog { build-depends: hw-hspec-hedgehog >= 0.1 && < 0.2 } -common vector { build-depends: vector >= 0.12 && < 0.13 } +common base { build-depends: base >= 4.8 && < 5 } +common criterion { build-depends: criterion >= 1.3 && < 1.6 } +common doctest { build-depends: doctest >= 0.16.2 && < 0.17 } +common doctest-discover { build-depends: doctest-discover >= 0.2 && < 0.3 } +common ghc-prim { build-depends: ghc-prim >= 0.5 && < 0.6 } +common hedgehog { build-depends: hedgehog >= 0.5.3 && < 1.1 } +common hspec { build-depends: hspec >= 2.4 && < 2.8 } +common hw-hedgehog { build-depends: hw-hedgehog >= 0.1 && < 0.2 } +common hw-hspec-hedgehog { build-depends: hw-hspec-hedgehog >= 0.1 && < 0.2 } +common vector { build-depends: vector >= 0.12 && < 0.13 } common config - default-language: Haskell2010 - ghc-options: -Wall + default-language: Haskell2010 + ghc-options: -Wall if (flag(bmi2)) && (impl(ghc >= 8.4.1)) - ghc-options: -mbmi2 -msse4.2 - cpp-options: -DBMI2_ENABLED + ghc-options: -mbmi2 -msse4.2 + cpp-options: -DBMI2_ENABLED +common bits-extra + build-depends: bits-extra + library - import: base, config - , ghc-prim - , vector - hs-source-dirs: src - ghc-options: -O2 - autogen-modules: Paths_bits_extra - exposed-modules: - Data.Bits.BitSize - Data.Bits.Pdep - Data.Bits.Pdep.Slow - Data.Bits.Pext - Data.Bits.Pext.Slow - other-modules: - Data.Bits.Pdep.Prim - Data.Bits.Pext.Prim - Paths_bits_extra + import: base, config + , ghc-prim + , vector + hs-source-dirs: src + ghc-options: -O2 + autogen-modules: Paths_bits_extra + exposed-modules: Data.Bits.BitSize + Data.Bits.Pdep + Data.Bits.Pdep.Slow + Data.Bits.Pext + Data.Bits.Pext.Slow + other-modules: Data.Bits.Pdep.Prim + Data.Bits.Pext.Prim + Paths_bits_extra test-suite bits-extra-test - import: base, config - , ghc-prim - , hedgehog - , hspec - , hw-hedgehog - , hw-hspec-hedgehog - type: exitcode-stdio-1.0 - main-is: Spec.hs - hs-source-dirs: test - ghc-options: -threaded -rtsopts -with-rtsopts=-N - autogen-modules: Paths_bits_extra - build-depends: bits-extra - build-tool-depends: hspec-discover:hspec-discover - other-modules: - Data.Bits.PdepSpec - Data.Bits.PextSpec - Paths_bits_extra + import: base, config + , ghc-prim + , hedgehog + , hspec + , hw-hedgehog + , hw-hspec-hedgehog + type: exitcode-stdio-1.0 + main-is: Spec.hs + hs-source-dirs: test + ghc-options: -threaded -rtsopts -with-rtsopts=-N + autogen-modules: Paths_bits_extra + build-depends: bits-extra + build-tool-depends: hspec-discover:hspec-discover + other-modules: Data.Bits.PdepSpec + Data.Bits.PextSpec + Paths_bits_extra benchmark bench - import: base, config - , criterion - , ghc-prim - , vector - type: exitcode-stdio-1.0 - main-is: Main.hs - other-modules: Paths_bits_extra - autogen-modules: Paths_bits_extra - hs-source-dirs: bench - ghc-options: -O2 - build-depends: bits-extra + import: base, config + , criterion + , ghc-prim + , vector + type: exitcode-stdio-1.0 + main-is: Main.hs + other-modules: Paths_bits_extra + autogen-modules: Paths_bits_extra + hs-source-dirs: bench + ghc-options: -O2 + build-depends: bits-extra + +test-suite hw-json-doctest + import: base, config + , doctest + , doctest-discover + , bits-extra + default-language: Haskell2010 + type: exitcode-stdio-1.0 + ghc-options: -threaded + main-is: DoctestDriver.hs + HS-Source-Dirs: doctest + build-tool-depends: doctest-discover:doctest-discover diff --git a/doctest/DoctestDriver.hs b/doctest/DoctestDriver.hs new file mode 100644 --- /dev/null +++ b/doctest/DoctestDriver.hs @@ -0,0 +1,12 @@ +{-# LANGUAGE CPP #-} + +#if MIN_VERSION_GLASGOW_HASKELL(8,4,4,0) +{-# OPTIONS_GHC -F -pgmF doctest-discover #-} +#else +module Main where + +import qualified System.IO as IO + +main :: IO () +main = IO.putStrLn "WARNING: doctest will not run on GHC versions earlier than 8.4.4" +#endif diff --git a/src/Data/Bits/Pdep.hs b/src/Data/Bits/Pdep.hs --- a/src/Data/Bits/Pdep.hs +++ b/src/Data/Bits/Pdep.hs @@ -1,5 +1,13 @@ {-# LANGUAGE CPP #-} +{-| +Module : Data.Bits.Pdep.Prim +Description : Parallel deposit operations +Copyright : (c) John Ky, 2018-2019 +License : BSD-3-Clause +Maintainer : newhoggy@gmail.com +Stability : stable +-} module Data.Bits.Pdep ( Pdep(..) , fastPdepEnabled @@ -11,8 +19,17 @@ -- | Bitwise parallel deposit. Deposits bits from the source at the locations -- described by the mask. +-- +-- Copies lower order bits from 'src' to 'mask' 1-bit locations in the return value; +-- 'mask' 0-bit locations in the return value will be cleared. +-- +-- >>> pdep 1 1 :: Word64 +-- 1 class Pdep a where - pdep :: a -> a -> a + pdep + :: a -- ^ the bitmap from which bits will be extracted + -> a -- ^ the bitmap selecting the bit locations that are to be deposited to + -> a -- ^ the bitmap containing the deposited bits with other bits bits cleared instance Pdep Word where pdep = P.primPdep @@ -36,6 +53,9 @@ -- | Runtime flag indicating whether the 'pdep' function is using the high-performance. -- BMI2 instruction set. A value of `False` indicates that `pdep` is emulated. +-- +-- Actual performance when using the BMI2 instruction set will vary according to CPU +-- model. For example Intel CPUs currently outperform AMD CPUs in this area. fastPdepEnabled :: Bool fastPdepEnabled = P.fastPdepEnabled {-# INLINE fastPdepEnabled #-} diff --git a/src/Data/Bits/Pdep/Prim.hs b/src/Data/Bits/Pdep/Prim.hs --- a/src/Data/Bits/Pdep/Prim.hs +++ b/src/Data/Bits/Pdep/Prim.hs @@ -1,6 +1,14 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE MagicHash #-} +{-| +Module : Data.Bits.Pdep.Prim +Description : Primop wrappers for the Parallel Deposit operation +Copyright : (c) John Ky, 2018-2019 +License : BSD-3-Clause +Maintainer : newhoggy@gmail.com +Stability : stable +-} module Data.Bits.Pdep.Prim ( primPdep , primPdep8 @@ -18,11 +26,33 @@ import Data.Bits.Pdep.Slow #endif -primPdep :: Word -> Word -> Word +-- | Bitwise parallel deposit for 'Word'. Deposits bits from the source at the locations +-- described by the mask. +-- +-- Copies lower order bits from 'src' to 'mask' 1-bit locations in the return value; +-- 'mask' 0-bit locations in the return value will be cleared. +-- +-- >>> primPdep 1 1 +-- 1 +primPdep + :: Word -- ^ word containing the bits that will be deposited + -> Word -- ^ bitmap selecting the bits that are to be deposited + -> Word -- ^ word containing the deposited bits primPdep src mask = fromIntegral (primPdep64 (fromIntegral src) (fromIntegral mask)) {-# INLINE primPdep #-} -primPdep64 :: Word64 -> Word64 -> Word64 +-- | Bitwise parallel deposit for 'Word64'. Deposits bits from the source at the locations +-- described by the mask. +-- +-- Copies lower order bits from 'src' to 'mask' 1-bit locations in the return value; +-- 'mask' 0-bit locations in the return value will be cleared. +-- +-- >>> primPdep64 1 1 +-- 1 +primPdep64 + :: Word64 -- ^ word containing the bits that will be deposited + -> Word64 -- ^ bitmap selecting the bits that are to be deposited + -> Word64 -- ^ word containing the deposited bits #if MIN_VERSION_base(4,11,0) && defined(BMI2_ENABLED) primPdep64 (W64# src#) (W64# mask#) = W64# (pdep64# src# mask#) #else @@ -30,7 +60,18 @@ #endif {-# INLINE primPdep64 #-} -primPdep32 :: Word32 -> Word32 -> Word32 +-- | Bitwise parallel deposit for 'Word32'. Deposits bits from the source at the locations +-- described by the mask. +-- +-- Copies lower order bits from 'src' to 'mask' 1-bit locations in the return value; +-- 'mask' 0-bit locations in the return value will be cleared. +-- +-- >>> primPdep32 1 1 +-- 1 +primPdep32 + :: Word32 -- ^ word containing the bits that will be deposited + -> Word32 -- ^ bitmap selecting the bits that are to be deposited + -> Word32 -- ^ word containing the deposited bits #if MIN_VERSION_base(4,11,0) && defined(BMI2_ENABLED) primPdep32 (W32# src#) (W32# mask#) = W32# (pdep32# src# mask#) #else @@ -38,11 +79,33 @@ #endif {-# INLINE primPdep32 #-} -primPdep16 :: Word16 -> Word16 -> Word16 +-- | Bitwise parallel deposit for 'Word16'. Deposits bits from the source at the locations +-- described by the mask. +-- +-- Copies lower order bits from 'src' to 'mask' 1-bit locations in the return value; +-- 'mask' 0-bit locations in the return value will be cleared. +-- +-- >>> primPdep16 1 1 +-- 1 +primPdep16 + :: Word16 -- ^ word containing the bits that will be deposited + -> Word16 -- ^ bitmap selecting the bits that are to be deposited + -> Word16 -- ^ word containing the deposited bits primPdep16 src mask = fromIntegral (primPdep32 (fromIntegral src) (fromIntegral mask)) {-# INLINE primPdep16 #-} -primPdep8 :: Word8 -> Word8 -> Word8 +-- | Bitwise parallel deposit for 'Word8'. Deposits bits from the source at the locations +-- described by the mask. +-- +-- Copies lower order bits from 'src' to 'mask' 1-bit locations in the return value; +-- 'mask' 0-bit locations in the return value will be cleared. +-- +-- >>> primPdep8 1 1 +-- 1 +primPdep8 + :: Word8 -- ^ word containing the bits that will be deposited + -> Word8 -- ^ bitmap selecting the bits that are to be deposited + -> Word8 -- ^ word containing the deposited bits primPdep8 src mask = fromIntegral (primPdep32 (fromIntegral src) (fromIntegral mask)) {-# INLINE primPdep8 #-} diff --git a/src/Data/Bits/Pdep/Slow.hs b/src/Data/Bits/Pdep/Slow.hs --- a/src/Data/Bits/Pdep/Slow.hs +++ b/src/Data/Bits/Pdep/Slow.hs @@ -1,3 +1,11 @@ +{-| +Module : Data.Bits.Pdep.Prim +Description : Parallel deposit operations (emulated) +Copyright : (c) John Ky, 2018-2019 +License : BSD-3-Clause +Maintainer : newhoggy@gmail.com +Stability : stable +-} module Data.Bits.Pdep.Slow ( SlowPdep(..) ) where @@ -6,6 +14,14 @@ import GHC.Int import GHC.Word +-- | Bitwise parallel deposit for 'Word64'. Deposits bits from the source at the locations +-- described by the mask. +-- +-- Copies lower order bits from 'src' to 'mask' 1-bit locations in the return value; +-- 'mask' 0-bit locations in the return value will be cleared. +-- +-- >>> slowPdep64 1 1 +-- 1 slowPdep64 :: Word64 -> Word64 -> Word64 slowPdep64 = slowPdep64' 0 diff --git a/src/Data/Bits/Pext.hs b/src/Data/Bits/Pext.hs --- a/src/Data/Bits/Pext.hs +++ b/src/Data/Bits/Pext.hs @@ -1,6 +1,14 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE MagicHash #-} +{-| +Module : Data.Bits.Pext.Prim +Description : Parallel extract operations +Copyright : (c) John Ky, 2018-2019 +License : BSD-3-Clause +Maintainer : newhoggy@gmail.com +Stability : stable +-} module Data.Bits.Pext ( Pext(..) , fastPextEnabled @@ -10,10 +18,18 @@ import qualified Data.Bits.Pext.Prim as P --- | Bitwise parallel extosit. extosits bits from the source at the locations --- described by the mask. +-- | Parallel extract bits for 'Word64' +-- +-- Copies selected bits from 'src' to contiguous low-order bits of the return value; +-- higher-order return value bits are cleared. +-- +-- >>> pext 1 1 :: Word64 +-- 1 class Pext a where - pext :: a -> a -> a + pext + :: a -- ^ the bitmap from which bits will be extracted + -> a -- ^ the bitmap selecting the bits that are to be extracted + -> a -- ^ the bitmap containing the extract bits with higher-order bits cleared instance Pext Word where pext = P.primPext @@ -37,6 +53,9 @@ -- | Runtime flag indicating whether the 'pext' function is using the high-performance. -- BMI2 instruction set. A value of `False` indicates that `pext` is emulated. +-- +-- Actual performance when using the BMI2 instruction set will vary according to CPU +-- model. For example Intel CPUs currently outperform AMD CPUs in this area. fastPextEnabled :: Bool fastPextEnabled = P.fastPextEnabled {-# INLINE fastPextEnabled #-} diff --git a/src/Data/Bits/Pext/Prim.hs b/src/Data/Bits/Pext/Prim.hs --- a/src/Data/Bits/Pext/Prim.hs +++ b/src/Data/Bits/Pext/Prim.hs @@ -1,6 +1,14 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE MagicHash #-} +{-| +Module : Data.Bits.Pext.Prim +Description : Primop wrappers for the Parallel Extract operation +Copyright : (c) John Ky, 2018-2019 +License : BSD-3-Clause +Maintainer : newhoggy@gmail.com +Stability : stable +-} module Data.Bits.Pext.Prim ( primPext , primPext8 @@ -18,11 +26,24 @@ import Data.Bits.Pext.Slow #endif -primPext :: Word -> Word -> Word +primPext + :: Word + -> Word + -> Word primPext src mask = fromIntegral (primPext64 (fromIntegral src) (fromIntegral mask)) {-# INLINE primPext #-} -primPext64 :: Word64 -> Word64 -> Word64 +-- | Parallel extract bits for 'Word64' +-- +-- Copies selected bits from 'src' to contiguous low-order bits of the return value; +-- higher-order return value bits are cleared. +-- +-- >>> primPext64 1 1 +-- 1 +primPext64 + :: Word64 -- ^ word from which bits will be extracted + -> Word64 -- ^ bitmap selecting the bits that are to be extracted + -> Word64 -- ^ word containing the extracted bits #if MIN_VERSION_base(4,11,0) && defined(BMI2_ENABLED) primPext64 (W64# src#) (W64# mask#) = W64# (pext64# src# mask#) #else @@ -30,7 +51,17 @@ #endif {-# INLINE primPext64 #-} -primPext32 :: Word32 -> Word32 -> Word32 +-- | Parallel extract bits for 'Word32' +-- +-- Copies selected bits from 'src' to contiguous low-order bits of the return value; +-- higher-order return value bits are cleared. +-- +-- >>> primPext32 1 1 +-- 1 +primPext32 + :: Word32 -- ^ word from which bits will be extracted + -> Word32 -- ^ bitmap selecting the bits that are to be extracted + -> Word32 -- ^ word containing the extracted bits #if MIN_VERSION_base(4,11,0) && defined(BMI2_ENABLED) primPext32 (W32# src#) (W32# mask#) = W32# (pext32# src# mask#) #else @@ -38,15 +69,35 @@ #endif {-# INLINE primPext32 #-} -primPext16 :: Word16 -> Word16 -> Word16 +-- | Parallel extract bits for 'Word16' +-- +-- Copies selected bits from 'src' to contiguous low-order bits of the return value; +-- higher-order return value bits are cleared. +-- +-- >>> primPext16 1 1 +-- 1 +primPext16 + :: Word16 -- ^ word from which bits will be extracted + -> Word16 -- ^ bitmap selecting the bits that are to be extracted + -> Word16 -- ^ word containing the extracted bits primPext16 src mask = fromIntegral (primPext32 (fromIntegral src) (fromIntegral mask)) {-# INLINE primPext16 #-} -primPext8 :: Word8 -> Word8 -> Word8 +-- | Parallel extract bits for 'Word8' +-- +-- Copies selected bits from 'src' to contiguous low-order bits of the return value; +-- higher-order return value bits are cleared. +-- +-- >>> primPext8 1 1 +-- 1 +primPext8 + :: Word8 -- ^ word from which bits will be extracted + -> Word8 -- ^ bitmap selecting the bits that are to be extracted + -> Word8 -- ^ word containing the extracted bits primPext8 src mask = fromIntegral (primPext32 (fromIntegral src) (fromIntegral mask)) {-# INLINE primPext8 #-} --- | Runtime flag indicating whether the 'pext' function is using the high-performance. +-- | Runtime flag indicating whether the 'pext' function is using the high-performance -- BMI2 instruction set. A value of `False` indicates that `pext` is emulated. fastPextEnabled :: Bool #if MIN_VERSION_base(4,11,0) && defined(BMI2_ENABLED) diff --git a/src/Data/Bits/Pext/Slow.hs b/src/Data/Bits/Pext/Slow.hs --- a/src/Data/Bits/Pext/Slow.hs +++ b/src/Data/Bits/Pext/Slow.hs @@ -1,3 +1,11 @@ +{-| +Module : Data.Bits.Pext.Prim +Description : Parallel extract operations (emulated) +Copyright : (c) John Ky, 2018-2019 +License : BSD-3-Clause +Maintainer : newhoggy@gmail.com +Stability : stable +-} module Data.Bits.Pext.Slow ( SlowPext(..) ) where @@ -5,7 +13,10 @@ import Data.Bits import GHC.Word -slowPext64 :: Word64 -> Word64 -> Word64 +slowPext64 + :: Word64 -- ^ the bitmap from which bits will be extracted + -> Word64 -- ^ the bitmap selecting the bits that are to be extracted + -> Word64 -- ^ the bitmap containing the extract bits with higher-order bits cleared slowPext64 = slowPext64' 0 0 0 slowPext64' :: Word64 -> Int -> Int -> Word64 -> Word64 -> Word64 @@ -21,7 +32,10 @@ -- | Bitwise parallel extract (emulated). Extract bits from the source at -- the locations described by the mask. class SlowPext a where - slowPext :: a -> a -> a + slowPext + :: a -- ^ the bitmap from which bits will be extracted + -> a -- ^ the bitmap selecting the bits that are to be extracted + -> a -- ^ the bitmap containing the extract bits with higher-order bits cleared instance SlowPext Word where slowPext s m = fromIntegral (slowPext64 (fromIntegral s) (fromIntegral m))