Option

GitHub   Edit on GitHub

Utilities for working with the Option data type.

The Option type is an enum that represents the possibility of something being present (with the Some variant), or not (with the None variant). There’s no standalone null or nil type in Grain; use an Option where you would normally reach for null or nil.

Added in 0.2.0 No other changes yet.
1
from "option" include Option
1
let hasValue = Some(1234) // Creates an Option containing 1234
1
let noValue = None // Creates an Option containing nothing

Values

Functions and constants included in the Option module.

Option.isSome

Added in 0.2.0 No other changes yet.
1
isSome : (option: Option<a>) => Bool

Checks if the Option is the Some variant.

Parameters:

param type description
option Option<a> The option to check

Returns:

type description
Bool true if the Option is the Some variant or false otherwise

Option.isNone

Added in 0.2.0 No other changes yet.
1
isNone : (option: Option<a>) => Bool

Checks if the Option is the None variant.

Parameters:

param type description
option Option<a> The option to check

Returns:

type description
Bool true if the Option is the None variant or false otherwise

Option.contains

Added in 0.2.0 No other changes yet.
1
contains : (value: a, option: Option<a>) => Bool

Checks if the Option is the Some variant and contains the given value. Uses the generic == equality operator.

Parameters:

param type description
value a The value to search for
option Option<a> The option to search

Returns:

type description
Bool true if the Option is equivalent to Some(value) or false otherwise

Option.expect

Added in 0.2.0 No other changes yet.
1
expect : (msg: String, option: Option<a>) => a

Extracts the value inside a Some option, otherwise throws an exception containing the message provided.

Parameters:

param type description
msg String The message to use upon failure
option Option<a> The option to extract a value from

Returns:

type description
a The unwrapped value if the Option is the Some variant

Throws:

Failure(String)

  • When the option is None

Option.unwrap

Added in 0.2.0 No other changes yet.
1
unwrap : (option: Option<a>) => a

Extracts the value inside a Some option, otherwise throws an exception containing a default message.

Parameters:

param type description
option Option<a> The option to extract the value from

Returns:

type description
a The unwrapped value if the Option is the Some variant

Throws:

Failure(String)

  • When the option is None

Option.unwrapWithDefault

Added in 0.2.0 No other changes yet.
1
unwrapWithDefault : (default: a, option: Option<a>) => a

Extracts the value inside a Some option or provide the default value if None.

Parameters:

param type description
default a The default value
option Option<a> The option to unwrap

Returns:

type description
a The unwrapped value if the Option is the Some variant or the default value otherwise

Option.map

Added in 0.2.0 No other changes yet.
1
map : (fn: (a => b), option: Option<a>) => Option<b>

If the Option is Some(value), applies the given function to the value and wraps the new value in a Some variant.

Parameters:

param type description
fn a => b The function to call on the value of a Some variant
option Option<a> The option to map

Returns:

type description
Option<b> A new Some variant produced by the mapping function if the variant was Some or the unmodified None otherwise

Option.mapWithDefault

Added in 0.2.0 No other changes yet.
1
mapWithDefault : (fn: (a => b), default: b, option: Option<a>) => b

If the Option is Some(value), applies the given function to the value to produce a new value, otherwise uses the default value. Useful for unwrapping an Option while providing a fallback for any None variants.

Parameters:

param type description
fn a => b The function to call on the value of a Some variant
default b A fallback value for a None variant
option Option<a> The option to map

Returns:

type description
b The value produced by the mapping function if the Option is of the Some variant or the default value otherwise

Option.mapWithDefaultFn

Added in 0.2.0 No other changes yet.
1
2
mapWithDefaultFn :
(fn: (a => b), defaultFn: (() => b), option: Option<a>) => b

If the Option is Some(value), applies the fn function to the value to produce a new value. If the Option is None, calls the defaultFn function to produce a new value. Useful for unwrapping an Option into a value, whether it is Some or None.

Parameters:

param type description
fn a => b The function to call on the value of a Some variant
defaultFn () => b The default function
option Option<a> The option to map

Returns:

type description
b The value produced by one of the mapping functions

Option.flatMap

Added in 0.2.0 No other changes yet.
1
flatMap : (fn: (a => Option<b>), option: Option<a>) => Option<b>

If the Option is Some(value), applies the given function to the value to produce a new Option.

Parameters:

param type description
fn a => Option<b> The function to call on the value of a Some variant
option Option<a> The option to map

Returns:

type description
Option<b> A new Option produced by the mapping function if the variant was Some or the unmodified None otherwise

Option.filter

Added in 0.2.0 No other changes yet.
1
filter : (fn: (a => Bool), option: Option<a>) => Option<a>

Converts Some(value) variants to None variants where the predicate function returns false. if the fn return true returns Some(value), otherwise returns None.

Parameters:

param type description
fn a => Bool The predicate function to indicate if the option should remain Some
option Option<a> The option to inspect

Returns:

type description
Option<a> Some(value) if the variant was Some and the predicate returns true or None otherwise

Option.zip

Added in 0.2.0 No other changes yet.
1
zip : (optionA: Option<a>, optionB: Option<b>) => Option<(a, b)>

Combine two Options into a single Option containing a tuple of their values.

Parameters:

param type description
optionA Option<a> The first option to combine
optionB Option<b> The second option to combine

Returns:

type description
Option<(a, b)> Some((valueA, valueB)) if both Options are Some variants or None otherwise

Option.zipWith

Added in 0.2.0 No other changes yet.
1
2
zipWith :
(fn: ((a, b) => c), optionA: Option<a>, optionB: Option<b>) => Option<c>

Combine two Options into a single Option. The new value is produced by applying the given function to both values.

Parameters:

param type description
fn (a, b) => c The function to generate a new value
optionA Option<a> The first option to combine
optionB Option<b> The second option to combine

Returns:

type description
Option<c> Some(newValue) if both Options are Some variants or None otherwise

Option.flatten

Added in 0.2.0 No other changes yet.
1
flatten : (option: Option<Option<a>>) => Option<a>

Flattens nested Options.

Parameters:

param type description
option Option<Option<a>> The option to flatten

Returns:

type description
Option<a> Some(innerValue) if all nested options were the Some variant or None otherwise

Examples:

1
Option.flatten(Some(Some(1))) == Some(1)

Option.toList

Added in 0.2.0 No other changes yet.
1
toList : (option: Option<a>) => List<a>

Converts an Option to a list with either zero or one item.

Parameters:

param type description
option Option<a> The option to convert

Returns:

type description
List<a> [value] if the Option was the Some variant or [] otherwise

Option.toArray

Added in 0.2.0 No other changes yet.
1
toArray : (option: Option<a>) => Array<a>

Converts an Option to an array with either zero or one item.

Parameters:

param type description
option Option<a> The option to convert

Returns:

type description
Array<a> [> value] if the Option was the Some variant or [> ] otherwise

Option.toResult

Added in 0.2.0 No other changes yet.
1
toResult : (err: a, option: Option<b>) => Result<b, a>

Converts the Option to a Result, using the provided error in case of the None variant.

Parameters:

param type description
err a The error to use if the option is None
option Option<b> The option to convert

Returns:

type description
Result<b, a> Ok(value) if the Option is Some(value) or Err(err) if the Option is None

Option.sideEffect

Added in 0.2.0 No other changes yet.
1
sideEffect : (fn: (a => Void), option: Option<a>) => Void

If the Option is Some(value), applies the fn function to the value without producing a new value.

Parameters:

param type description
fn a => Void The function to call on the value of a Some variant
option Option<a> The option to inspect

Option.peek

Added in 0.2.0 No other changes yet.
1
peek : (fn: (a => Void), option: Option<a>) => Option<a>

If the Option is Some(value), applies the fn function to the value without producing a new value. Useful for inspecting Options without changing anything.

Parameters:

param type description
fn a => Void The function to call on the value of a Some variant
option Option<a> The option to inspect

Returns:

type description
Option<a> The unmodified option

Option.(||)

Added in 0.6.0
versionchanges
0.2.0Originally named `or`
1
(||) : (optionA: Option<a>, optionB: Option<a>) => Option<a>

Behaves like a logical OR (||) where the first Option is only returned if it is the Some variant and falling back to the second Option in all other cases.

Parameters:

param type description
optionA Option<a> The first option
optionB Option<a> The second option

Returns:

type description
Option<a> The first Option if it is the Some variant or the second Option otherwise

Option.(&&)

Added in 0.6.0
versionchanges
0.2.0Originally named `and`
1
(&&) : (optionA: Option<a>, optionB: Option<a>) => Option<a>

Behaves like a logical AND (&&) where the first Option is only returned if it is the None variant and falling back to the second Option Result in all other cases.

Parameters:

param type description
optionA Option<a> The first option
optionB Option<a> The second option

Returns:

type description
Option<a> The second Option if both are the Some variant or the first Option otherwise
This is a notification!