Hike.Option (hike v0.0.1)
The Hike.Option
module provides an implementation of the Optional data type.
It defines a struct Option
with a single field value
which can either be @none
or any other value of type t
. This implementation provides functions to work with
Optional data, including mapping, filtering, applying and many more functions to the value
inside the Optional data.
example-usage
Example Usage
iex> option = %Hike.Option{value: 42}
%Hike.Option{value: 42}
iex> Hike.Option.map(option, &(&1 * 2))
%Hike.Option{value: 84}
iex> Hike.Option.filter(option, &(rem(&1, 2) == 0))
%Hike.Option{value: 42}
iex> Hike.Option.apply(option, &(&1 + 10))
%Hike.Option{value: 52}
For more information on how to use this module, please see the documentation for the individual functions.
Link to this section Summary
Types
binder()
represent a binding(mapping) function which take no parameter and return an option of type <TR>
.
binder(t)
represent a binding(mapping) function which take a parameter of type <T>
and return an option of type <TR>
.
func()
represent a function which take no parameter and return value of type <TR>
.
func(t)
represent a function which take a parameter of type <T>
and return a value of type <TR>
.
mapper()
represent a mapping function which take no parameter and return a value of type <TR>
.
mapper(t)
represent a mapping function which take a parameter of type <T>
and return a value of type <TR>
.
Elevated data type of Option struct that represents None
state.
Elevated data type of Option struct that represents Some
state and have a value of type <T>
.
generic input type <T>
.
generic return type <TR>
.
Functions
Applies a given function to the value of an Option
struct and returns the result as a new Option
.
OR
Applies a given function stored in an option to the value of another option, and returns the result as a new option.
Transforms an Option<T>
struct with a non-nil value using a binder function that returns another Option<TR>
struct.
Applies the given function to the value of the provided option, returning a new option containing the original value if the function returns a truthy value, otherwise returning an empty option. If the provided option has no value, this function simply returns the empty option.
Returns true
if the Option
is in None
state, otherwise false
.
Returns true
if the Option
is in Some
state, otherwise false
.
Applies the given mapping function to the value inside the Option
struct and returns a new Option
struct containing the transformed value. If the input Option
struct is @none
, the function
returns a new Option
struct in none state.
## Examples
Matches on an option
and returns the result of the matching function.
Calls some_fun
with the value of the Option if the Option is in :some
state,
or calls none_fun
if the Option is in :none
state.
Creates an Option
in None
state.
Creates an Option
in Some
state
Link to this section Types
binder()
binder()
represent a binding(mapping) function which take no parameter and return an option of type <TR>
.
binder(t)
binder(t)
represent a binding(mapping) function which take a parameter of type <T>
and return an option of type <TR>
.
func()
@type func() :: (() -> tr())
func()
represent a function which take no parameter and return value of type <TR>
.
func(t)
@type func(t) :: (t -> tr())
func(t)
represent a function which take a parameter of type <T>
and return a value of type <TR>
.
mapper()
@type mapper() :: (() -> tr())
mapper()
represent a mapping function which take no parameter and return a value of type <TR>
.
mapper(t)
@type mapper(t) :: (t -> tr())
mapper(t)
represent a mapping function which take a parameter of type <T>
and return a value of type <TR>
.
option()
@type option() :: %Hike.Option{value: nil}
Elevated data type of Option struct that represents None
state.
option(t)
@type option(t) :: %Hike.Option{value: t}
Elevated data type of Option struct that represents Some
state and have a value of type <T>
.
@type t() :: any()
generic input type <T>
.
tr()
@type tr() :: any()
generic return type <TR>
.
Link to this section Functions
apply(option, func)
@spec apply(option(t()), func(t())) :: option(tr())
@spec apply(option(), func() | func(t())) :: option()
Applies a given function to the value of an Option
struct and returns the result as a new Option
.
OR
Applies a given function stored in an option to the value of another option, and returns the result as a new option.
examples
Examples
iex> option = %Option{value: 42}
iex> add_one = fn x -> x + 1 end
iex> Option.apply(option, add_one)
%Option{value: 43}
iex> none_option = %Option{value: nil}
iex> Option.apply(none_option, add_one)
%Option{value: nil}
iex> option = %Option{value: "hello"}
iex> upcase_string = fn str -> String.upcase(str) end
iex> Option.apply(option, upcase_string)
%Option{value: "HELLO"}
bind(opt, func)
@spec bind(option(t()), binder(t())) :: option(tr())
@spec bind(option(), binder() | binder(t())) :: option()
Transforms an Option<T>
struct with a non-nil value using a binder function that returns another Option<TR>
struct.
If the input Option
has a nil
value, returns a new Option
struct with a nil
value.
if you have a function that return Option<TR>
and you want to apply mapping then use bind function to avoid double elevation.
examples
Examples
iex> option = %Option{value: 42}
iex> add_one = fn x -> Option.some(x + 1) end
iex> Option.bind(option, add_one)
%Option{value: 43}
iex> Option.bind(Option.some("hello"), fn x -> Option.some(String.upcase(x)) end)
%Option{value: "HELLO"}
iex> Option.bind(Option.none() )
%Option{value: nil}
filter(opt, func)
Applies the given function to the value of the provided option, returning a new option containing the original value if the function returns a truthy value, otherwise returning an empty option. If the provided option has no value, this function simply returns the empty option.
examples
Examples
iex> Option.filter(%Option{value: 42}, fn x -> rem(x, 2) == 0 end)
%Option{value: 42}
iex> Option.filter(%Option{value: 42}, fn x -> rem(x, 2) == 1 end)
%Option{value: nil}
iex> Option.filter(%Option{value: nil}, fn x -> rem(x, 2) == 0 end)
%Option{value: nil}
iex> list_opt = Option.some([1,2,3])
iex> list_filter = fn (lst) -> Enum.count(lst) > 5 end
iex> Option.filter(list_opt, list_filter)
%Hike.Option{value: nil}
is_none?(option)
Returns true
if the Option
is in None
state, otherwise false
.
examples
Examples
iex> Option.is_none?(Option.none())
true
iex> Option.is_none?(Option.some("hello"))
false
is_some?(option)
Returns true
if the Option
is in Some
state, otherwise false
.
examples
Examples
iex> Option.is_some?(Option.some("hello"))
true
iex> Option.is_some?(Option.none())
false
map(option, func)
@spec map(option(t()), mapper(t())) :: option(tr())
@spec map(option(), mapper() | mapper(t())) :: option()
Applies the given mapping function to the value inside the Option
struct and returns a new Option
struct containing the transformed value. If the input Option
struct is @none
, the function
returns a new Option
struct in none state.
## Examples
iex> Option.map(Option.some("hello"), fn x -> String.upcase(x) end)
%Option{value: "HELLO"}
iex> Option.map(Option.none(), fn x -> String.upcase(x) end)
%Option{value: nil}
match(option, none_fun)
Matches on an option
and returns the result of the matching function.
Calls some_fun
with the value of the Option if the Option is in :some
state,
or calls none_fun
if the Option is in :none
state.
examples
Examples
iex> import Hike.Option
# Match on `some` value with a matching function
iex> match(some(10), &(&1 * 2))
# => 20
# Match on `none` value with a none-matching function
iex> match(none(), fn -> "no value" end)
# => "no value"
# Match on `some` value with a matching function and on `none` value with a none-matching function
iex> match(some("hello"), &(&1 <> " world"), fn -> "no value" end)
# => "hello world"
# Match on `none` value with a none-matching function even if a matching function is provided
iex> match(none(), &(&1 * 2), fn -> "no value" end)
# => "no value"
iex> Option.match(Option.some("hello"), fn x -> String.upcase(x) end)
"HELLO"
iex> Option.match(Option.none(), fn -> "nothing" end)
"nothing"
iex> Option.match(Option.some("hello"), fn x -> String.upcase(x) end, fn -> "nothing" end )
"HELLO"
iex> Option.match(Option.none(), fn x -> String.upcase(x) end, fn -> "nothing" end)
"nothing"
match(arg1, some_fun, none_fun)
none()
@spec none() :: option()
Creates an Option
in None
state.
examples
Examples
iex> Option.none()
%Option{value: :nil}
some(value)
Creates an Option
in Some
state
examples
Examples
iex> Option.some("hello")
%Option{value: "hello"}