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>.

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

@type binder() :: (() -> option(tr()))

binder() represent a binding(mapping) function which take no parameter and return an option of type <TR>.

@type binder(t) :: (t -> option(tr()))

binder(t) represent a binding(mapping) function which take a parameter of type <T> and return an option of type <TR>.

@type func() :: (() -> tr())

func() represent a function which take no parameter and return value of type <TR>.

@type func(t) :: (t -> tr())

func(t) represent a function which take a parameter of type <T> and return a value of type <TR>.

@type mapper() :: (() -> tr())

mapper() represent a mapping function which take no parameter and return a value of type <TR>.

@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>.

@type option() :: %Hike.Option{value: nil}

Elevated data type of Option struct that represents None state.

@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>.

@type tr() :: any()

generic return type <TR>.

Link to this section Functions

Link to this function

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"}
Link to this function

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}
Link to this function

filter(opt, func)

@spec filter(option(), func()) :: option()
@spec filter(option(t()), func(t())) :: option(tr())

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}
Link to this function

is_none?(option)

@spec is_none?(option() | option(t())) :: boolean()

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
Link to this function

is_some?(option)

@spec is_some?(option() | option(t())) :: boolean()

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
Link to this function

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}
Link to this function

match(option, none_fun)

@spec match(option(), func()) :: tr()
@spec match(option(t()), func(t())) :: tr()

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"
Link to this function

match(arg1, some_fun, none_fun)

@spec match(option(t()) | option(), func(t()), func()) :: tr()
@spec none() :: option()

Creates an Option in None state.

examples

Examples

iex> Option.none()
%Option{value: :nil}
@spec some(t()) :: option(t())

Creates an Option in Some state

examples

Examples

iex> Option.some("hello")
%Option{value: "hello"}