| Title: | The Maybe Monad |
|---|---|
| Description: | The maybe type represents the possibility of some value or nothing. It is often used instead of throwing an error or returning `NULL`. The advantage of using a maybe type over `NULL` is that it is both composable and requires the developer to explicitly acknowledge the potential absence of a value, helping to avoid the existence of unexpected behaviour. |
| Authors: | Andrew McNeil [aut, cre] |
| Maintainer: | Andrew McNeil <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.1.0 |
| Built: | 2024-10-31 03:49:41 UTC |
| Source: | https://github.com/armcn/maybe |
Combine predicate functions to check if all are TRUE
and(...)and(...)
... |
Predicate functions |
A predicate function
and(not_null, not_na)(1) and(not_null, not_na)(NULL)and(not_null, not_na)(1) and(not_null, not_na)(NULL)
Evaluate a maybe returning function on a maybe value
and_then(.m, .f, ...) bind(.m, .f, ...)and_then(.m, .f, ...) bind(.m, .f, ...)
.m |
A maybe value |
.f |
A maybe returning function to apply to the maybe value |
... |
Named arguments for the function |
A maybe value
safe_sqrt <- maybe(sqrt, ensure = not_infinite) just(9) %>% and_then(safe_sqrt) just(-1) %>% and_then(safe_sqrt) nothing() %>% and_then(safe_sqrt)safe_sqrt <- maybe(sqrt, ensure = not_infinite) just(9) %>% and_then(safe_sqrt) just(-1) %>% and_then(safe_sqrt) nothing() %>% and_then(safe_sqrt)
Evaluate a binary maybe returning function on two maybe values
and_then2(.m1, .m2, .f, ...)and_then2(.m1, .m2, .f, ...)
.m1 |
A maybe value |
.m2 |
A maybe value |
.f |
A binary maybe returning function to apply to the maybe values |
... |
Named arguments for the function |
A maybe value
and_then2(just(1), just(2), maybe(`+`)) and_then2(nothing(), just(2), maybe(`/`))and_then2(just(1), just(2), maybe(`+`)) and_then2(nothing(), just(2), maybe(`/`))
Evaluate a ternary maybe returning function on three maybe values
and_then3(.m1, .m2, .m3, .f, ...)and_then3(.m1, .m2, .m3, .f, ...)
.m1 |
A maybe value |
.m2 |
A maybe value |
.m3 |
A maybe value |
.f |
A ternary maybe returning function to apply to the maybe values |
... |
Named arguments for the function |
A maybe value
safe_sum <- maybe(function(x, y, z) sum(x, y, z)) and_then3(just(1), just(2), just(3), safe_sum) and_then3(nothing(), just(2), just(3), safe_sum)safe_sum <- maybe(function(x, y, z) sum(x, y, z)) and_then3(just(1), just(2), just(3), safe_sum) and_then3(nothing(), just(2), just(3), safe_sum)
Filter and unwrap a list of 'Just' values
filter_justs(.l)filter_justs(.l)
.l |
List of maybe values |
A list of values
filter_justs(list(just(1), nothing(), just("a")))filter_justs(list(just(1), nothing(), just("a")))
Map a function over a list and filter only 'Just' values
filter_map(.l, .f, ...)filter_map(.l, .f, ...)
.l |
List of values |
.f |
A maybe returning function to apply to the maybe values |
... |
Named arguments for the function |
A list of values
filter_map(list(-1, "2", 9), maybe(sqrt))filter_map(list(-1, "2", 9), maybe(sqrt))
Unwrap a 'Just' value or throw an error
from_just(.m)from_just(.m)
.m |
A maybe value |
The unwrapped 'Just' value
just(1) %>% from_just()just(1) %>% from_just()
Check if an object is a 'Just' value
is_just(a)is_just(a)
a |
Object to check |
TRUE or FALSE
is_just(1) is_just(just(1)) is_just(nothing())is_just(1) is_just(just(1)) is_just(nothing())
Check if an object is a maybe value
is_maybe(a)is_maybe(a)
a |
Object to check |
TRUE or FALSE
is_maybe(1) is_maybe(just(1)) is_maybe(nothing())is_maybe(1) is_maybe(just(1)) is_maybe(nothing())
Check if an object is a 'Nothing' value
is_nothing(a)is_nothing(a)
a |
Object to check |
TRUE or FALSE
is_nothing(1) is_nothing(just(1)) is_nothing(nothing())is_nothing(1) is_nothing(just(1)) is_nothing(nothing())
Create a 'Just' variant of a maybe value
just(a)just(a)
a |
A value to wrap in a 'Just' container |
A 'Just' variant of a maybe value
just(1) just("hello")just(1) just("hello")
Wrapping a function in maybe will modify it to return a maybe value. If
the function would normally return an error or warning the modified function
will return a 'Nothing' value, otherwise it will return a 'Just' value.
If a predicate function is provided with the parameter ensure, if the
predicate returns TRUE when evaluated on the return value of the function,
then a 'Just' value will be returned by the modified function, otherwise
it will return a 'Nothing' value.
maybe(.f, ensure = function(a) TRUE, allow_warning = FALSE)maybe(.f, ensure = function(a) TRUE, allow_warning = FALSE)
.f |
A function to modify |
ensure |
A predicate function |
allow_warning |
Whether warnings should result in 'Nothing' values |
A function which returns maybe values
maybe(mean)(1:10) maybe(mean, allow_warning = TRUE)("hello") maybe(sqrt)("hello") maybe(sqrt, ensure = not_infinite)(-1)maybe(mean)(1:10) maybe(mean, allow_warning = TRUE)("hello") maybe(sqrt)("hello") maybe(sqrt, ensure = not_infinite)(-1)
Unwrap and call a function on a maybe value or return a default
maybe_case(.m, .f, default)maybe_case(.m, .f, default)
.m |
A maybe value |
.f |
A function to apply to the maybe value in the case of 'Just' |
default |
A default value to return in the case of 'Nothing' |
The return value of the 'Just' function or the default value
just(1:10) %>% maybe_case(mean, 0) nothing() %>% maybe_case(mean, 0)just(1:10) %>% maybe_case(mean, 0) nothing() %>% maybe_case(mean, 0)
If the maybe value is a 'Nothing' variant FALSE will be returned. If it is
a 'Just' variant the contents will be unwrapped and compared to the value
argument using base::identical.
maybe_contains(.m, value)maybe_contains(.m, value)
.m |
A maybe value |
value |
A value to check |
TRUE or FALSE
just(1) %>% maybe_contains(1) just("a") %>% maybe_contains(1) nothing() %>% maybe_contains(1)just(1) %>% maybe_contains(1) just("a") %>% maybe_contains(1) nothing() %>% maybe_contains(1)
If both values are 'Nothing' variants or both values are 'Just' variants with
identical contents TRUE will be returned, otherwise FALSE.
maybe_equal(.m1, .m2)maybe_equal(.m1, .m2)
.m1 |
A maybe value |
.m2 |
A maybe value |
TRUE or FALSE
maybe_equal(just(1), just(1)) maybe_equal(just(1), just(2)) maybe_equal(nothing(), nothing())maybe_equal(just(1), just(1)) maybe_equal(just(1), just(2)) maybe_equal(nothing(), nothing())
Flatten a nested maybe value
maybe_flatten(.m) join(.m)maybe_flatten(.m) join(.m)
.m |
A maybe value |
A maybe value
just(just(1)) %>% maybe_flatten() just(nothing()) %>% maybe_flatten() just(1) %>% maybe_flatten() nothing() %>% maybe_flatten()just(just(1)) %>% maybe_flatten() just(nothing()) %>% maybe_flatten() just(1) %>% maybe_flatten() nothing() %>% maybe_flatten()
Evaluate a function on a maybe value
maybe_map(.m, .f, ...) fmap(.m, .f, ...)maybe_map(.m, .f, ...) fmap(.m, .f, ...)
.m |
A maybe value |
.f |
A function to apply to the maybe value |
... |
Named arguments for the function |
A maybe value
just(9) %>% maybe_map(sqrt) nothing() %>% maybe_map(sqrt)just(9) %>% maybe_map(sqrt) nothing() %>% maybe_map(sqrt)
Evaluate a binary function on two maybe values
maybe_map2(.m1, .m2, .f, ...)maybe_map2(.m1, .m2, .f, ...)
.m1 |
A maybe value |
.m2 |
A maybe value |
.f |
A binary function to apply to the maybe values |
... |
Named arguments for the function |
A maybe value
maybe_map2(just(1), just(2), `+`) maybe_map2(nothing(), just(2), `/`)maybe_map2(just(1), just(2), `+`) maybe_map2(nothing(), just(2), `/`)
Evaluate a ternary function on three maybe values
maybe_map3(.m1, .m2, .m3, .f, ...)maybe_map3(.m1, .m2, .m3, .f, ...)
.m1 |
A maybe value |
.m2 |
A maybe value |
.m3 |
A maybe value |
.f |
A ternary function to apply to the maybe values |
... |
Named arguments for the function |
A maybe value
maybe_map3(just(1), just(2), just(3), function(x, y, z) x + y + z) maybe_map3(nothing(), just(2), just(3), function(x, y, z) x / y * z)maybe_map3(just(1), just(2), just(3), function(x, y, z) x + y + z) maybe_map3(nothing(), just(2), just(3), function(x, y, z) x / y * z)
Check if a vector or data frame is empty
not_empty(a)not_empty(a)
a |
Object to check |
TRUE or FALSE
not_empty(integer()) not_empty(list()) not_empty(1:10) not_empty(data.frame()) not_empty(data.frame(a = 1:10))not_empty(integer()) not_empty(list()) not_empty(1:10) not_empty(data.frame()) not_empty(data.frame(a = 1:10))
Check if an object is not infinite
not_infinite(a)not_infinite(a)
a |
Object to check |
TRUE or FALSE
not_infinite(Inf) not_infinite(1)not_infinite(Inf) not_infinite(1)
Check if an object is not NA
not_na(a)not_na(a)
a |
Object to check |
TRUE or FALSE
not_na(NA) not_na(1)not_na(NA) not_na(1)
Check if an object is not NaN
not_nan(a)not_nan(a)
a |
Object to check |
TRUE or FALSE
not_nan(NaN) not_nan(1)not_nan(NaN) not_nan(1)
Check if an object is not NULL
not_null(a)not_null(a)
a |
Object to check |
TRUE or FALSE
not_null(NULL) not_null(1)not_null(NULL) not_null(1)
In this case 'undefined' values include NULL, NaN, all NA variants,
and infinite values.
not_undefined(a)not_undefined(a)
a |
Object to check |
TRUE or FALSE
not_undefined(NA) not_undefined(NULL) not_undefined(1)not_undefined(NA) not_undefined(NULL) not_undefined(1)
Create a 'Nothing' variant of a maybe value
nothing()nothing()
A 'Nothing' variant of a maybe value
nothing()nothing()
Combine predicate functions to check if any are TRUE
or(...)or(...)
... |
Predicate functions |
A predicate function
or(not_null, not_na)(1) or(not_null, not_na)(NULL)or(not_null, not_na)(1) or(not_null, not_na)(NULL)
Wrapping a function in perhaps will modify it to return the expected value
or a default value in some circumstances. If the function would normally
return an error or warning the modified function will return a default value,
otherwise it will return the expected value. If a predicate function is
provided with the parameter ensure, if the predicate returns TRUE when
evaluated on the return value of the function, then the expected value will
be returned by the modified function, otherwise it will return the default
value.
perhaps(.f, default, ensure = function(a) TRUE, allow_warning = FALSE)perhaps(.f, default, ensure = function(a) TRUE, allow_warning = FALSE)
.f |
A function to modify |
default |
A default value |
ensure |
A predicate function |
allow_warning |
Whether warnings should result in the default value |
A function which returns the expected value or the default value
perhaps(mean, default = 0)(1:10) perhaps(mean, default = 0, allow_warning = TRUE)("hello") perhaps(sqrt, default = 0)("hello") perhaps(sqrt, default = 0, ensure = not_infinite)(-1)perhaps(mean, default = 0)(1:10) perhaps(mean, default = 0, allow_warning = TRUE)("hello") perhaps(sqrt, default = 0)("hello") perhaps(sqrt, default = 0, ensure = not_infinite)(-1)
Unwrap a maybe value or return a default
with_default(.m, default) from_maybe(.m, default)with_default(.m, default) from_maybe(.m, default)
.m |
A maybe value |
default |
A default value to return if the maybe value is 'Nothing' |
The unwrapped maybe value or the default value
just(1) %>% with_default(default = 0) nothing() %>% with_default(default = 0)just(1) %>% with_default(default = 0) nothing() %>% with_default(default = 0)