unboxing-vector
A newtype-friendly variant of unboxed vectors
https://github.com/minoki/unboxing-vector#readme
LTS Haskell 22.33: | 0.2.0.0 |
Stackage Nightly 2024-09-07: | 0.2.0.0 |
Latest on Hackage: | 0.2.0.0 |
unboxing-vector-0.2.0.0@sha256:a8f8ddab08d16cd4051fb1febb06aaaa54d211b50001664c06282cfdcb97bab0,3768
Module documentation for 0.2.0.0
- Data
- Data.Vector
unboxing-vector: A newtype-friendly variant of unboxed vectors
This package provides newtype-friendly wrappers for Data.Vector.Unboxed
in vector
package.
Description
Suppose you define a newtype for Int
and want to store them in an unboxed vector.
import qualified Data.Vector.Unboxed as Unboxed
newtype Foo = Foo Int
vec :: Unboxed.Vector Foo
vec = Unboxed.generate 10 (\i -> Foo i)
With classic Data.Vector.Unboxed
, you either write two dozen of lines of code to get it work (the exact code is here), or resort to Template Haskell (vector-th-unbox
package) to generate it.
Now you have the third option, namely Data.Vector.Unboxing
.
With Data.Vector.Unboxing
, the amount of code you write is just two lines:
import qualified Data.Vector.Unboxing as Unboxing
instance Unboxing.Unboxable Foo where
type Rep Foo = Int
vec :: Unboxing.Vector Foo
vec = Unboxing.generate 10 (\i -> Foo i)
…and if you want to be even more concise, you can derive Unboxable
instance with GeneralizedNewtypeDeriving
.
Note that the vector type provided by this package (Data.Vector.Unboxing.Vector
) is different from Data.Vector.Unboxed.Vector
.
If you need to convert Unboxing.Vector
to Unboxed.Vector
, or vice versa, use Unboxing.toUnboxedVector
or Unboxing.fromUnboxedVector
.
The module defining the type Foo
does not need to export its constructor to enable use of Unboxing.Vector Foo
.
In that case, the users of the abstract data type cannot convert between Unboxing.Vector Int
and Unboxing.Vector Foo
— the abstraction is kept!
For non-newtypes
Suppose you define a data type isomorphic to a tuple, like:
data ComplexDouble = MkComplexDouble {-# UNPACK #-} !Double {-# UNPACK #-} !Double
In this example, ComplexDouble
is isomorphic to (Double, Double)
, but has a different representation. Thus, you cannot derive Unboxing.Unboxable
from (Double, Double)
.
For such cases, unboxing-vector provides a feature to derive Unboxable
using Generic
.
Use Unboxing.Generics
newtype wrapper to derive it.
{-# LANGUAGE DeriveGeneric, DerivingVia, UndecidableInstances #-}
data ComplexDouble = MkComplexDouble {-# UNPACK #-} !Double {-# UNPACK #-} !Double
deriving Generic
deriving Data.Vector.Unboxing.Unboxable via Data.Vector.Unboxing.Generics ComplexDouble
Unboxing via fromEnum
/toEnum
is also available.
Use Unboxing.Enum
or Unboxing.EnumRep
to derive it.
{-# LANGUAGE DerivingVia, UndecidableInstances #-}
data Direction = North | South | East | West
deriving Enum
deriving Unboxing.Unboxable via Unboxing.EnumRep Int8 Direction
Conversion
Conversion from/to Unboxed vector
You can use fromUnboxedVector
and toUnboxedVector
to convert one vector type to another.
import qualified Data.Vector.Unboxed as Unboxed
import qualified Data.Vector.Unboxing as Unboxing
convert :: Unboxed.Vector Int -> Unboxing.Vector Int
convert vec = Unboxing.fromUnboxedVector vec
Coercion between Unboxing vectors
You can use coerceVector
to convert vector types of different element types, if they have the same representation and have appropriate data constructors in scope.
import qualified Data.Vector.Unboxing as Unboxing
import Data.MonoTraversable (ofold)
import Data.Monoid (Sum(..), All, getAll)
sum :: Unboxing.Vector Int -> Int
sum vec = getSum $ ofold (Unboxing.coerceVector vec :: Unboxing.Vector (Sum Int)) -- OK
and :: Unboxing.Vector Bool -> Bool
and vec = getAll $ ofold (Unboxing.coerceVector vec :: Unboxing.Vector All) -- fails because the data constructor is not in scope
Supported GHC versions
The library itself is tested with GHC 8.0.2 or later.
To use GeneralizedNewtypeDeriving
on Unboxable
class, you need GHC 8.2 or later,
because GND for associated type families became available on that version.
DerivingVia
is avaliable since GHC 8.6.1.
This means that, defining an Unboxable
instance for user-defined data
types (like ComplexDouble
or Direction
in this document) requires a latest GHC.
If you want a way to make your data
types on older GHCs, please open an issue on GitHub.
Changes
Changelog for unboxing-vector
Version 0.2.0.0 (2020-09-27)
- Add coercion functions for mutable vectors.
- Add
Unboxable
instance for several mode types:Data.Semigroup.Arg
,Data.Monoid.Alt
,Data.Functor.Compose
. - The dependency on mono-traversable can be disabled via a package flag.
Version 0.1.1.0 (2019-07-01)
- Support older GHC versions.
- Add
Enum
andEnumRep
wrappers. - Add
Unboxable
instance forOrdering
.
Version 0.1.0.0 (2019-06-17)
Initial release with
- Data.Vector.Unboxing
- Data.Vector.Unboxing.Mutable