Module

Data.Maybe

#Maybe

data Maybe a

The Maybe type is used to represent optional values and can be seen as something like a type-safe null, where Nothing is null and Just x is the non-null value x.

Constructors

Nothing
Just a

Instances

Functor Maybe
The Functor instance allows functions to transform the contents of a Just with the <$> operator:
```
f <$> Just x == Just (f x)
```
Nothing values are left untouched:
```
f <$> Nothing == Nothing
```
Apply Maybe
The Apply instance allows functions contained within a Just to transform a value contained within a Just using the apply operator:
```
Just f <*> Just x == Just (f x)
```
Nothing values are left untouched:
```
Just f <*> Nothing == Nothing
Nothing <*> Just x == Nothing
```
Combining Functor's <$> with Apply's <*> can be used transform a pure function to take Maybe-typed arguments so f :: a -> b -> c becomes f :: Maybe a -> Maybe b -> Maybe c:
```
f <$> Just x <*> Just y == Just (f x y)
```
The Nothing-preserving behaviour of both operators means the result of an expression like the above but where any one of the values is Nothing means the whole result becomes Nothing also:
```
f <$> Nothing <*> Just y == Nothing
f <$> Just x <*> Nothing == Nothing
f <$> Nothing <*> Nothing == Nothing
```
Applicative Maybe
The Applicative instance enables lifting of values into Maybe with the pure function:
```
pure x :: Maybe _ == Just x
```
Combining Functor's <$> with Apply's <*> and Applicative's pure can be used to pass a mixture of Maybe and non-Maybe typed values to a function that does not usually expect them, by using pure for any value that is not already Maybe typed:
```
f <$> Just x <*> pure y == Just (f x y)
```
Even though pure = Just it is recommended to use pure in situations like this as it allows the choice of Applicative to be changed later without having to go through and replace Just with a new constructor.
Alt Maybe
The Alt instance allows for a choice to be made between two Maybe values with the <|> operator, where the first Just encountered is taken.
```
Just x <|> Just y == Just x
Nothing <|> Just y == Just y
Nothing <|> Nothing == Nothing
```
Plus Maybe
The Plus instance provides a default Maybe value:
```
empty :: Maybe _ == Nothing
```
Alternative Maybe
The Alternative instance guarantees that there are both Applicative and Plus instances for Maybe.
Bind Maybe
The Bind instance allows sequencing of Maybe values and functions that return a Maybe by using the >>= operator:
```
Just x >>= f = f x
Nothing >>= f = Nothing
```

Monad Maybe

The Monad instance guarantees that there are both Applicative and Bind instances for Maybe. This also enables the do syntactic sugar:

do
  x' <- x
  y' <- y
  pure (f x' y')

Which is equivalent to:

x >>= (\x' -> y >>= (\y' -> pure (f x' y')))

Which is equivalent to:

case x of
  Nothing -> Nothing
  Just x' -> case y of
    Nothing -> Nothing
    Just y' -> Just (f x' y')

Extend Maybe
The Extend instance allows sequencing of Maybe values and functions that accept a Maybe a and return a non-Maybe result using the <<= operator.
```
f <<= Nothing = Nothing
f <<= x = Just (f x)
```
Invariant Maybe
(Semigroup a) => Semigroup (Maybe a)
The Semigroup instance enables use of the operator <> on Maybe values whenever there is a Semigroup instance for the type the Maybe contains. The exact behaviour of <> depends on the "inner" Semigroup instance, but generally captures the notion of appending or combining things.
```
Just x <> Just y = Just (x <> y)
Just x <> Nothing = Just x
Nothing <> Just y = Just y
Nothing <> Nothing = Nothing
```
(Semigroup a) => Monoid (Maybe a)
(Semiring a) => Semiring (Maybe a)
(Eq a) => Eq (Maybe a)
The Eq instance allows Maybe values to be checked for equality with == and inequality with /= whenever there is an Eq instance for the type the Maybe contains.
Eq1 Maybe
(Ord a) => Ord (Maybe a)
The Ord instance allows Maybe values to be compared with compare, >, >=, < and <= whenever there is an Ord instance for the type the Maybe contains.

Nothing is considered to be less than any Just value.
Ord1 Maybe
(Bounded a) => Bounded (Maybe a)
(Show a) => Show (Maybe a)
The Show instance allows Maybe values to be rendered as a string with show whenever there is an Show instance for the type the Maybe contains.
Generic (Maybe a) _

#maybe

maybe :: forall a b. b -> (a -> b) -> Maybe a -> b

Takes a default value, a function, and a Maybe value. If the Maybe value is Nothing the default value is returned, otherwise the function is applied to the value inside the Just and the result is returned.

maybe x f Nothing == x
maybe x f (Just y) == f y

#maybe'

maybe' :: forall a b. (Unit -> b) -> (a -> b) -> Maybe a -> b

Similar to maybe but for use in cases where the default value may be expensive to compute. As PureScript is not lazy, the standard maybe has to evaluate the default value before returning the result, whereas here the value is only computed when the Maybe is known to be Nothing.

maybe' (\_ -> x) f Nothing == x
maybe' (\_ -> x) f (Just y) == f y

#fromMaybe

fromMaybe :: forall a. a -> Maybe a -> a

Takes a default value, and a Maybe value. If the Maybe value is Nothing the default value is returned, otherwise the value inside the Just is returned.

fromMaybe x Nothing == x
fromMaybe x (Just y) == y

#fromMaybe'

fromMaybe' :: forall a. (Unit -> a) -> Maybe a -> a

Similar to fromMaybe but for use in cases where the default value may be expensive to compute. As PureScript is not lazy, the standard fromMaybe has to evaluate the default value before returning the result, whereas here the value is only computed when the Maybe is known to be Nothing.

fromMaybe' (\_ -> x) Nothing == x
fromMaybe' (\_ -> x) (Just y) == y

#isJust

isJust :: forall a. Maybe a -> Boolean

Returns true when the Maybe value was constructed with Just.

#isNothing

isNothing :: forall a. Maybe a -> Boolean

Returns true when the Maybe value is Nothing.

#fromJust

fromJust :: forall a. Partial => Maybe a -> a

A partial function that extracts the value from the Just data constructor. Passing Nothing to fromJust will throw an error at runtime.

#optional

optional :: forall f a. Alt f => Applicative f => f a -> f (Maybe a)

One or none.

optional empty = pure Nothing

The behaviour of optional (pure x) depends on whether the Alt instance satisfy the left catch law (pure a <|> b = pure a).

Either e does:

optional (Right x) = Right (Just x)

But Array does not:

optional [x] = [Just x, Nothing]