# Types

## Nil

Nil is a type used to represent the absence of something, similar to null or undefined in other languages.

Unlike some other languages values cannot be implicitly nil.

```pub type Nil =
Nil```

## Result

Result represents the result of something that may succeed or not. `Ok` means it was successful, `Error` means it was not successful.

```pub type Result(success, error) =
Result(success, error)```

# Functions

## flatten

`pub fn flatten(result: Result(Result(a, b), b)) -> Result(a, b)`

Merge a nested Result into a single layer.

## Examples

``````> flatten(Ok(Ok(1)))
Ok(1)

> flatten(Ok(Error(""))
Error("")

> flatten(Error(Nil))
Error(Nil)
``````

## is_error

`pub fn is_error(result: Result(a, b)) -> Bool`

Check whether the result is an Error value.

## Examples

``````> is_error(Ok(1))
False

> is_error(Error(Nil))
True
``````

## is_ok

`pub fn is_ok(result: Result(a, b)) -> Bool`

Check whether the result is an Ok value.

## Examples

``````> is_ok(Ok(1))
True

> is_ok(Error(Nil))
False
``````

## map

```pub fn map(
over result: Result(a, b),
with fun: fn(a) -> c,
) -> Result(c, b)```

Update a value held within the Ok of a result by calling a given function on it.

If the result is an Error rather than OK the function is not called and the result stays the same.

## Examples

``````> map(over: Ok(1), with: fn(x) { x + 1 })
Ok(2)

> map(over: Error(1), with: fn(x) { x + 1 })
Error(1)
``````

## map_error

```pub fn map_error(
over result: Result(a, b),
with fun: fn(b) -> c,
) -> Result(a, c)```

Update a value held within the Error of a result by calling a given function on it.

If the result is Ok rather than Error the function is not called and the result stays the same.

## Examples

``````> map_error(over: Error(1), with: fn(x) { x + 1 })
Error(2)

> map_error(over: Ok(1), with: fn(x) { x + 1 })
Ok(1)
``````

## nil_error

`pub fn nil_error(result: Result(a, b)) -> Result(a, Nil)`

Transforms any error into Error(Nil)

## Examples

``````> nil_error(Error(1))
Error(Nil)

> nil_error(Ok(1))
Ok(1)
``````

## or

```pub fn or(
first: Result(a, b),
second: Result(a, b),
) -> Result(a, b)```

Return the first value if it is Ok, otherwise return the second value.

## Examples

``````> or(Ok(1), Ok(2))
Ok(1)

> or(Ok(1), Error("Error 2"))
Ok(1)

> or(Error("Error 1"), Ok(2))
Ok(2)

> or(Error("Error 1"), Error("Error 2"))
Error("Error 2")
``````

## then

```pub fn then(
result: Result(a, b),
apply fun: fn(a) -> Result(c, b),
) -> Result(c, b)```

Update a value held within the Ok of a result by calling a given function on it, where the given function also returns a result. The two results are then merged together into one result.

If the result is an Error rather than OK the function is not called and the result stays the same.

This function is the equivalent of calling `map` followed by `flatten`, and it is useful for chaining together multiple functions that may fail.

## Examples

``````> then(Ok(1), fn(x) { Ok(x + 1) })
Ok(2)

> then(Ok(1), fn(x) { Ok(tuple("a", x)) })
Ok(tuple("a", 1))

> then(Ok(1), fn(x) { Error("Oh no") })
Error("Oh no")

> then(Error(Nil), fn(x) { Ok(x + 1) })
Error(Nil)
``````

## unwrap

`pub fn unwrap(result: Result(a, b), or default: a) -> a`

Extract the Ok value from a result, returning a default value if the result is an Error.

## Examples

``````> unwrap(Ok(1), 0)
1

> unwrap(Error(""), 0)
0
``````