Data.Containers.NonEmpty

Non-Empty Typeclass

Provides the typeclass HasNonEmpty, which abstracts over different types which have a "non-empty" variant.

Used to convert between and in between possibly-empty and non-empty types. Instances are provided for all modules in this package, as well as for NonEmpty in base and NonEmptyVector.

Documentation

class HasNonEmpty s where

If s is an instance of HasNonEmpty, it means that there is a corresponding "non-empty" version of s, NE s.

In order for things to be well-behaved, we expect that nonEmpty and maybe empty fromNonEmpty should form an isomorphism (or that withNonEmpty empty fromNonEmpty == id. In addition, the following properties should hold for most exectations:

• (x == empty) ==> isEmpty x

• (x == empty) ==> isNothing (nonEmpty x)

• isEmpty x    ==> isNothing (nonEmpty x)

• unsafeToNonEmpty x == fromJust (nonEmpty x)

• Usually, not (isEmpty x) ==> isJust (nonEmpty x), but this isn't necessary.

Minimal complete definition

(nonEmpty | withNonEmpty), fromNonEmpty, empty

Associated Types

type NE s = t | t -> s

NE s is the "non-empty" version of s.

Methods

nonEmpty :: s -> Maybe (NE s)

"Smart constructor" for NE s given a (potentailly empty) s. Will return Nothing if the s was empty, and Just n if the s was not empty, with n :: NE s.

Should form an isomorphism with maybe empty fromNonEmpty.

fromNonEmpty :: NE s -> s

Convert a NE s (non-empty s) back into an s, "obscuring" its non-emptiness from its type.

withNonEmpty :: r -> (NE s -> r) -> s -> r

Continuation-based version of nonEmpty, which can be more efficient in certain situations.

withNonEmpty empty fromNonEmpty should be id.

empty :: s

An empty s.

isEmpty :: s -> Bool

Check if an s is empty.

unsafeToNonEmpty :: s -> NE s

Unsafely coerce an s into an NE s (non-empty s). Is undefined (throws a runtime exception when evaluation is attempted) when the s is empty.

Instances

HasNonEmpty IntSet

Defined in Data.Containers.NonEmpty

Associated Types

type NE IntSet = (t :: Type)

Methods

nonEmpty :: IntSet -> Maybe (NE IntSet)

fromNonEmpty :: NE IntSet -> IntSet

withNonEmpty :: r -> (NE IntSet -> r) -> IntSet -> r

empty :: IntSet

isEmpty :: IntSet -> Bool

unsafeToNonEmpty :: IntSet -> NE IntSet

HasNonEmpty [a]

Defined in Data.Containers.NonEmpty

Associated Types

type NE [a] = (t :: Type)

Methods

nonEmpty :: [a] -> Maybe (NE [a])

fromNonEmpty :: NE [a] -> [a]

withNonEmpty :: r -> (NE [a] -> r) -> [a] -> r

empty :: [a]

isEmpty :: [a] -> Bool

unsafeToNonEmpty :: [a] -> NE [a]

HasNonEmpty (IntMap a)

Defined in Data.Containers.NonEmpty

Associated Types

type NE (IntMap a) = (t :: Type)

Methods

nonEmpty :: IntMap a -> Maybe (NE (IntMap a))

fromNonEmpty :: NE (IntMap a) -> IntMap a

withNonEmpty :: r -> (NE (IntMap a) -> r) -> IntMap a -> r

empty :: IntMap a

isEmpty :: IntMap a -> Bool

unsafeToNonEmpty :: IntMap a -> NE (IntMap a)

HasNonEmpty (Seq a)

Defined in Data.Containers.NonEmpty

Associated Types

type NE (Seq a) = (t :: Type)

Methods

nonEmpty :: Seq a -> Maybe (NE (Seq a))

fromNonEmpty :: NE (Seq a) -> Seq a

withNonEmpty :: r -> (NE (Seq a) -> r) -> Seq a -> r

empty :: Seq a

isEmpty :: Seq a -> Bool

unsafeToNonEmpty :: Seq a -> NE (Seq a)

HasNonEmpty (Set a)

Defined in Data.Containers.NonEmpty

Associated Types

type NE (Set a) = (t :: Type)

Methods

nonEmpty :: Set a -> Maybe (NE (Set a))

fromNonEmpty :: NE (Set a) -> Set a

withNonEmpty :: r -> (NE (Set a) -> r) -> Set a -> r

empty :: Set a

isEmpty :: Set a -> Bool

unsafeToNonEmpty :: Set a -> NE (Set a)

HasNonEmpty (Vector a)

Defined in Data.Containers.NonEmpty

Associated Types

type NE (Vector a) = (t :: Type)

Methods

nonEmpty :: Vector a -> Maybe (NE (Vector a))

fromNonEmpty :: NE (Vector a) -> Vector a

withNonEmpty :: r -> (NE (Vector a) -> r) -> Vector a -> r

empty :: Vector a

isEmpty :: Vector a -> Bool

unsafeToNonEmpty :: Vector a -> NE (Vector a)

HasNonEmpty (Map k a)

Defined in Data.Containers.NonEmpty

Associated Types

type NE (Map k a) = (t :: Type)

Methods

nonEmpty :: Map k a -> Maybe (NE (Map k a))

fromNonEmpty :: NE (Map k a) -> Map k a

withNonEmpty :: r -> (NE (Map k a) -> r) -> Map k a -> r

empty :: Map k a

isEmpty :: Map k a -> Bool

unsafeToNonEmpty :: Map k a -> NE (Map k a)

pattern IsNonEmpty :: HasNonEmpty s => NE s -> s

The IsNonEmpty and IsEmpty patterns allow you to treat a s as if it were either a IsNonEmpty n (where n is a non-empty version of s, type NE s) or an IsEmpty.

For example, you can pattern match on a list to get a NonEmpty (non-empty list):

safeHead :: [Int] -> Int
safeHead (IsNonEmpty (x :| _)) = x     -- here, the list was not empty
safehead IsEmpty               = 0     -- here, the list was empty

Matching on IsNonEmpty n means that the original input was not empty, and you have a verified-non-empty n :: NE s to use.

Note that because of the way coverage checking works for polymorphic pattern synonyms, you will unfortunatelly still get incomplete pattern match warnings if you match on both IsNonEmpty and NonEmpty, even though the two are meant to provide complete coverage. However, many instances of HasNonEmpty (like NEMap, NEIntMap, NESet, NEIntSet) will provide their own monomorphic versions of these patterns that can be verified as complete covers by GHC.

This is a bidirectional pattern, so you can use IsNonEmpty to convert a NE s back into an s, "obscuring" its non-emptiness (see fromNonEmpty).

pattern IsEmpty :: HasNonEmpty s => s

The IsNonEmpty and IsEmpty patterns allow you to treat a s as if it were either a IsNonEmpty n (where n is a non-empty version of s, type NE s) or an IsEmpty.

Matching on IsEmpty means that the original item was empty.

This is a bidirectional pattern, so you can use IsEmpty as an expression, and it will be interpreted as empty.

Note that because of the way coverage checking works for polymorphic pattern synonyms, you will unfortunatelly still get incomplete pattern match warnings if you match on both IsNonEmpty and NonEmpty, even though the two are meant to provide complete coverage. However, many instances of HasNonEmpty (like NEMap, NEIntMap, NESet, NEIntSet) will provide their own monomorphic versions of these patterns that can be verified as complete covers by GHC.

See IsNonEmpty for more information.

overNonEmpty :: (HasNonEmpty s, HasNonEmpty t) => (NE s -> NE t) -> s -> t

Useful function for mapping over the "non-empty" representation of a type.

Since: 0.3.3.0

onNonEmpty :: HasNonEmpty s => (NE s -> r) -> s -> Maybe r

Useful function for applying a function on the "non-empty" representation of a type.

If you want a continuation taking NE s -> 'Maybe r', you can use withNonEmpty Nothing.

Since: 0.3.3.0