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.

The `Maybe`

type encapsulates an optional value. A value of type `Maybe a`

either contains a value of type `a`

(represented as `Just a`

), or it is empty (represented as `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.

Monad Maybe | |

Functor Maybe | |

MonadFix Maybe | |

Applicative Maybe | |

Foldable Maybe | |

Traversable Maybe | |

Generic1 Maybe | |

MonadPlus Maybe | |

Alternative Maybe | |

Eq a => Eq (Maybe a) | |

Data a => Data (Maybe a) | |

Ord a => Ord (Maybe a) | |

Read a => Read (Maybe a) | |

Show a => Show (Maybe a) | |

Generic (Maybe a) | |

Monoid a => Monoid (Maybe a) | Lift a semigroup into |

type Rep1 Maybe | |

type Rep (Maybe a) | |

type (==) (Maybe k) a b |

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.

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`

isJust :: Maybe a -> Bool Source

The `isJust`

function returns `True`

iff its argument is of the form `Just _`

.

Basic usage:

`>>>`

True`isJust (Just 3)`

`>>>`

True`isJust (Just ())`

`>>>`

False`isJust Nothing`

Only the outer constructor is taken into consideration:

`>>>`

True`isJust (Just Nothing)`

isNothing :: Maybe a -> Bool Source

The `isNothing`

function returns `True`

iff its argument is `Nothing`

.

Basic usage:

`>>>`

False`isNothing (Just 3)`

`>>>`

False`isNothing (Just ())`

`>>>`

True`isNothing Nothing`

Only the outer constructor is taken into consideration:

`>>>`

False`isNothing (Just Nothing)`

fromJust :: Maybe a -> a Source

The `fromJust`

function extracts the element out of a `Just`

and throws an error if its argument is `Nothing`

.

Basic usage:

`>>>`

1`fromJust (Just 1)`

`>>>`

20`2 * (fromJust (Just 10))`

`>>>`

*** Exception: Maybe.fromJust: Nothing`2 * (fromJust 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`

.

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 `Just a`

where `a`

is the first element of the list.

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`

.

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.

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 `Maybe b`

. If this is `Nothing`

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

, then `b`

is included in the result list.

Using `mapMaybe f x`

is a shortcut for `catMaybes $ map f x`

in most cases:

`>>>`

`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]`

© The University of Glasgow and others

Licensed under a BSD-style license (see top of the page).

https://downloads.haskell.org/~ghc/7.10.3/docs/html/libraries/base-4.8.2.0/Data-Maybe.html