base-4.18.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 :: HasCallStack => 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

Instances details

MonadFail Maybe Source # | Since: base-4.9.0.0
Instance details Defined in Control.Monad.Fail Methods fail :: String -> Maybe a Source #
MonadFix Maybe Source # | Since: base-2.1
Instance details Defined in Control.Monad.Fix Methods mfix :: (a -> Maybe a) -> Maybe a Source #
MonadZip Maybe Source # | Since: base-4.8.0.0
Instance details Defined in Control.Monad.Zip 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 #
Foldable Maybe Source # | Since: base-2.1

Instance details

Defined in Data.Foldable

Methods

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

foldMap :: Monoid m => (a -> m) -> Maybe a -> 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 #

Eq1 Maybe Source # | Since: base-4.9.0.0
Instance details Defined in Data.Functor.Classes Methods liftEq :: (a -> b -> Bool) -> Maybe a -> Maybe b -> Bool Source #
Ord1 Maybe Source # | Since: base-4.9.0.0
Instance details Defined in Data.Functor.Classes Methods liftCompare :: (a -> b -> Ordering) -> Maybe a -> Maybe b -> Ordering Source #
Read1 Maybe Source # | Since: base-4.9.0.0
Instance details Defined in Data.Functor.Classes Methods liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (Maybe a) Source # liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [Maybe a] Source # liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (Maybe a) Source # liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [Maybe a] Source #
Show1 Maybe Source # | Since: base-4.9.0.0
Instance details Defined in Data.Functor.Classes Methods liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> Maybe a -> ShowS Source # liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [Maybe a] -> ShowS Source #
Traversable Maybe Source # | Since: base-2.1
Instance details Defined in Data.Traversable 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 #
Alternative Maybe Source # | Picks the leftmost `Just` value, or, alternatively, `Nothing`. Since: base-2.1
Instance details Defined in GHC.Base Methods empty :: Maybe a Source # (<|>) :: Maybe a -> Maybe a -> Maybe a Source # some :: Maybe a -> Maybe [a] Source # many :: Maybe a -> Maybe [a] Source #
Applicative Maybe Source # | Since: base-2.1
Instance details Defined in GHC.Base Methods pure :: a -> Maybe a Source # (<*>) :: Maybe (a -> b) -> Maybe a -> Maybe b Source # liftA2 :: (a -> b -> c) -> Maybe a -> Maybe b -> Maybe c Source # (*>) :: Maybe a -> Maybe b -> Maybe b Source # (<*) :: Maybe a -> Maybe b -> Maybe a Source #
Functor Maybe Source # | Since: base-2.1
Instance details Defined in GHC.Base Methods fmap :: (a -> b) -> Maybe a -> Maybe b Source # (<$) :: a -> Maybe b -> Maybe a Source #
Monad Maybe Source # | Since: base-2.1
Instance details Defined in GHC.Base Methods (>>=) :: Maybe a -> (a -> Maybe b) -> Maybe b Source # (>>) :: Maybe a -> Maybe b -> Maybe b Source # return :: a -> Maybe a Source #
MonadPlus Maybe Source # | Picks the leftmost `Just` value, or, alternatively, `Nothing`. Since: base-2.1
Instance details Defined in GHC.Base Methods mzero :: Maybe a Source # mplus :: Maybe a -> Maybe a -> Maybe a Source #
Generic1 Maybe Source # |
Instance details Defined in GHC.Generics Associated Types type Rep1 Maybe :: k -> Type Source # Methods from1 :: forall (a :: k). Maybe a -> Rep1 Maybe a Source # to1 :: forall (a :: k). Rep1 Maybe a -> Maybe a Source #
Data a => Data (Maybe a) Source # | Since: base-4.0.0.0

Instance details

Defined in Data.Data

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 :: forall r r'. (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 #

Semigroup 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 4.11.0: constraint on inner `a` value generalised from `Monoid` to `Semigroup`. Since: base-2.1
Instance details Defined in GHC.Base Methods mempty :: Maybe a Source # mappend :: Maybe a -> Maybe a -> Maybe a Source # mconcat :: [Maybe a] -> Maybe a Source #
Semigroup a => Semigroup (Maybe a) Source # | Since: base-4.9.0.0
Instance details Defined in GHC.Base Methods (<>) :: Maybe a -> Maybe a -> Maybe a Source # sconcat :: NonEmpty (Maybe a) -> Maybe a Source # stimes :: Integral b => b -> Maybe a -> Maybe a Source #
Generic (Maybe a) Source # |
Instance details Defined in GHC.Generics Associated Types type Rep (Maybe a) :: Type -> Type Source # Methods from :: Maybe a -> Rep (Maybe a) x Source # to :: Rep (Maybe a) x -> Maybe a Source #
Read a => Read (Maybe a) Source # | Since: base-2.1
Instance details Defined in GHC.Read 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) Source # | Since: base-2.1
Instance details Defined in GHC.Show Methods showsPrec :: Int -> Maybe a -> ShowS Source # show :: Maybe a -> String Source # showList :: [Maybe a] -> ShowS Source #
Eq a => Eq (Maybe a) Source # | Since: base-2.1
Instance details Defined in GHC.Maybe Methods (==) :: Maybe a -> Maybe a -> Bool Source # (/=) :: Maybe a -> Maybe a -> Bool Source #
Ord a => Ord (Maybe a) Source # | Since: base-2.1
Instance details Defined in GHC.Maybe 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 #
type Rep1 Maybe Source # | Since: base-4.6.0.0
Instance details Defined in GHC.Generics type Rep1 Maybe = D1 ('MetaData "Maybe" "GHC.Maybe" "base" 'False) (C1 ('MetaCons "Nothing" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Just" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))
type Rep (Maybe a) Source # | Since: base-4.6.0.0
Instance details Defined in GHC.Generics type Rep (Maybe a) = D1 ('MetaData "Maybe" "GHC.Maybe" "base" 'False) (C1 ('MetaCons "Nothing" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Just" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))

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

Expand

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

Expand

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

Expand

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 :: HasCallStack => Maybe a -> a Source #

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

#### Examples

Expand

Basic usage:

    >>> fromJust (Just 1)
    1

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

    >>> 2 * (fromJust Nothing)
    *** Exception: Maybe.fromJust: Nothing
    ...

WARNING: This function is partial. You can use case-matching instead.

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

The `fromMaybe` function takes a default value and a `Maybe` value. If the `Maybe` is `Nothing`, it returns the default value; otherwise, it returns the value contained in the `Maybe`.

#### Examples

Expand

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

Expand

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 given `Just`.

#### Examples

Expand

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

Expand

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

Expand

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]