diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ -# Revision history for primitive-element +# Revision history for primitive-offset -## 0.1.0.0 -- YYYY-mm-dd +## 0.2.0.1 -- 2024-03-05 -* First version. Released on an unsuspecting world. +* Update package metadata. + +## 0.2.0.0 -- 2019-05-30 + +## 0.1.0.0 -- 2019-05-15 + +* First version. diff --git a/Setup.hs b/Setup.hs deleted file mode 100644 --- a/Setup.hs +++ /dev/null @@ -1,2 +0,0 @@ -import Distribution.Simple -main = defaultMain diff --git a/primitive-offset.cabal b/primitive-offset.cabal --- a/primitive-offset.cabal +++ b/primitive-offset.cabal @@ -1,28 +1,38 @@ -cabal-version: 2.2 -name: primitive-offset -version: 0.2.0.0 -synopsis: Types for offsets into unboxed arrays +cabal-version: 3.0 +name: primitive-offset +version: 0.2.0.1 +synopsis: Types for offsets into unboxed arrays description: Pair a typed or untyped primitive array with an offset. This is useful for providing meaningful type signatures when working with the foreign function interface. -homepage: https://github.com/andrewthad/primitive-offset -bug-reports: https://github.com/andrewthad/primitive-offset/issues -license: BSD-3-Clause -license-file: LICENSE -author: Andrew Martin -maintainer: andrew.thaddeus@gmail.com -copyright: 2019 Andrew Martin -category: Data -extra-source-files: CHANGELOG.md +homepage: https://github.com/byteverse/primitive-offset +bug-reports: https://github.com/byteverse/primitive-offset/issues +license: BSD-3-Clause +license-file: LICENSE +author: Andrew Martin +maintainer: amartin@layer3com.com +copyright: 2019 Andrew Martin +category: Data +extra-doc-files: CHANGELOG.md +tested-with: GHC ==9.4.8 || ==9.6.3 || ==9.8.1 + +common build-settings + default-language: Haskell2010 + ghc-options: -Wall -Wunused-packages + build-depends: base >=4.11.1.0 && <5 + library + import: build-settings + hs-source-dirs: src + ghc-options: -O2 exposed-modules: - Data.Primitive.PrimArray.Offset Data.Primitive.ByteArray.Offset - build-depends: - , base >=4.11.1.0 && <5 - , primitive >= 0.6.4 - hs-source-dirs: src - default-language: Haskell2010 - ghc-options: -O2 -Wall + Data.Primitive.PrimArray.Offset + + build-depends: primitive >=0.6.4 + +source-repository head + type: git + location: git://github.com/byteverse/primitive-offset.git diff --git a/src/Data/Primitive/ByteArray/Offset.hs b/src/Data/Primitive/ByteArray/Offset.hs --- a/src/Data/Primitive/ByteArray/Offset.hs +++ b/src/Data/Primitive/ByteArray/Offset.hs @@ -1,21 +1,24 @@ -{-# language DuplicateRecordFields #-} +{-# LANGUAGE DuplicateRecordFields #-} + module Data.Primitive.ByteArray.Offset ( -- * Types - ByteArrayOffset(..) - , MutableByteArrayOffset(..) + ByteArrayOffset (..) + , MutableByteArrayOffset (..) ) where -import Data.Primitive (ByteArray,MutableByteArray) +import Data.Primitive (ByteArray, MutableByteArray) --- | A byte array and an index into the array. The element --- type is understood to be byte (an 8-bit word). +{- | A byte array and an index into the array. The element +type is understood to be byte (an 8-bit word). +-} data ByteArrayOffset = ByteArrayOffset { array :: {-# UNPACK #-} !ByteArray , offset :: {-# UNPACK #-} !Int } --- | A mutable byte array and an index into the array. The element --- type is understood to be byte (an 8-bit word). +{- | A mutable byte array and an index into the array. The element +type is understood to be byte (an 8-bit word). +-} data MutableByteArrayOffset s = MutableByteArrayOffset { array :: {-# UNPACK #-} !(MutableByteArray s) , offset :: {-# UNPACK #-} !Int diff --git a/src/Data/Primitive/PrimArray/Offset.hs b/src/Data/Primitive/PrimArray/Offset.hs --- a/src/Data/Primitive/PrimArray/Offset.hs +++ b/src/Data/Primitive/PrimArray/Offset.hs @@ -1,42 +1,43 @@ -{-# language DuplicateRecordFields #-} +{-# LANGUAGE DuplicateRecordFields #-} --- | Data types for describing an array paired with an index --- into it. This is intended to be used in wrappers for @unsafe@ --- FFI calls. For example, the POSIX function @recvfrom@ takes --- a @socklen_t*@ argument. (Let us assume that @socklen_t@ --- is equivalant to @int@ for this example.) How is this argument best --- described by a Haskell type? When working with pinned memory, --- the best option @'Ptr' 'CInt'@. --- It works equally well regardless of whether we originally had an --- array of 'CInt' or a pointer to a single 'CInt'. This works because --- of functions like 'Data.Primitive.advancePtr' and --- 'Foreign.Ptr.plusPtr' that effectively index into an array. --- Unpinned memory, however, is trickier. We want to have the full --- flexibility (handling both a single-element or --- multi-element buffer) that @'Ptr' 'CInt'@ affords. We cannot --- offset into a 'MutablePrimArray' to get a new one like we --- could with 'Ptr'. (Such a function is not possible because --- unpinned memory can be relocated.) So, the offseting must --- be done in the C function wrapped by the @unsafe@ FFI. This --- means that the offset must be passed together with the --- 'MutablePrimArray'. This is the precisely the product that --- 'MutablePrimArrayOffset' represents. In a type signature, it --- provides additional clarity about the meaning of the offset. --- --- This library is used in the extensively in the @posix-api@ --- library to clarify intent in a number of type signatures. +{- | Data types for describing an array paired with an index +into it. This is intended to be used in wrappers for @unsafe@ +FFI calls. For example, the POSIX function @recvfrom@ takes +a @socklen_t*@ argument. (Let us assume that @socklen_t@ +is equivalant to @int@ for this example.) How is this argument best +described by a Haskell type? When working with pinned memory, +the best option @'Ptr' 'CInt'@. +It works equally well regardless of whether we originally had an +array of 'CInt' or a pointer to a single 'CInt'. This works because +of functions like 'Data.Primitive.advancePtr' and +'Foreign.Ptr.plusPtr' that effectively index into an array. +Unpinned memory, however, is trickier. We want to have the full +flexibility (handling both a single-element or +multi-element buffer) that @'Ptr' 'CInt'@ affords. We cannot +offset into a 'MutablePrimArray' to get a new one like we +could with 'Ptr'. (Such a function is not possible because +unpinned memory can be relocated.) So, the offseting must +be done in the C function wrapped by the @unsafe@ FFI. This +means that the offset must be passed together with the +'MutablePrimArray'. This is the precisely the product that +'MutablePrimArrayOffset' represents. In a type signature, it +provides additional clarity about the meaning of the offset. + +This library is used in the extensively in the @posix-api@ +library to clarify intent in a number of type signatures. +-} module Data.Primitive.PrimArray.Offset ( -- * Types - PrimArrayOffset(..) - , MutablePrimArrayOffset(..) + PrimArrayOffset (..) + , MutablePrimArrayOffset (..) + -- * Resolution , indexOffset , readOffset ) where -import Control.Monad.Primitive (PrimMonad,PrimState) -import Data.Primitive (Prim,PrimArray,MutablePrimArray) -import Data.Primitive (indexPrimArray,readPrimArray) +import Control.Monad.Primitive (PrimMonad, PrimState) +import Data.Primitive (MutablePrimArray, Prim, PrimArray, indexPrimArray, readPrimArray) -- | A primitive array and an index into the array. data PrimArrayOffset a = PrimArrayOffset @@ -51,15 +52,17 @@ } -- | Recover the element in the primitive array. -indexOffset :: Prim a - => PrimArrayOffset a - -> a -{-# inline indexOffset #-} +indexOffset :: + (Prim a) => + PrimArrayOffset a -> + a +{-# INLINE indexOffset #-} indexOffset (PrimArrayOffset arr ix) = indexPrimArray arr ix -- | Recover the element in the mutable primitive array. -readOffset :: (PrimMonad m, Prim a) - => MutablePrimArrayOffset (PrimState m) a - -> m a -{-# inline readOffset #-} +readOffset :: + (PrimMonad m, Prim a) => + MutablePrimArrayOffset (PrimState m) a -> + m a +{-# INLINE readOffset #-} readOffset (MutablePrimArrayOffset arr ix) = readPrimArray arr ix