finitary: A better, more type-safe Enum.

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 type class witnessing that a type has finitely-many inhabitants, as well as its cardinality. Also provides an auto-deriving framework using GHC Generics, together with a range of instances for existing types.


[Skip to Readme]

Properties

Versions 0.1.0.0, 1.0.0.0, 1.0.0.1, 1.1.0.0, 1.1.0.1, 1.2.0.0, 1.2.0.0, 2.0.0.0, 2.1.0.1, 2.1.1.0, 2.1.1.1
Change log CHANGELOG.md
Dependencies base (>=4.10 && <4.14), bitvec (>=1.0.0.1 && <1.2.0.0), coercible-utils (>=0.0.0 && <1.0.0), finite-typelits (>=0.1.4.2 && <0.2.0.0), ghc-typelits-knownnat (>=0.7 && <0.8), ghc-typelits-natnormalise (>=0.7 && <0.8), primitive (>=0.6.4.0 && <0.8.0.0), template-haskell (>=2.12.0.0 && <2.16.0.0), typelits-witnesses (>=0.4.0.0 && <0.5.0.0), 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
Bug tracker https://notabug.org/koz/ross/finitary/issues
Source repo head: git clone git://notabug.org/koz.ross/finitary.git
Uploaded by koz_ross at 2019-10-17T06:07:59Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for finitary-1.2.0.0

[back to package description]

finitary

What's all this about?

finitary allows us to specify that a type is finite (that is, contains finitely many inhabitants which are not _|_), and have confirmation of this fact by GHC. Additionally, it offers a Generics-based auto-derivation interface for this, as well as multiple helper functions that are enabled by all this machinery.

Why is this a big deal?

Consider Enum. It's not difficult to see that Enum has issues:

It's partial all over the place

What will this code do?

toEnum 3 :: Bool

The answer is 'a runtime error'. How about this?

succ True

The answer, again, is 'a runtime error'. Many of the methods provided by Enum are partial like this, because many types that happen to be Enum instances have cardinalities (much) smaller than Int, which necessitates leaving some Int values 'out'.

The converse is not much better: on some platforms, Int has smaller cardinality than some types with Enum instances in base. For example, on a platform where Int is 32 bits wide, the Word64 instance will definitely cause problems, as it's 'too big'.

It gives us almost no information

An Enum instance says that a type can be munged to and from an Int... somehow. While base and the Haskell Report certainly provide some limits on its behaviour, a lot of questions remain unanswered, including:

We don't have a (default) way to auto-derive it

Quoting base:

Instances of Enum may be derived for any enumeration type (types whose constructors have no fields).

But what if your type has fields, especially when they're instances of Enum? Unfortunately, no auto-derivation for you. While this stance makes some sense, it's still rather inconvenient.

OK, so what are you offering instead?

The core of finitary is the Finitary type class. If we have an instance of Finitary for some type a, we have a witness to an isomorphism between a and some (KnownNat n) => Finite n. More precisely, we (together with GHC) know:

How does Finitary solve the issues behind Enum?

Everything is total, forever

There is no way to call fromFinite or toFinite with an 'inappropriate' argument. We always know - if you give me a Finite n, I will give you back a (unique) a, guaranteed.

We learn a lot from a type having a Finitary instance

Aside from cardinality, we also inherently get the ability to:

All of this is safe, total and can be relied upon. Check out the documentation for more details - all of this functionality is provided. We also have functions to help enumerate values of Finitary types.

But what about auto-derivation?

We have you covered. If you want to auto-derive an instance of Finitary for your type, you absolutely can, using the power of GHC.Generics:

{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE TypeInType #-}

import GHC.Generics
import GHC.TypeNats
import Data.Word

import qualified Data.Vector.Sized as VS

data Foo = Bar | Baz (Word8, Word8) | Quux (VS.Vector 4 Bool)
  deriving (Eq, Generic, Finitary) 

Furthermore, GHC will even calculate the cardinality for you. To assist in this, we have provided as many instances of Finitary for 'base' types as possible - see the documentation for full details.

That all seems rather cool - what else can I do with this?

Knowing that a type has finite cardinality is usable for many things - all of which we plan to provide. Some examples (with links once we have working, tested code) include:

If there's something else interesting you think can be done with this, let us know: it might make it onto this list, and into code.

What will this work on?

Currently, we have tested finitary (meaning 'run tests, not just compiled') on GHCs 8.2.2, 8.4.4, 8.6.5 and 8.8.1. If you would like any additional versions supported, please let us know.

So far, the tests have all been on x86_64 GNU/Linux. If you have results on other platforms or architectures, please let us know too!

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.