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.

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).

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.

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

Since: 0.3.3.0

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