isJust (Just 42)
--> True


isJust (Just [])
--> True


isJust Nothing
--> False

isNothing (Just 42)
--> False


isNothing (Just [])
--> False


isNothing Nothing
--> True

Flattens nested Maybes

join (Just (Just 1))
--> Just 1


join (Just Nothing)
--> Nothing


join Nothing
--> Nothing

Keep the Maybe only if the predicate function passes

filter (\v -> v == 1) (Just 1)
--> Just 1


filter (\v -> v == 2) (Just 1)
--> Nothing


filter (\v -> v == 1) Nothing
--> Nothing

Like using a case. Give a function that says what to do if the input is Just, and a value to use if the input is Nothing.

These are all equivalent:

unwrap default f maybeX


maybeX
    |> Maybe.map f
    |> Maybe.withDefault default


case maybeX of
    Just x ->
        f x


    Nothing ->
        default

Except that unlike a case, the default value for unwrap is always computed. If your default value is expensive to compute, use the lazy unpack instead.

Examples:

unwrap 0 String.length Nothing
--> 0


unwrap 0 String.length (Just "abc")
--> 3

Like unwrap, but the default value is lazy, and will only be computed if the Maybe is Nothing.

unpack (\() -> 0) String.length Nothing
--> 0


unpack (\() -> 0) String.length (Just "abc")
--> 3

unpack (\() -> default) f maybeX is equivalent to

case maybeX of
    Just x ->
        f x


    Nothing ->
        default

Returns the first value that is present, like the boolean ||.

Both values will be computed. There is no short-circuiting. If your second argument is expensive to calculate and you need short circuiting, use orLazy instead.

or (Just 4) (Just 5)
--> Just 4


or (Just 4) Nothing
--> Just 4


or Nothing (Just 5)
--> Just 5


or Nothing Nothing
--> Nothing

Advanced functional programmers will recognize this as the implementation of mplus for Maybes from the MonadPlus type class.

Piping-friendly version of or.

Just 5
    |> orElse (Just 4)
--> Just 5


orElse (Just 4) (Just 5)
--> Just 5


List.head []
    |> orElse (List.head [ 4 ])
--> Just 4

Returns the first value that is present.

All values will be computed. If your arguments are expensive to calculate, use orListLazy instead.

orList
    [ Nothing
    , Just 1
    , Just 2
    ]
--> Just 1


orList
    [ List.head []
    , String.toInt ""
    ]
--> Nothing


orList []
--> Nothing

Lazy version of or.

The second argument will only be evaluated if the first argument is Nothing.

orLazy (Just 4) (\() -> Debug.todo "Expensive calculation")
--> Just 4

Lazy version of orElse. Piping-friendly version of orLazy.

The first argument will only be evaluated if the second argument is Nothing.

Just 4
    |> orElseLazy (\() -> Debug.todo "Expensive calculation")
--> Just 4

Lazy version of orList

Stops calculating new values after the first match

orListLazy
    [ \() -> Nothing
    , \() -> Just 1
    , \() -> Debug.todo "Expensive calculation"
    ]
--> Just 1

Try a list of functions against a value. Return the value of the first call that succeeds (returns Just).

type UserInput
    = FloatInput Float
    | IntInput Int
    | UnknownInput


"5.6"
    |> oneOf
        [ String.toInt >> Maybe.map IntInput
        , String.toFloat >> Maybe.map FloatInput
        ]
    |> Maybe.withDefault UnknownInput
--> FloatInput 5.6

Take all the values that are present, throwing away any Nothings.

Equivalent to List.filterMap identity.

values [ Just 1, Nothing, Just 2 ]
--> [ 1, 2 ]

If every Maybe in the list is present, return all of the values unwrapped. If there are any Nothings, the whole function fails and returns Nothing.

combine []
--> Just []


combine [ Just 1, Just 2, Just 3 ]
--> Just [ 1, 2, 3 ]


combine [ Just 1, Nothing, Just 3 ]
--> Nothing

Like combine, but map a function over each element of the list first.

If every function call succeeds (returns Just), traverse will return a list. If any function call fails (returns Nothing), traverse will return Nothing.

combine is equivalent to traverse identity.

traverse (\x -> Just (x * 10)) [ 1, 2, 3, 4, 5 ]
--> Just [ 10, 20, 30, 40, 50 ]


traverse List.head [ [1], [2, 3], [] ]
--> Nothing

Like combine, but works on Array instead of List.

Like traverse, but works on Array instead of List.

A Maybe is a lot like a list that can only be length 0 or 1.

Returns a singleton list if the value is present, and an empty list it's missing.

toList Nothing
--> []


toList (Just 1)
--> [ 1 ]

Like toList, but returns a singleton or empty Array.

import Array


toArray Nothing
--> Array.fromList []


toArray (Just 1)
--> Array.fromList [ 1 ]

Add an item to a list only if it's a Just.

cons (Just 1) [ 2, 3 ]
--> [ 1, 2, 3 ]


cons Nothing [2, 3 ]
--> [ 2, 3 ]

import Array exposing (Array)


array : Array Int
array = Array.fromList [1,2,3]


andThen2 Array.get (Just 1) (Just array)
--> Just 2


andThen2 Array.get Nothing (Just array)
--> Nothing


andThen2 Array.get (Just 1) Nothing
--> Nothing


andThen2 Array.get (Just 4) (Just array)
--> Nothing

If both a function and a value are present, apply the function to the value. If either argument is Nothing, return Nothing.

Just ((+) 2)
    |> andMap (Just 3)
--> Just 5


Nothing
    |> andMap (Just 3)
--> Nothing


Just ((+) 2)
    |> andMap Nothing
--> Nothing

This can be used to do Maybe.mapN or andThenN for any number of arguments.

-- map4
Just (\a b c d -> a + b + c + d )
    |> andMap (Just 1)
    |> andMap (Just 2)
    |> andMap (Just 4)
    |> andMap (Just 8)
--> Just 15


-- andThen4
Just (\a b c d -> Just (a + b + c + d ))
    |> andMap (Just 1)
    |> andMap (Just 2)
    |> andMap (Just 4)
    |> andMap (Just 8)
    |> join
--> Just 15

Advanced functional programmers will recognize this as the implementation of <*> for Maybes from the Applicative typeclass.

Take two Maybe values. If the first one equals Nothing, return Nothing. Otherwise return the second value.

next (Just 1) (Just 2)
--> Just 2


next Nothing (Just 2)
--> Nothing


next (Just 1) Nothing
--> Nothing

Advanced functional programmers will recognize this as the implementation of *> for Maybes from the Applicative typeclass.

Take two Maybe values. If the second one equals Nothing, return Nothing. Otherwise return the first value.

prev (Just 1) (Just 2)
--> Just 1


prev Nothing (Just 2)
--> Nothing


prev (Just 1) Nothing
--> Nothing

Advanced functional programmers will recognize this as the implementation of <* for Maybes from the Applicative typeclass.