Skip to content

Docs for Option #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 17, 2023
Merged

Docs for Option #42

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
279 changes: 144 additions & 135 deletions src/Core__Option.resi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,224 +22,233 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */

/**
We represent the existence and nonexistence of a value by wrapping it with
the `option` type. In order to make it a bit more convenient to work with
option-types, we provide utility-functions for it.
/***
We represent the existence and nonexistence of a value by wrapping it with
the `option` type. In order to make it a bit more convenient to work with
option-types, we provide utility-functions for it.

The `option` type is a part of the ReScript standard library which is defined
like this:
The `option` type is a part of the ReScript standard library which is defined
like this:

```res sig
type option<'a> = None | Some('a)
```
```rescript
type option<'a> = None | Some('a)
```

```res example
let someString: option<string> = Some("hello")
```
```rescript
let someString: option<string> = Some("hello")
```
*/

/**
If `optionValue` is `Some(value)` and `p(value) = true`, it returns `Some(value)`; otherwise returns `None`
`filter(opt, f)` applies `f` to `opt`, if `f` returns `true`, then it returns `Some(value)`, otherwise returns `None`.

## Examples

```res example
Option.filter(Some(10), x => x > 5) /* returns `Some(10)` */
Option.filter(Some(4), x => x > 5) /* returns `None` */
Option.filter(None, x => x > 5) /* returns `None` */
```
```rescript
Option.filter(Some(10), x => x > 5) // Some(10)
Option.filter(Some(4), x => x > 5) // None
Option.filter(None, x => x > 5) // None
```
*/
let filter: (option<'a>, 'a => bool) => option<'a>

/**
If `optionValue` is `Some(value`), it calls `f(value)`; otherwise returns `()`
`forEach(opt, f)` call `f` on `opt`. if `opt` is `Some(value)`, then if calls
`f`, otherwise returns `unit`.

```res example
Option.forEach(Some("thing"), x => Console.log(x)) /* logs "thing" */
Option.forEach(None, x => Console.log(x)) /* returns () */
```
## Examples

```rescript
Option.forEach(Some("thing"), x => Console.log(x)) // logs "thing"
Option.forEach(None, x => Console.log(x)) // returns ()
```
*/
let forEach: (option<'a>, 'a => unit) => unit

/**
Raises an Error in case `None` is provided. Use with care.
`getExn(opt)` raises an Error in case `None` is provided.

```rescript
Option.getExn(Some(3)) // 3
Option.getExn(None) /* Raises an Error */
```

```res example
Option.getExn(Some(3)) /* 3 */
## Exceptions

Option.getExn(None) /* Raises an Error */
```
- Raises an error if `opt` is `None`
*/
let getExn: option<'a> => 'a

/**
`getUnsafe(x)` returns `x`
`getUnsafe(value)` returns `value`.

## Examples

This is an unsafe operation, it assumes `x` is neither `None`
nor `Some(None(...)))`
```rescript
Option.getUnsafe(Some(3)) == 3
Option.getUnsafe(None) // Raises an error
```

## Exceptions

- This is an unsafe operation, it assumes `value` is neither `None` nor `Some(None(...)))`
*/
external getUnsafe: option<'a> => 'a = "%identity"

/**
If `optionValue` is of `Some(value)`,
this function returns that value applied with `f`, in other words `f(value)`.
`mapWithDefault(opt, default, f)` applies `f` to `opt`, if `opt` is `None`, then
`f` return `default`, otherwise return that value applied with `f`.

If `optionValue` is `None`, the default is returned.
## Examples

```res example
let someValue = Some(3)
someValue->Option.mapWithDefault(0, x => x + 5) /* 8 */
```rescript
let someValue = Some(3)
someValue->Option.mapWithDefault(0, x => x + 5) // 8

let noneValue = None
noneValue->Option.mapWithDefault(0, x => x + 5) /* 0 */
```
let noneValue = None
noneValue->Option.mapWithDefault(0, x => x + 5) // 0
```
*/
let mapWithDefault: (option<'a>, 'b, 'a => 'b) => 'b

/**
If `optionValue` is `Some(value)` this returns `f(value)`, otherwise it returns `None`.
`map(opt f)` applies `f` to `opt`, if `opt` is `Some(value)` this returns
`f(value)`, otherwise it returns `None`.

```res example
Option.map(Some(3), x => x * x) /* Some(9) */
## Examples

Option.map(None, x => x * x) /* None */
```
```rescript
Option.map(Some(3), x => x * x) // Some(9)
Option.map(None, x => x * x) // None
```
*/
let map: (option<'a>, 'a => 'b) => option<'b>

/**
If `optionValue` is `Some(value)`, returns `f(value)`, otherwise returns
`None`.<br/>
The function `f` must have a return type of `option<'b>`.

```res example
let addIfAboveOne = value =>
if (value > 1) {
Some(value + 1)
} else {
None
}

Option.flatMap(Some(2), addIfAboveOne) /* Some(3) */

Option.flatMap(Some(-4), addIfAboveOne) /* None */

Option.flatMap(None, addIfAboveOne) /* None */
```
`flatMap(opt, f)` returns `f` applied to `opt` if `opt` is `Some(value)`,
otherwise `None`. The function `f` must have a return type of `option<'b>`.

## Examples

```rescript
let addIfAboveOne = value =>
if (value > 1) {
Some(value + 1)
} else {
None
}

Option.flatMap(Some(2), addIfAboveOne) // Some(3)
Option.flatMap(Some(-4), addIfAboveOne) // None
Option.flatMap(None, addIfAboveOne) // None
```
*/
let flatMap: (option<'a>, 'a => option<'b>) => option<'b>

/**
If `optionalValue` is `Some(value)`, returns `value`, otherwise default.

```res example
Option.getWithDefault(None, "Banana") /* Banana */
`getWithDefault(opt, default)` returns `value` if `opt` is `Some(value)`,
otherwise return `default` if `opt` is `None`.

Option.getWithDefault(Some("Apple"), "Banana") /* Apple */
```
## Examples

```res example
let greet = (firstName: option<string>) =>
"Greetings " ++ firstName->Option.getWithDefault("Anonymous")
```rescript
Option.getWithDefault(None, "Banana") // Banana
Option.getWithDefault(Some("Apple"), "Banana") // Apple

Some("Jane")->greet /* "Greetings Jane" */
let greet = (firstName: option<string>) =>
"Greetings " ++ firstName->Option.getWithDefault("Anonymous")

None->greet /* "Greetings Anonymous" */
```
Some("Jane")->greet // "Greetings Jane"
None->greet // "Greetings Anonymous"
```
*/
let getWithDefault: (option<'a>, 'a) => 'a

/**
`orElse optionalValue otherOptional`
`orElse(opt1, opt2)` returns `opt2` if `opt1` is `None`, otherwise `opt1`.

If `optionalValue` is `Some value`, returns `Some value`, otherwise `otherOptional`
## Examples

```
orElse (Some 1812) (Some 1066) = Some 1812;;
orElse None (Some 1066) = Some 1066;;
orElse None None = None;;
```
```rescript
Option.orElse(Some(1812), Some(1066)) == Some(1812)
Option.orElse(None, Some(1066) == Some(1066)
Option.orElse(None, None) == None
```
*/
let orElse: (option<'a>, option<'a>) => option<'a>

/**
Returns `true` if the argument is `Some(value)`, `false` otherwise.
`isSome(opt)` returns `true` if `opt` is `Some(value)`, otherwise returns `false`.

```res example
Option.isSome(None) /* false */
## Examples

Option.isSome(Some(1)) /* true */
```
```rescript
Option.isSome(None) // false
Option.isSome(Some(1)) // true
```
*/
let isSome: option<'a> => bool

/**
Returns `true` if the argument is `None`, `false` otherwise.
`isNone(opt)` returns `true` if `opt` is `None`, false otherwise.

```res example
Option.isNone(None) /* true */
## Examples

Option.isNone(Some(1)) /* false */
```
```rescript
Option.isNone(None) // true
Option.isNone(Some(1)) // false
```
*/
let isNone: option<'a> => bool

/**
Evaluates two optional values for equality with respect to a predicate
function. If both `optValue1` and `optValue2` are `None`, returns `true`.
If one of the arguments is `Some(value)` and the other is `None`, returns
`false`.

If arguments are `Some(value1)` and `Some(value2)`, returns the result of
`predicate(value1, value2)`; the predicate function must return a bool.

```res example
let clockEqual = (a, b) => mod(a, 12) == mod(b, 12)

open Option
`eq(opt1, opt2, f)` evaluates two optional values for equality with respect to a predicate function `f`. If both `opt1` and `opt2` are `None`, returns `true`.
If one of the arguments is `Some(value)` and the other is `None`, returns
`false`.
If arguments are `Some(value1)` and `Some(value2)`, returns the result of
`f(value1, value2)`, the predicate function `f` must return a bool.

eq(Some(3), Some(15), clockEqual) /* true */
## Examples

eq(Some(3), None, clockEqual) /* false */
```rescript
let clockEqual = (a, b) => mod(a, 12) == mod(b, 12)

eq(None, Some(3), clockEqual) /* false */
open Option

eq(None, None, clockEqual) /* true */
```
eq(Some(3), Some(15), clockEqual) // true
eq(Some(3), None, clockEqual) // false
eq(None, Some(3), clockEqual) // false
eq(None, None, clockEqual) // true
```
*/
let eq: (option<'a>, option<'b>, ('a, 'b) => bool) => bool

/**
`cmp(optValue1, optValue2, comparisonFunction)` compares two optional values
with respect to given `comparisonFunction`.

If both `optValue1` and `optValue2` are `None`, it returns `0`.

If the first argument is `Some(value1)` and the second is `None`, returns `1`
(something is greater than nothing).

If the first argument is `None` and the second is `Some(value2)`, returns `-1`
(nothing is less than something).

If the arguments are `Some(value1)` and `Some(value2)`, returns the result of
`comparisonFunction(value1, value2)`; comparisonFunction takes two arguments
and returns `-1` if the first argument is less than the second, `0` if the
arguments are equal, and `1` if the first argument is greater than the second.

```res example
let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12))
`cmp(opt1, opt2, f)` compares two optional values with respect to given `f`.

open Option
If both `opt1` and `opt2` are `None`, it returns `0`. If the first argument is `Some(value1)` and the second is `None`, returns `1` (something is greater than nothing).

cmp(Some(3), Some(15), clockCompare) /* 0 */
If the first argument is `None` and the second is `Some(value2)`, returns `-1`
(nothing is less than something).

cmp(Some(3), Some(14), clockCompare) /* 1 */
If the arguments are `Some(value1)` and `Some(value2)`, returns the result of
`f(value1, value2)`, `f` takes two arguments and returns `-1` if the first
argument is less than the second, `0` if the arguments are equal, and `1` if
the first argument is greater than the second.

cmp(Some(2), Some(15), clockCompare) /* (-1) */
## Examples

cmp(None, Some(15), clockCompare) /* (-1) */
```rescript
let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12))

cmp(Some(14), None, clockCompare) /* 1 */
open Option

cmp(None, None, clockCompare) /* 0 */
```
cmp(Some(3), Some(15), clockCompare) // 0
cmp(Some(3), Some(14), clockCompare) // 1
cmp(Some(2), Some(15), clockCompare) // (-1)
cmp(None, Some(15), clockCompare) // (-1)
cmp(Some(14), None, clockCompare) // 1
cmp(None, None, clockCompare) // 0
```
*/
let cmp: (option<'a>, option<'b>, ('a, 'b) => int) => int