base-4.10.1.0: Basic libraries

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 #

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 # | Since: 2.1
Methods (>>=) :: Maybe a -> (a -> Maybe b) -> Maybe b # (>>) :: Maybe a -> Maybe b -> Maybe b # return :: a -> Maybe a # fail :: String -> Maybe a #
Functor Maybe # | Since: 2.1
Methods fmap :: (a -> b) -> Maybe a -> Maybe b # (<$) :: a -> Maybe b -> Maybe a #
MonadFix Maybe # | Since: 2.1
Methods mfix :: (a -> Maybe a) -> Maybe a #
MonadFail Maybe # | Since: 4.9.0.0
Methods fail :: String -> Maybe a #
Applicative Maybe # | Since: 2.1
Methods pure :: a -> Maybe a # (<*>) :: Maybe (a -> b) -> Maybe a -> Maybe b # liftA2 :: (a -> b -> c) -> Maybe a -> Maybe b -> Maybe c # (*>) :: Maybe a -> Maybe b -> Maybe b # (<*) :: Maybe a -> Maybe b -> Maybe a #
Foldable Maybe # | Since: 2.1

Methods

fold :: Monoid m => Maybe m -> m #

foldMap :: Monoid m => (a -> m) -> Maybe a -> m #

foldr :: (a -> b -> b) -> b -> Maybe a -> b #

foldr' :: (a -> b -> b) -> b -> Maybe a -> b #

foldl :: (b -> a -> b) -> b -> Maybe a -> b #

foldl' :: (b -> a -> b) -> b -> Maybe a -> b #

foldr1 :: (a -> a -> a) -> Maybe a -> a #

foldl1 :: (a -> a -> a) -> Maybe a -> a #

toList :: Maybe a -> [a] #

null :: Maybe a -> Bool #

length :: Maybe a -> Int #

elem :: Eq a => a -> Maybe a -> Bool #

maximum :: Ord a => Maybe a -> a #

minimum :: Ord a => Maybe a -> a #

sum :: Num a => Maybe a -> a #

product :: Num a => Maybe a -> a #

Traversable Maybe # | Since: 2.1
Methods traverse :: Applicative f => (a -> f b) -> Maybe a -> f (Maybe b) # sequenceA :: Applicative f => Maybe (f a) -> f (Maybe a) # mapM :: Monad m => (a -> m b) -> Maybe a -> m (Maybe b) # sequence :: Monad m => Maybe (m a) -> m (Maybe a) #
MonadPlus Maybe # | Since: 2.1
Methods mzero :: Maybe a # mplus :: Maybe a -> Maybe a -> Maybe a #
Alternative Maybe # | Since: 2.1
Methods empty :: Maybe a # (<|>) :: Maybe a -> Maybe a -> Maybe a # some :: Maybe a -> Maybe [a] # many :: Maybe a -> Maybe [a] #
MonadZip Maybe # | Since: 4.8.0.0
Methods mzip :: Maybe a -> Maybe b -> Maybe (a, b) # mzipWith :: (a -> b -> c) -> Maybe a -> Maybe b -> Maybe c # munzip :: Maybe (a, b) -> (Maybe a, Maybe b) #
Show1 Maybe # | Since: 4.9.0.0
Methods liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> Maybe a -> ShowS # liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [Maybe a] -> ShowS #
Read1 Maybe # | Since: 4.9.0.0
Methods liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (Maybe a) # liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [Maybe a] # liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (Maybe a) # liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [Maybe a] #
Ord1 Maybe # | Since: 4.9.0.0
Methods liftCompare :: (a -> b -> Ordering) -> Maybe a -> Maybe b -> Ordering #
Eq1 Maybe # | Since: 4.9.0.0
Methods liftEq :: (a -> b -> Bool) -> Maybe a -> Maybe b -> Bool #
Eq a => Eq (Maybe a) # |
Methods (==) :: Maybe a -> Maybe a -> Bool Source # (/=) :: Maybe a -> Maybe a -> Bool Source #
Data a => Data (Maybe a) # | Since: 4.0.0.0

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Maybe a -> c (Maybe a) #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Maybe a) #

toConstr :: Maybe a -> Constr #

dataTypeOf :: Maybe a -> DataType #

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c (Maybe a)) #

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Maybe a)) #

gmapT :: (forall b. Data b => b -> b) -> Maybe a -> Maybe a #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Maybe a -> r #

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Maybe a -> r #

gmapQ :: (forall d. Data d => d -> u) -> Maybe a -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> Maybe a -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Maybe a -> m (Maybe a) #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Maybe a -> m (Maybe a) #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Maybe a -> m (Maybe a) #

Ord a => Ord (Maybe a) # |
Methods compare :: Maybe a -> Maybe a -> Ordering Source # (<) :: Maybe a -> Maybe a -> Bool Source # (<=) :: Maybe a -> Maybe a -> Bool Source # (>) :: Maybe a -> Maybe a -> Bool Source # (>=) :: Maybe a -> Maybe a -> Bool Source # max :: Maybe a -> Maybe a -> Maybe a Source # min :: Maybe a -> Maybe a -> Maybe a Source #
Read a => Read (Maybe a) # | Since: 2.1
Methods readsPrec :: Int -> ReadS (Maybe a) # readList :: ReadS [Maybe a] # readPrec :: ReadPrec (Maybe a) # readListPrec :: ReadPrec [Maybe a] #
Show a => Show (Maybe a) # |
Methods showsPrec :: Int -> Maybe a -> ShowS # show :: Maybe a -> String # showList :: [Maybe a] -> ShowS #
Generic (Maybe a) # |
Associated Types type Rep (Maybe a) :: * -> * # Methods from :: Maybe a -> Rep (Maybe a) x # to :: Rep (Maybe a) x -> Maybe a #
Semigroup a => Semigroup (Maybe a) # | Since: 4.9.0.0
Methods (<>) :: Maybe a -> Maybe a -> Maybe a # sconcat :: NonEmpty (Maybe a) -> Maybe a # stimes :: Integral b => b -> Maybe a -> Maybe a #
Monoid a => Monoid (Maybe a) # | 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 used to be no "Semigroup" typeclass providing just `mappend`, we use `Monoid` instead. Since: 2.1
Methods mempty :: Maybe a # mappend :: Maybe a -> Maybe a -> Maybe a # mconcat :: [Maybe a] -> Maybe a #
Generic1 * Maybe # |
Associated Types type Rep1 Maybe (f :: Maybe -> *) :: k -> * # Methods from1 :: f a -> Rep1 Maybe f a # to1 :: Rep1 Maybe f a -> f a #
type Rep (Maybe a) # |
type Rep (Maybe a) = D1 * (MetaData "Maybe" "GHC.Base" "base" False) ((:+:) * (C1 * (MetaCons "Nothing" PrefixI False) (U1 *)) (C1 * (MetaCons "Just" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * a))))
type Rep1 * Maybe # |
type Rep1 * Maybe = D1 * (MetaData "Maybe" "GHC.Base" "base" False) ((:+:) * (C1 * (MetaCons "Nothing" PrefixI False) (U1 *)) (C1 * (MetaCons "Just" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) Par1)))
type (==) (Maybe k) a b # |
type (==) (Maybe k) a b

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

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 #

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 #

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 #

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 #

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 #

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

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

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

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]