Copyright | (c) The University of Glasgow 2001 |
---|---|

License | BSD-style (see the file libraries/base/LICENSE) |

Maintainer | libraries@haskell.org |

Stability | stable |

Portability | portable |

Safe Haskell | Trustworthy |

Language | Haskell2010 |

The Maybe type, and associated operations.

# Documentation

The `Maybe`

type encapsulates an optional value. A value of type

either contains a value of type `Maybe`

a`a`

(represented as

),
or it is empty (represented as `Just`

a`Nothing`

). Using `Maybe`

is a good way to
deal with errors or exceptional cases without resorting to drastic
measures such as `error`

.

The `Maybe`

type is also a monad. It is a simple kind of error
monad, where all errors are represented by `Nothing`

. A richer
error monad can be built using the `Either`

type.

maybe :: b -> (a -> b) -> Maybe a -> b Source #

The `maybe`

function takes a default value, a function, and a `Maybe`

value. If the `Maybe`

value is `Nothing`

, the function returns the
default value. Otherwise, it applies the function to the value inside
the `Just`

and returns the result.

#### Examples

Basic usage:

`>>>`

True`maybe False odd (Just 3)`

`>>>`

False`maybe False odd Nothing`

Read an integer from a string using `readMaybe`

. If we succeed,
return twice the integer; that is, apply `(*2)`

to it. If instead
we fail to parse an integer, return `0`

by default:

`>>>`

`import Text.Read ( readMaybe )`

`>>>`

10`maybe 0 (*2) (readMaybe "5")`

`>>>`

0`maybe 0 (*2) (readMaybe "")`

Apply `show`

to a `Maybe Int`

. If we have `Just n`

, we want to show
the underlying `Int`

`n`

. But if we have `Nothing`

, we return the
empty string instead of (for example) "Nothing":

`>>>`

"5"`maybe "" show (Just 5)`

`>>>`

""`maybe "" show Nothing`

fromMaybe :: a -> Maybe a -> a Source #

The `fromMaybe`

function takes a default value and and `Maybe`

value. If the `Maybe`

is `Nothing`

, it returns the default values;
otherwise, it returns the value contained in the `Maybe`

.

#### Examples

Basic usage:

`>>>`

"Hello, World!"`fromMaybe "" (Just "Hello, World!")`

`>>>`

""`fromMaybe "" Nothing`

Read an integer from a string using `readMaybe`

. If we fail to
parse an integer, we want to return `0`

by default:

`>>>`

`import Text.Read ( readMaybe )`

`>>>`

5`fromMaybe 0 (readMaybe "5")`

`>>>`

0`fromMaybe 0 (readMaybe "")`

listToMaybe :: [a] -> Maybe a Source #

The `listToMaybe`

function returns `Nothing`

on an empty list
or

where `Just`

a`a`

is the first element of the list.

#### Examples

Basic usage:

`>>>`

Nothing`listToMaybe []`

`>>>`

Just 9`listToMaybe [9]`

`>>>`

Just 1`listToMaybe [1,2,3]`

Composing `maybeToList`

with `listToMaybe`

should be the identity
on singleton/empty lists:

`>>>`

[5]`maybeToList $ listToMaybe [5]`

`>>>`

[]`maybeToList $ listToMaybe []`

But not on lists with more than one element:

`>>>`

[1]`maybeToList $ listToMaybe [1,2,3]`

maybeToList :: Maybe a -> [a] Source #

The `maybeToList`

function returns an empty list when given
`Nothing`

or a singleton list when not given `Nothing`

.

#### Examples

Basic usage:

`>>>`

[7]`maybeToList (Just 7)`

`>>>`

[]`maybeToList Nothing`

One can use `maybeToList`

to avoid pattern matching when combined
with a function that (safely) works on lists:

`>>>`

`import Text.Read ( readMaybe )`

`>>>`

3`sum $ maybeToList (readMaybe "3")`

`>>>`

0`sum $ maybeToList (readMaybe "")`

catMaybes :: [Maybe a] -> [a] Source #

The `catMaybes`

function takes a list of `Maybe`

s and returns
a list of all the `Just`

values.

#### Examples

Basic usage:

`>>>`

[1,3]`catMaybes [Just 1, Nothing, Just 3]`

When constructing a list of `Maybe`

values, `catMaybes`

can be used
to return all of the "success" results (if the list is the result
of a `map`

, then `mapMaybe`

would be more appropriate):

`>>>`

`import Text.Read ( readMaybe )`

`>>>`

[Just 1,Nothing,Just 3]`[readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]`

`>>>`

[1,3]`catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]`

mapMaybe :: (a -> Maybe b) -> [a] -> [b] Source #

The `mapMaybe`

function is a version of `map`

which can throw
out elements. In particular, the functional argument returns
something of type

. If this is `Maybe`

b`Nothing`

, no element
is added on to the result list. If it is

, then `Just`

b`b`

is
included in the result list.

#### Examples

Using

is a shortcut for `mapMaybe`

f x

in most cases:`catMaybes`

$ `map`

f x

`>>>`

`import Text.Read ( readMaybe )`

`>>>`

`let readMaybeInt = readMaybe :: String -> Maybe Int`

`>>>`

[1,3]`mapMaybe readMaybeInt ["1", "Foo", "3"]`

`>>>`

[1,3]`catMaybes $ map readMaybeInt ["1", "Foo", "3"]`

If we map the `Just`

constructor, the entire list should be returned:

`>>>`

[1,2,3]`mapMaybe Just [1,2,3]`