|
4 | 4 |
|
5 | 5 | ### Types
|
6 | 6 |
|
7 |
| - data Maybe a where |
8 |
| - Nothing :: Maybe a |
9 |
| - Just :: a -> Maybe a |
| 7 | +#### `Maybe` |
| 8 | + |
| 9 | +The `Maybe` type is used to represent optional values and can be seen as |
| 10 | +something like a type-safe `null`, where `Nothing` is `null` and `Just x` |
| 11 | +is the non-null value `x`. |
| 12 | + |
| 13 | + data Maybe a |
| 14 | + = Nothing |
| 15 | + | Just a |
10 | 16 |
|
11 | 17 |
|
12 | 18 | ### Type Class Instances
|
13 | 19 |
|
| 20 | +#### `altMaybe` |
| 21 | + |
| 22 | +The `Alt` instance allows for a choice to be made between two `Maybe` |
| 23 | +values with the `<|>` operator, where the first `Just` encountered |
| 24 | +is taken. |
| 25 | + |
| 26 | +``` purescript |
| 27 | +Just x <|> Just y == Just x |
| 28 | +Nothing <|> Just y == Just y |
| 29 | +Nothing <|> Nothing == Nothing |
| 30 | +``` |
| 31 | + |
14 | 32 | instance altMaybe :: Alt Maybe
|
15 | 33 |
|
| 34 | +#### `alternativeMaybe` |
| 35 | + |
| 36 | +The `Alternative` instance guarantees that there are both `Applicative` and |
| 37 | +`Plus` instances for `Maybe`. |
| 38 | + |
16 | 39 | instance alternativeMaybe :: Alternative Maybe
|
17 | 40 |
|
| 41 | +#### `applicativeMaybe` |
| 42 | + |
| 43 | +The `Applicative` instance enables lifting of values into `Maybe` with the |
| 44 | +`pure` or `return` function (`return` is an alias for `pure`): |
| 45 | + |
| 46 | +``` purescript |
| 47 | +pure x :: Maybe _ == Just x |
| 48 | +return x :: Maybe _ == Just x |
| 49 | +``` |
| 50 | + |
| 51 | +Combining `Functor`'s' `<$>` with `Apply`'s `<*>` and `Applicative`'s |
| 52 | +`pure` can be used to pass a mixture of `Maybe` and non-`Maybe` typed |
| 53 | +values to a function that does not usually expect them, by using `pure` |
| 54 | +for any value that is not already `Maybe` typed: |
| 55 | + |
| 56 | +``` purescript |
| 57 | +f <$> Just x <*> pure y == Just (f x y) |
| 58 | +``` |
| 59 | + |
| 60 | +Even though `pure = Just` it is recommended to use `pure` in situations |
| 61 | +like this as it allows the choice of `Applicative` to be changed later |
| 62 | +without having to go through and replace `Just` with a new constructor. |
| 63 | + |
18 | 64 | instance applicativeMaybe :: Applicative Maybe
|
19 | 65 |
|
| 66 | +#### `applyMaybe` |
| 67 | + |
| 68 | +The `Apply` instance allows functions contained within a `Just` to |
| 69 | +transform a value contained within a `Just` using the `(<*>)` operator: |
| 70 | + |
| 71 | +``` purescript |
| 72 | +Just f <*> Just x == Just (f x) |
| 73 | +``` |
| 74 | + |
| 75 | +`Nothing` values are left untouched: |
| 76 | + |
| 77 | +``` purescript |
| 78 | +Just f <$> Nothing == Nothing |
| 79 | +Nothing <$> Just x == Nothing |
| 80 | +``` |
| 81 | + |
| 82 | +Combining `Functor`'s' `<$>` with `Apply`'s `<*>` can be used transform a |
| 83 | +pure function to take `Maybe`-typed arguments so `f :: a -> b -> c` |
| 84 | +becomes `f :: Maybe a -> Maybe b -> Maybe c`: |
| 85 | + |
| 86 | +``` purescript |
| 87 | +f <$> Just x <*> Just y == Just (f x y) |
| 88 | +``` |
| 89 | + |
| 90 | +The `Nothing`-preserving behaviour of both operators means the result of |
| 91 | +an expression like the above but where any one of the values is `Nothing` |
| 92 | +means the whole result becomes `Nothing` also: |
| 93 | + |
| 94 | +``` purescript |
| 95 | +f <$> Nothing <*> Just y == Nothing |
| 96 | +f <$> Just x <*> Nothing == Nothing |
| 97 | +f <$> Nothing <*> Nothing == Nothing |
| 98 | +``` |
| 99 | + |
20 | 100 | instance applyMaybe :: Apply Maybe
|
21 | 101 |
|
| 102 | +#### `bindMaybe` |
| 103 | + |
| 104 | +The `Bind` instance allows sequencing of `Maybe` values and functions that |
| 105 | +return a `Maybe` by using the `>>=` operator: |
| 106 | + |
| 107 | +``` purescript |
| 108 | +Just x >>= f = f x |
| 109 | +Nothing >>= f = Nothing |
| 110 | +``` |
| 111 | + |
22 | 112 | instance bindMaybe :: Bind Maybe
|
23 | 113 |
|
| 114 | +#### `eqMaybe` |
| 115 | + |
| 116 | +The `Eq` instance allows `Maybe` values to be checked for equality with |
| 117 | +`==` and inequality with `/=` whenever there is an `Eq` instance for the |
| 118 | +type the `Maybe` contains. |
| 119 | + |
24 | 120 | instance eqMaybe :: (Eq a) => Eq (Maybe a)
|
25 | 121 |
|
| 122 | +#### `extendMaybe` |
| 123 | + |
| 124 | +The `Extend` instance allows sequencing of `Maybe` values and functions |
| 125 | +that accept a `Maybe a` and return a non-`Maybe` result using the |
| 126 | +`<<=` operator. |
| 127 | + |
| 128 | +``` purescript |
| 129 | +f <<= Nothing = Nothing |
| 130 | +f <<= Just x = Just (f x) |
| 131 | +``` |
| 132 | + |
26 | 133 | instance extendMaybe :: Extend Maybe
|
27 | 134 |
|
| 135 | +#### `functorMaybe` |
| 136 | + |
| 137 | +The `Functor` instance allows functions to transform the contents of a |
| 138 | +`Just` with the `<$>` operator: |
| 139 | + |
| 140 | +``` purescript |
| 141 | +f <$> Just x == Just (f x) |
| 142 | +``` |
| 143 | + |
| 144 | +`Nothing` values are left untouched: |
| 145 | + |
| 146 | +``` purescript |
| 147 | +f <$> Nothing == Nothing |
| 148 | +``` |
| 149 | + |
28 | 150 | instance functorMaybe :: Functor Maybe
|
29 | 151 |
|
| 152 | +#### `monadMaybe` |
| 153 | + |
| 154 | +The `Monad` instance guarantees that there are both `Applicative` and |
| 155 | +`Bind` instances for `Maybe`. This also enables the `do` syntactic sugar: |
| 156 | + |
| 157 | +``` purescript |
| 158 | +do |
| 159 | + x' <- x |
| 160 | + y' <- y |
| 161 | + pure (f x' y') |
| 162 | +``` |
| 163 | + |
| 164 | +Which is equivalent to: |
| 165 | + |
| 166 | +``` purescript |
| 167 | +x >>= (\x' -> y >>= (\y' -> pure (f x' y'))) |
| 168 | +``` |
| 169 | + |
30 | 170 | instance monadMaybe :: Monad Maybe
|
31 | 171 |
|
| 172 | +#### `monadPlusMaybe` |
| 173 | + |
| 174 | +The `MonadPlus` instance guarantees that there are both `Monad` and |
| 175 | +`Alternative` instances for `Maybe`. |
| 176 | + |
32 | 177 | instance monadPlusMaybe :: MonadPlus Maybe
|
33 | 178 |
|
| 179 | +#### `ordMaybe` |
| 180 | + |
| 181 | +The `Ord` instance allows `Maybe` values to be compared with |
| 182 | +`compare`, `>`, `>=`, `<` and `<=` whenever there is an `Ord` instance for |
| 183 | +the type the `Maybe` contains. |
| 184 | + |
| 185 | +`Nothing` is considered to be less than any `Just` value. |
| 186 | + |
34 | 187 | instance ordMaybe :: (Ord a) => Ord (Maybe a)
|
35 | 188 |
|
| 189 | +#### `plusMaybe` |
| 190 | + |
| 191 | +The `Plus` instance provides a default `Maybe` value: |
| 192 | + |
| 193 | +``` purescript |
| 194 | +empty :: Maybe _ == Nothing |
| 195 | +``` |
| 196 | + |
36 | 197 | instance plusMaybe :: Plus Maybe
|
37 | 198 |
|
| 199 | +#### `semigroupMaybe` |
| 200 | + |
| 201 | +The `Semigroup` instance enables use of the operator `<>` on `Maybe` values |
| 202 | +whenever there is a `Semigroup` instance for the type the `Maybe` contains. |
| 203 | +The exact behaviour of `<>` depends on the "inner" `Semigroup` instance, |
| 204 | +but generally captures the notion of appending or combining things. |
| 205 | + |
| 206 | +``` purescript |
| 207 | +Just x <> Just y = Just (x <> y) |
| 208 | +Just x <> Nothing = Just x |
| 209 | +Nothing <> Just y = Just y |
| 210 | +Nothing <> Nothing = Nothing |
| 211 | +``` |
| 212 | + |
38 | 213 | instance semigroupMaybe :: (Semigroup a) => Semigroup (Maybe a)
|
39 | 214 |
|
| 215 | +#### `showMaybe` |
| 216 | + |
| 217 | +The `Show` instance allows `Maybe` values to be rendered as a string with |
| 218 | +`show` whenever there is an `Show` instance for the type the `Maybe` |
| 219 | +contains. |
| 220 | + |
40 | 221 | instance showMaybe :: (Show a) => Show (Maybe a)
|
41 | 222 |
|
42 | 223 |
|
43 | 224 | ### Values
|
44 | 225 |
|
| 226 | +#### `fromMaybe` |
| 227 | + |
| 228 | +Takes a default value, and a `Maybe` value. If the `Maybe` value is |
| 229 | +`Nothing` the default value is returned, otherwise the value inside the |
| 230 | +`Just` is returned. |
| 231 | + |
| 232 | +``` purescript |
| 233 | +fromMaybe default Nothing == default |
| 234 | +fromMaybe default (Just x) == x |
| 235 | +``` |
| 236 | + |
45 | 237 | fromMaybe :: forall a. a -> Maybe a -> a
|
46 | 238 |
|
| 239 | +#### `isJust` |
| 240 | + |
| 241 | +Returns `true` when the `Maybe` value was constructed with `Just`. |
| 242 | + |
47 | 243 | isJust :: forall a. Maybe a -> Boolean
|
48 | 244 |
|
| 245 | +#### `isNothing` |
| 246 | + |
| 247 | +Returns `true` when the `Maybe` value is `Nothing`. |
| 248 | + |
49 | 249 | isNothing :: forall a. Maybe a -> Boolean
|
50 | 250 |
|
| 251 | +#### `maybe` |
| 252 | + |
| 253 | +Takes a default value, a function, and a `Maybe` value. If the `Maybe` |
| 254 | +value is `Nothing` the default value is returned, otherwise the function |
| 255 | +is applied to the value inside the `Just` and the result is returned. |
| 256 | + |
| 257 | +``` purescript |
| 258 | +maybe default f Nothing == default |
| 259 | +maybe default f (Just x) == f x |
| 260 | +``` |
| 261 | + |
51 | 262 | maybe :: forall a b. b -> (a -> b) -> Maybe a -> b
|
52 | 263 |
|
53 | 264 |
|
54 | 265 | ## Module Data.Maybe.Unsafe
|
55 | 266 |
|
56 | 267 | ### Values
|
57 | 268 |
|
| 269 | +#### `fromJust` |
| 270 | + |
| 271 | +A partial function that extracts the value from the `Just` data |
| 272 | +constructor. Passing `Nothing` to `fromJust` will throw an error at |
| 273 | +runtime. |
| 274 | + |
58 | 275 | fromJust :: forall a. Maybe a -> a
|
0 commit comments