Hackage :: [Package]

finitary-derive: Easy and efficient Unbox, Storable, Binary and Hashable instances for Finitary types.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

Provides a wrapper with pre-made instances of Unbox, Storable, Binary and Hashable, suitable for use with types that have Finitary instances. Never write Unbox by hand again!

[Skip to Readme]

Properties

Versions 1.0.0.0, 1.0.0.1, 1.0.0.1, 2.0.0.0, 2.1.0.0, 2.2.0.0, 2.2.0.1, 3.0.0.1
Change log CHANGELOG.md
Dependencies base (>=4.11 && <4.14), binary (>=0.8.5.1 && <0.9.0.0), coercible-utils (>=0.0.0 && <0.1.0), deepseq (>=1.4.3.0 && <1.5.0.0), finitary (>=1.1.0.0 && <1.2.0.0), finite-typelits (>=0.1.4.2 && <0.2.0.0), ghc-typelits-extra (>=0.3.1 && <0.4.0), ghc-typelits-knownnat (>=0.7 && <0.8), hashable (>=1.3.0.0 && <1.4.0.0), mtl (>=2.2.2 && <2.3), vector (>=0.12.0.3 && <0.13.0.0), vector-sized (>=1.4.0.0 && <1.5.0.0) [details]
License GPL-3.0-or-later
Copyright (C) Koz Ross 2019
Author Koz Ross
Maintainer koz.ross@retro-freedom.nz
Category Data
Home page https://notabug.org/koz.ross/finitary-derive
Uploaded by koz_ross at 2019-09-21T06:19:30Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for finitary-derive-1.0.0.1

[back to package description]

finitary-derive

What's this all about, then?

Have you ever written an Unbox instance for a user-defined type? I hope not, because it's a uniquely tedious chore. If your type is more complex, this can be difficult, fiddly, and frustrating. Storable is not much better. This is the kind of 'work' that we as Haskellers ought not to put up with.

Now, you don't have to! As long as your type is Finitary, you can now get Unbox and Storable (as well as Binary and Hashable, because we could) instances almost automagically:

{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE DerivingVia #-}

import Data.Finitary
import Data.Finitary.Pack
import Data.Word
import Data.Hashable

import qualified Data.Vector.Unboxed as VU

data Foo = Bar | Baz (Word8, Word8) | Quux Word16
  deriving (Eq, Generic, Finitary)
  deriving (Storable, Binary, Hashable) via (Pack Foo)

someVector :: VU.Vector (Pack Foo)
someVector = VU.fromList . fmap Pack $ [Bar, Baz 0x0 0xf, Quux 0x134]

If you don't have access to DerivingVia, you can still get the benefits of this library -- just use Pack a instead of a in all cases where you need any such instances. As it is a newtype, you can coerce through it if you care about efficiency.

Why can't I automagic up Unbox too?

The short answer is 'role restrictions on unboxed vectors'. If you want a more detailed explanation, check out the GHC wiki on roles, as well as the implementation of Data.Vector.Unboxed. You might also want to check out stuff about data families, as it ties into this rather aggravating limitation closely too.

Sounds good! Can I use it?

Certainly - we've tested on GHC 8.4.4, 8.6.5 and 8.8.1, on GNU/Linux only. If you would like support for any additional GHC versions, let us know. Unfortunately, while the library will build on 8.4.4, due to hedgehog-classes being limited to 8.6+, tests cannot be run on this version.

If you build and use this library successfully on any other platforms, we'd like to know too - it'd be beneficial even if nothing breaks, and especially if something does.

License

This library is under the GNU General Public License, version 3 or later (SPDX code GPL-3.0-or-later). For more details, see the LICENSE.md file.