Period

v0.1.0

Period v0.1.0 Period View Source

Period does represent a timeframe.

Creating a Period

A Period is a opaque type, so it’s not meant to be directly created like other structs, but you should rather use Period.new/3, Period.new!/3 or Period.from_naive/3 to create a Period.

Internally Period’s do work with timestamps (:microsecond precision) so any DateTime values extracted from a Period will be using the default Etc/UTC timezone. The caller will be responsible to retain timezones if needed.

Date.Range

A Period can be converted into a elixir core Date.Range struct by using Period.to_range/1.

Link to this section Summary

Types

boundry_state()

The states a boundry can be in

datetime()

The input types for creating a new periods

t()
timestamp()

Unix timestamp in microseconds

Functions

from_naive(from, to, opts \\ [])

Convenience function to use Period with naive datetime values

from_naive!(from, to, opts \\ [])
get_boundry_notation(p)

Get the boundry notation for both boundries

get_lower_boundry(period)

Get the lower boundry of the period

get_lower_boundry_notation(period)

Get the boundry notation for the lower boundry

get_upper_boundry(period)

Get the lower boundry of the period

get_upper_boundry_notation(period)

Get the boundry notation for the upper boundry

make_inclusive(period)

Make a period inclusive on both ends

new(lower, upper, opts \\ [])

Does create a new %Period{} struct

new!(lower, upper, opts \\ [])

Same as new/3, but does raise on errors

to_range(period)

Convert the period into a core %Date.Range{}

Link to this section Types

Link to this type boundry_state() View Source 
boundry_state() :: :included | :excluded

The states a boundry can be in

Link to this type datetime() View Source 
datetime() :: DateTime.t() | integer()

The input types for creating a new periods

Link to this type timestamp() View Source 
timestamp() :: integer()

Unix timestamp in microseconds

Link to this section Functions

Link to this function from_naive(from, to, opts \\ []) View Source 
from_naive(NaiveDateTime.t(), NaiveDateTime.t(), Keyword.t()) ::
  {:ok, t()} | {:error, term()}

Convenience function to use Period with naive datetime values.

Does simply attach the Etc/UTC timezone to the naive datetime.

Link to this function from_naive!(from, to, opts \\ []) View Source 
from_naive!(NaiveDateTime.t(), NaiveDateTime.t(), Keyword.t()) ::
  t() | no_return()
Link to this function get_boundry_notation(p) View Source 
get_boundry_notation(t()) :: {binary(), binary()}

Get the boundry notation for both boundries

Example 

iex> period = Period.new!(1517171882222330, 1517171882222335)
iex> Period.get_boundry_notation(period)
{"[", ")"}
Link to this function get_lower_boundry(period) View Source 
get_lower_boundry(t()) :: {boundry_state(), DateTime.t()}

Get the lower boundry of the period.

Does return the boundry state and the date of the boundry.

Example 

iex> period = Period.new!(1517171882222330, 1517171882222335)
iex> {:included, dt} = Period.get_lower_boundry(period)
iex> dt
#DateTime<2018-01-28 20:38:02.222330Z>
Link to this function get_lower_boundry_notation(period) View Source 
get_lower_boundry_notation(t()) :: binary()

Get the boundry notation for the lower boundry

Example 

iex> period = Period.new!(1517171882222330, 1517171882222335)
iex> Period.get_lower_boundry_notation(period)
"["

iex> period = Period.new!(1517171882222330, 1517171882222335, lower_state: :excluded)
iex> Period.get_lower_boundry_notation(period)
"("
Link to this function get_upper_boundry(period) View Source 
get_upper_boundry(t()) :: {boundry_state(), DateTime.t()}

Get the lower boundry of the period.

Does return the boundry state and the date of the boundry.

Example 

iex> period = Period.new!(1517171882222330, 1517171882222335)
iex> {:excluded, dt} = Period.get_upper_boundry(period)
iex> dt
#DateTime<2018-01-28 20:38:02.222335Z>
Link to this function get_upper_boundry_notation(period) View Source 
get_upper_boundry_notation(t()) :: binary()

Get the boundry notation for the upper boundry

Example 

iex> period = Period.new!(1517171882222330, 1517171882222335)
iex> Period.get_upper_boundry_notation(period)
")"

iex> period = Period.new!(1517171882222330, 1517171882222335, upper_state: :included)
iex> Period.get_upper_boundry_notation(period)
"]"
Link to this function make_inclusive(period) View Source 
make_inclusive(t()) :: t()

Make a period inclusive on both ends.

Example 

iex> period = Period.new!(1517171882222330, 1517171882222335)
iex> Period.make_inclusive(period)
#Period<[#DateTime<2018-01-28 20:38:02.222330Z>, #DateTime<2018-01-28 20:38:02.222334Z>]>
Link to this function new(lower, upper, opts \\ []) View Source 
new(datetime(), datetime(), Keyword.t()) :: {:ok, t()} | {:error, term()}
new(datetime(), datetime(), Keyword.t()) :: t() | no_return()

Does create a new %Period{} struct.

Can only be created from timestamps or DateTime structs, which will be converted to a timestamp. This period does not furtherconcern itself with timezones.

Timestamps need to be in :microsecond precision.

Examples 

iex> {:ok, period} = Period.new(1517171882222330, 1517171882222335)
iex> period
#Period<[#DateTime<2018-01-28 20:38:02.222330Z>, #DateTime<2018-01-28 20:38:02.222335Z>)>

iex> opts = [lower_state: :excluded, upper_state: :included]
iex> {:ok, period} = Period.new(1517171882222330, 1517171882222335, opts)
iex> period
#Period<(#DateTime<2018-01-28 20:38:02.222330Z>, #DateTime<2018-01-28 20:38:02.222335Z>]>

iex> from = DateTime.from_unix!(1517171882222330, :microsecond)
iex> to = DateTime.from_unix!(1517171882222335, :microsecond)
iex> {:ok, period} = Period.new(from, to)
iex> period
#Period<[#DateTime<2018-01-28 20:38:02.222330Z>, #DateTime<2018-01-28 20:38:02.222335Z>)>

iex> from = DateTime.from_unix!(1517171882222335, :microsecond)
iex> to = DateTime.from_unix!(1517171882222330, :microsecond)
iex> Period.new(from, to)
{:error, "In strict mode the lower date cannot be before the upper date (2018-01-28 20:38:02.222335Z, 2018-01-28 20:38:02.222330Z)."}
Link to this function new!(lower, upper, opts \\ []) View Source

Same as new/3, but does raise on errors.

Examples 

iex> Period.new!(1517171882222330, 1517171882222335)
#Period<[#DateTime<2018-01-28 20:38:02.222330Z>, #DateTime<2018-01-28 20:38:02.222335Z>)>

iex> opts = [lower_state: :excluded, upper_state: :included]
iex> Period.new!(1517171882222330, 1517171882222335, opts)
#Period<(#DateTime<2018-01-28 20:38:02.222330Z>, #DateTime<2018-01-28 20:38:02.222335Z>]>

iex> from = DateTime.from_unix!(1517171882222330, :microsecond)
iex> to = DateTime.from_unix!(1517171882222335, :microsecond)
iex> Period.new!(from, to)
#Period<[#DateTime<2018-01-28 20:38:02.222330Z>, #DateTime<2018-01-28 20:38:02.222335Z>)>

iex> from = DateTime.from_unix!(1517171882222335, :microsecond)
iex> to = DateTime.from_unix!(1517171882222330, :microsecond)
iex> Period.new!(from, to)
** (ArgumentError) In strict mode the lower date cannot be before the upper date (2018-01-28 20:38:02.222335Z, 2018-01-28 20:38:02.222330Z).
Link to this function to_range(period) View Source 
to_range(t()) :: {:ok, Date.Range.t()} | {:error, term()}

Convert the period into a core %Date.Range{}.

Does only work with periods, which are inclusive on both boundries as that’s a restriction of Date.Range structs.