base-4.9.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 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 # |
Methods (>>=) :: Maybe a -> (a -> Maybe b) -> Maybe b Source # (>>) :: Maybe a -> Maybe b -> Maybe b Source # return :: a -> Maybe a Source # fail :: String -> Maybe a Source #
Functor Maybe # |
Methods fmap :: (a -> b) -> Maybe a -> Maybe b Source # (<$) :: a -> Maybe b -> Maybe a Source #
MonadFix Maybe # |
Methods mfix :: (a -> Maybe a) -> Maybe a Source #
MonadFail Maybe # |
Methods fail :: String -> Maybe a Source #
Applicative Maybe # |
Methods pure :: a -> Maybe a Source # (<*>) :: Maybe (a -> b) -> Maybe a -> Maybe b Source # (*>) :: Maybe a -> Maybe b -> Maybe b Source # (<*) :: Maybe a -> Maybe b -> Maybe a Source #
Foldable Maybe # |
Methods fold :: Monoid m => Maybe m -> m Source # foldMap :: Monoid m => (a -> m) -> Maybe a -> m Source # foldr :: (a -> b -> b) -> b -> Maybe a -> b Source # foldr' :: (a -> b -> b) -> b -> Maybe a -> b Source # foldl :: (b -> a -> b) -> b -> Maybe a -> b Source # foldl' :: (b -> a -> b) -> b -> Maybe a -> b Source # foldr1 :: (a -> a -> a) -> Maybe a -> a Source # foldl1 :: (a -> a -> a) -> Maybe a -> a Source # toList :: Maybe a -> [a] Source # null :: Maybe a -> Bool Source # length :: Maybe a -> Int Source # elem :: Eq a => a -> Maybe a -> Bool Source # maximum :: Ord a => Maybe a -> a Source # minimum :: Ord a => Maybe a -> a Source # sum :: Num a => Maybe a -> a Source # product :: Num a => Maybe a -> a Source #
Traversable Maybe # |
Methods traverse :: Applicative f => (a -> f b) -> Maybe a -> f (Maybe b) Source # sequenceA :: Applicative f => Maybe (f a) -> f (Maybe a) Source # mapM :: Monad m => (a -> m b) -> Maybe a -> m (Maybe b) Source # sequence :: Monad m => Maybe (m a) -> m (Maybe a) Source #
Generic1 Maybe # |
Associated Types type Rep1 (Maybe :: * -> *) :: * -> * Source # Methods from1 :: Maybe a -> Rep1 Maybe a Source # to1 :: Rep1 Maybe a -> Maybe a Source #
MonadPlus Maybe # |
Methods mzero :: Maybe a Source # mplus :: Maybe a -> Maybe a -> Maybe a Source #
Alternative Maybe # |
Methods empty :: Maybe a Source # (<|>) :: Maybe a -> Maybe a -> Maybe a Source # some :: Maybe a -> Maybe [a] Source # many :: Maybe a -> Maybe [a] Source #
MonadZip Maybe # |
Methods mzip :: Maybe a -> Maybe b -> Maybe (a, b) Source # mzipWith :: (a -> b -> c) -> Maybe a -> Maybe b -> Maybe c Source # munzip :: Maybe (a, b) -> (Maybe a, Maybe b) Source #
Show1 Maybe # |
Methods liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> Maybe a -> ShowS Source # liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [Maybe a] -> ShowS Source #
Read1 Maybe # |
Methods liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (Maybe a) Source # liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [Maybe a] Source #
Ord1 Maybe # |
Methods liftCompare :: (a -> b -> Ordering) -> Maybe a -> Maybe b -> Ordering Source #
Eq1 Maybe # |
Methods liftEq :: (a -> b -> Bool) -> Maybe a -> Maybe b -> Bool Source #
Eq a => Eq (Maybe a) # |
Methods (==) :: Maybe a -> Maybe a -> Bool Source # (/=) :: Maybe a -> Maybe a -> Bool Source #
Data a => Data (Maybe a) # |
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Maybe a -> c (Maybe a) Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Maybe a) Source # toConstr :: Maybe a -> Constr Source # dataTypeOf :: Maybe a -> DataType Source # dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c (Maybe a)) Source # dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Maybe a)) Source # gmapT :: (forall b. Data b => b -> b) -> Maybe a -> Maybe a Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Maybe a -> r Source # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Maybe a -> r Source # gmapQ :: (forall d. Data d => d -> u) -> Maybe a -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> Maybe a -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Maybe a -> m (Maybe a) Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Maybe a -> m (Maybe a) Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Maybe a -> m (Maybe a) Source #
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) # |
Methods readsPrec :: Int -> ReadS (Maybe a) Source # readList :: ReadS [Maybe a] Source # readPrec :: ReadPrec (Maybe a) Source # readListPrec :: ReadPrec [Maybe a] Source #
Show a => Show (Maybe a) # |
Methods showsPrec :: Int -> Maybe a -> ShowS Source # show :: Maybe a -> String Source # showList :: [Maybe a] -> ShowS Source #
Generic (Maybe a) # |
Associated Types type Rep (Maybe a) :: * -> * Source # Methods from :: Maybe a -> Rep (Maybe a) x Source # to :: Rep (Maybe a) x -> Maybe a Source #
Semigroup a => Semigroup (Maybe a) # |
Methods (<>) :: Maybe a -> Maybe a -> Maybe a Source # sconcat :: NonEmpty (Maybe a) -> Maybe a Source # stimes :: Integral b => b -> Maybe a -> Maybe a Source #
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 is no "Semigroup" typeclass providing just `mappend`, we use `Monoid` instead.
Methods mempty :: Maybe a Source # mappend :: Maybe a -> Maybe a -> Maybe a Source # mconcat :: [Maybe a] -> Maybe a Source #
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 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 (==) (Maybe k) a b # |
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.

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