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

Data.Maybe

Description

The Maybe type, and associated operations.

Synopsis

data Maybe a
- = Nothing
- | Just a
maybe :: b -> (a -> b) -> Maybe a -> b
isJust :: Maybe a -> Bool
isNothing :: Maybe a -> Bool
fromJust :: Maybe a -> a
fromMaybe :: a -> Maybe a -> a
listToMaybe :: [a] -> Maybe a
maybeToList :: Maybe a -> [a]
catMaybes :: [Maybe a] -> [a]
mapMaybe :: (a -> Maybe b) -> [a] -> [b]

Documentation

data Maybe a Source

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.

Constructors

Nothing

Just a

Instances

Monad Maybe Source

Functor Maybe Source

MonadFix Maybe Source

Applicative Maybe Source

Foldable Maybe Source

Traversable Maybe Source

Generic1 Maybe Source

MonadPlus Maybe Source

Alternative Maybe Source

Eq a => Eq (Maybe a) Source

Data a => Data (Maybe a) Source

Ord a => Ord (Maybe a) Source

Read a => Read (Maybe a) Source

Show a => Show (Maybe a) Source

Generic (Maybe a) Source

Monoid a => Monoid (Maybe a) Source

Lift a semigroup into Maybe forming a Monoid according to http://en.wikipedia.org/wiki/Monoid: "Any semigroup S may be turned into a monoid simply by adjoining an element e not in S and defining e*e = e and e*s = s = s*e for all s ∈ S." Since there is no "Semigroup" typeclass providing just mappend , we use Monoid instead.

type Rep1 Maybe Source

type Rep (Maybe a) Source

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

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:

>>> maybe False odd (Just 3)
True

>>> maybe False odd Nothing
False

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 )
>>> maybe 0 (*2) (readMaybe "5")
10
>>> maybe 0 (*2) (readMaybe "")
0

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":

>>> maybe "" show (Just 5)
"5"
>>> maybe "" show Nothing
""

isJust :: Maybe a -> Bool Source

The isJust function returns True iff its argument is of the form Just _.

Examples

Basic usage:

>>> isJust (Just 3)
True

>>> isJust (Just ())
True

>>> isJust Nothing
False

Only the outer constructor is taken into consideration:

>>> isJust (Just Nothing)
True

isNothing :: Maybe a -> Bool Source

The isNothing function returns True iff its argument is Nothing .

Examples

Basic usage:

>>> isNothing (Just 3)
False

>>> isNothing (Just ())
False

>>> isNothing Nothing
True

Only the outer constructor is taken into consideration:

>>> isNothing (Just Nothing)
False

fromJust :: Maybe a -> a Source

The fromJust function extracts the element out of a Just and throws an error if its argument is Nothing .

Examples

Basic usage:

>>> fromJust (Just 1)
1

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

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

Examples

Basic usage:

>>> fromMaybe "" (Just "Hello, World!")
"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 )
>>> fromMaybe 0 (readMaybe "5")
5
>>> fromMaybe 0 (readMaybe "")
0

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.

Examples

Basic usage:

>>> listToMaybe []
Nothing

>>> listToMaybe [9]
Just 9

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

Composing maybeToList with listToMaybe should be the identity on singleton/empty lists:

>>> maybeToList $ listToMaybe [5]
[5]
>>> maybeToList $ listToMaybe []
[]

But not on lists with more than one element:

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

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:

>>> maybeToList (Just 7)
[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 )
>>> sum $ maybeToList (readMaybe "3")
3
>>> sum $ maybeToList (readMaybe "")
0

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:

>>> catMaybes [Just 1, Nothing, Just 3]
[1,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 )
>>> [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
[Just 1,Nothing,Just 3]
>>> catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
[1,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.

Examples

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
>>> mapMaybe readMaybeInt ["1", "Foo", "3"]
[1,3]
>>> catMaybes $ map readMaybeInt ["1", "Foo", "3"]
[1,3]

If we map the Just constructor, the entire list should be returned:

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