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.