base-4.8.1.0: Basic libraries

Data.Maybe

Description

The Maybe type, and associated operations.

Synopsis

# 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

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

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