diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..f6c0b22 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +@byteverse/l3c diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 0000000..00fbdfb --- /dev/null +++ b/.github/workflows/build.yaml @@ -0,0 +1,11 @@ +name: build +on: + pull_request: + branches: + - "*" + +jobs: + call-workflow: + uses: byteverse/.github/.github/workflows/build-matrix.yaml@main + with: + cabal-file: primitive-offset.cabal diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 0000000..9411962 --- /dev/null +++ b/.github/workflows/release.yaml @@ -0,0 +1,10 @@ +name: release +on: + push: + tags: + - "*" + +jobs: + call-workflow: + uses: byteverse/.github/.github/workflows/release.yaml@main + secrets: inherit diff --git a/.gitignore b/.gitignore index 28d589b..cde1485 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.vscode/ dist dist-* cabal-dev diff --git a/CHANGELOG.md b/CHANGELOG.md index 52df48a..627884b 100644 --- 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 index 9a994af..0000000 --- a/Setup.hs +++ /dev/null @@ -1,2 +0,0 @@ -import Distribution.Simple -main = defaultMain diff --git a/fourmolu.yaml b/fourmolu.yaml new file mode 100644 index 0000000..40cd005 --- /dev/null +++ b/fourmolu.yaml @@ -0,0 +1,51 @@ +# Number of spaces per indentation step +indentation: 2 + +# Max line length for automatic line breaking +column-limit: 200 + +# Styling of arrows in type signatures (choices: trailing, leading, or leading-args) +function-arrows: trailing + +# How to place commas in multi-line lists, records, etc. (choices: leading or trailing) +comma-style: leading + +# Styling of import/export lists (choices: leading, trailing, or diff-friendly) +import-export-style: leading + +# Whether to full-indent or half-indent 'where' bindings past the preceding body +indent-wheres: false + +# Whether to leave a space before an opening record brace +record-brace-space: true + +# Number of spaces between top-level declarations +newlines-between-decls: 1 + +# How to print Haddock comments (choices: single-line, multi-line, or multi-line-compact) +haddock-style: multi-line + +# How to print module docstring +haddock-style-module: null + +# Styling of let blocks (choices: auto, inline, newline, or mixed) +let-style: auto + +# How to align the 'in' keyword with respect to the 'let' keyword (choices: left-align, right-align, or no-space) +in-style: right-align + +# Whether to put parentheses around a single constraint (choices: auto, always, or never) +single-constraint-parens: always + +# Output Unicode syntax (choices: detect, always, or never) +unicode: never + +# Give the programmer more choice on where to insert blank lines +respectful: true + +# Fixity information for operators +fixities: [] + +# Module reexports Fourmolu should know about +reexports: [] + diff --git a/primitive-offset.cabal b/primitive-offset.cabal index 13cf4e1..69c4bbc 100644 --- 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 index 89007f8..18206a4 100644 --- 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 index bd87daf..3b825c0 100644 --- 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 @@ data MutablePrimArrayOffset s a = MutablePrimArrayOffset } -- | 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