Kronos v1.0.0 Kronos

Kronos is a tool to facilitate the manipulation of dates (via Timestamps). This library use the seconds as a reference.

iex> import Kronos
...> use Kronos.Infix
...> {:ok, t} = new({2010, 12, 20}, {0, 0, 0})
...> r = t + ~t(2)day + ~t(3)hour + ~t(10)minute + ~t(13)second
...> Kronos.to_string(r)
"2010-12-22 03:10:13Z"

The measures references are :

Kronos.second
Kronos.minute
Kronos.second
Kronos.fifteen_minutes
Kronos.half_hour
Kronos.hour
Kronos.half_day
Kronos.day
Kronos.week
Kronos.month This measure is an approximation (30 days)
Kronos.year This measure is an approximation (365 days)

Unsafe values

Kronos.month and Kronos.year are unsafe, they represents a “approximation” of a month or a year. You should never use it with Kronos.truncate/2, Kronos.next/2 and Kronos.pred/2 (and of course as a precision flag).

Summary

Types

datetime_t()

This type represents a couple date-time

day_of_week()

This type represents the day of the week

duration()

This type represents a range between two timestamp

metric()

This type represents a metric_type

non_neg_triplet()

This type represents a triplet of non negative values

result()

This type represents a failable result

t()

This type represents a typed timestamp

week_t()

This type represents a specific week type

Functions

after?(a, b, precision \\ second())

Kronos.after?(a, b) check if a is later in time than b

before?(a, b, precision \\ second())

Kronos.before?(a, b) check if a is earlier in time than b

day()

References the subtype day

day(value)

Builds a value into the subtype day

day_of_week(ts)

Returns the day of the week from a Kronos.t. 0 for Monday, 6 for Sunday

day_of_week_internal(ts)

Returns the day of the week from a Kronos.t. 0 for Monday, 6 for Sunday

days_in(year, month)

Returns a Kronos.t with the number of days in a month, the month is referenced by year and month (non neg integer)

diff(duration)

Returns the difference (always positive) between to members of a duration

equivalent?(a, b, precision \\ second())

Kronos.equivalent?(a, b) check if a is at the same moment of b

fifteen_minutes()

References the subtype fifteen_minutes

fifteen_minutes(value)

Builds a value into the subtype fifteen_minutes

from_datetime(datetime)

Converts a DateTime.t into a Kronos.t

half_day()

References the subtype half_day

half_day(value)

Builds a value into the subtype half_day

half_hour()

References the subtype half_hour

half_hour(value)

Builds a value into the subtype half_hour

hour()

References the subtype hour

hour(value)

Builds a value into the subtype hour

hours_of(timestamp)

Returns the hours (relatives) of a timestamp

include?(a, list)

Check if a Kronos.t is include into a Kronos.duration

laps(list)

Creates a duration between two Kronos.t. This duration is a Mizur.Range.range

laps(a, b)

Creates a duration between two Kronos.t. This duration is a Mizur.Range.range

leap_year?(year)

Returns if the given year is a leap year

minute()

References the subtype minute

minute(value)

Builds a value into the subtype minute

minutes_of(timestamp)

Returns the minutes (relatives) of a timestamp

month()

References the subtype month

month(value)

Builds a value into the subtype month

new(timestamp)

Converts an erlang datetime representation to a Kronos.result

new(date, time)

Converts two tuple (date, time) to a Kronos.result

new!(input)

Same of Kronos.new/1 but raise an ArgumentError if the timestamp creation failed

new!(date, time)

Same of Kronos.new/2 but raise an ArgumentError if the timestamp creation failed

next(t, list)

Jump to the next value of a type. For example next(Kronos.day, of: Kronos.new({2017, 10, 10}, {22, 12, 12})) give the date : 2017-10-11, 0:0:0

now()

Returns the current timestamp (in a Kronos.t)

one(arg)

overlap?(a, list)

Checks that two durations have an intersection

pred(t, list)

Jump to the pred value of a type. For example next(Kronos.day, of: Kronos.new({2017, 10, 10}, {22, 12, 12})) give the date : 2017-10-09, 0:0:0

second()

References the subtype second

second(value)

Builds a value into the subtype second

seconds_of(timestamp)

Returns the seconds (relatives) of a timestamp

to_datetime(timestamp)

Converts a Kronos.t to a DateTime.t, the result is wrapped into {:ok, value} or {:error, reason}

to_datetime!(timestamp)

Converts a Kronos.t to a DateTime.t. Raise an ArgumentError if the timestamp is not valid

to_integer(timestamp)

Returns the wrapped values (into a Kronos.t) as an integer in second. This function is mainly used to convert Kronos.t toDateTime.t

to_string(value)

Convert a Kronos.t into a string, use the DateTime inspect

truncate(timestamp, list)

Rounds the given timestamp (timestamp) to the given type (at)

week()

References the subtype week

week(value)

Builds a value into the subtype week

year()

References the subtype year

year(value)

Builds a value into the subtype year

Types

datetime_t()

datetime_t() :: {non_neg_triplet, non_neg_triplet}

This type represents a couple date-time

day_of_week()

day_of_week() :: :mon | :tue | :wed | :thu | :fri | :sat | :sun

This type represents the day of the week

duration()

duration() :: Mizur.Range.range

This type represents a range between two timestamp

metric()

metric() :: Mizur.metric_type | week_t

This type represents a metric_type

non_neg_triplet()

non_neg_triplet() :: {non_neg_integer, non_neg_integer, non_neg_integer}

This type represents a triplet of non negative values

result()

result() :: {:ok, t} | {:error, atom}

This type represents a failable result

t()

t() :: Mizur.typed_value

This type represents a typed timestamp

week_t()

week_t() :: {t, day_of_week}

This type represents a specific week type

Functions

after?(a, b, precision \\ second())

after?(t, t, metric) :: boolean

Kronos.after?(a, b) check if a is later in time than b.

iex> {a, b} = {Kronos.new!(2), Kronos.new!(1)}
...> Kronos.after?(a, b)
true

You can specify a precision, to ignore minutes, hours or days. (By passing a precision, both parameters will be truncated via Kronos.truncate/2).

before?(a, b, precision \\ second())

before?(t, t, metric) :: boolean

Kronos.before?(a, b) check if a is earlier in time than b.

iex> {a, b} = {Kronos.new!(2), Kronos.new!(1)}
...> Kronos.before?(b, a)
true

You can specify a precision, to ignore minutes, hours or days. (By passing a precision, both parameters will be truncated via Kronos.truncate/2).

day()

References the subtype day

day(value)

Builds a value into the subtype day

day_of_week(ts)

day_of_week(t) :: day_of_week

Returns the day of the week from a Kronos.t. 0 for Monday, 6 for Sunday.

iex> a = KronosTest.mock(:day, 1970, 1, 1, 12, 10, 11)
...> Kronos.day_of_week(a)
:thu

iex> a = KronosTest.mock(:day, 2017, 4, 29, 0, 3, 11)
...> Kronos.day_of_week(a)
:sat

day_of_week_internal(ts)

day_of_week_internal(t) :: 0..6

Returns the day of the week from a Kronos.t. 0 for Monday, 6 for Sunday.

iex> a = KronosTest.mock(:day, 1970, 1, 1, 12, 10, 11)
...> Kronos.day_of_week_internal(a)
3

iex> a = KronosTest.mock(:day, 2017, 4, 29, 0, 3, 11)
...> Kronos.day_of_week_internal(a)
5

days_in(year, month)

days_in(non_neg_integer, 1..12) :: t

Returns a Kronos.t with the number of days in a month, the month is referenced by year and month (non neg integer).

iex> Kronos.days_in(2004, 2)
Kronos.day(29)

iex> Kronos.days_in(2005, 2)
Kronos.day(28)

iex> Kronos.days_in(2005, 1)
Kronos.day(31)

iex> Kronos.days_in(2001, 4)
Kronos.day(30)

diff(duration)

diff(duration) :: t

Returns the difference (always positive) between to members of a duration.

iex> duration = KronosTest.mock(:duration, 2017, 2018)
...> Mizur.from((Kronos.diff(duration)), to: Kronos.day)
Kronos.day(365)

equivalent?(a, b, precision \\ second())

equivalent?(t, t, metric) :: boolean

Kronos.equivalent?(a, b) check if a is at the same moment of b.

iex> {a, b} = {Kronos.new!(2), Kronos.new!(1)}
...> Kronos.equivalent?(b, a, Kronos.hour())
true

You can specify a precision, to ignore minutes, hours or days. (By passing a precision, both parameters will be truncated via Kronos.truncate/2).

fifteen_minutes()

References the subtype fifteen_minutes

fifteen_minutes(value)

Builds a value into the subtype fifteen_minutes

from_datetime(datetime)

from_datetime(DateTime.t) :: t

Converts a DateTime.t into a Kronos.t

half_day()

References the subtype half_day

half_day(value)

Builds a value into the subtype half_day

half_hour()

References the subtype half_hour

half_hour(value)

Builds a value into the subtype half_hour

hour()

References the subtype hour

hour(value)

Builds a value into the subtype hour

hours_of(timestamp)

hours_of(t) :: integer

Returns the hours (relatives) of a timestamp.

iex> a = KronosTest.mock(:day, 2017, 10, 10, 23, 45, 53)
...> Kronos.hours_of(a)
23

iex> a = KronosTest.mock(:day, 1903, 10, 10, 13, 22, 7)
...> Kronos.hours_of(a)
13

include?(a, list)

include?(t, [{:in, duration}]) :: boolean

Check if a Kronos.t is include into a Kronos.duration.

iex> duration = KronosTest.mock(:duration, 2017, 2018)
...> a = KronosTest.mock(:day, 2015, 12, 10)
...> b = KronosTest.mock(:day, 2017, 5, 10)
...> {Kronos.include?(a, in: duration), Kronos.include?(b, in: duration)}
{false, true}

laps(list)

laps([from: t, to: t]) :: duration

Creates a duration between two Kronos.t. This duration is a Mizur.Range.range.

iex> a = Kronos.new!(1)
...> b = Kronos.new!(100)
...> [from: a, to: b] |> Kronos.laps
Mizur.Range.new(Kronos.new!(1), Kronos.new!(100))

laps(a, b)

laps(t, t) :: duration

Creates a duration between two Kronos.t. This duration is a Mizur.Range.range.

iex> a = Kronos.new!(1)
...> b = Kronos.new!(100)
...> Kronos.laps(a, b)
Mizur.Range.new(Kronos.new!(1), Kronos.new!(100))

leap_year?(year)

leap_year?(non_neg_integer) :: boolean

Returns if the given year is a leap year.

iex> Kronos.leap_year?(2004)
true 

iex> Kronos.leap_year?(2017)
false

minute()

References the subtype minute

minute(value)

Builds a value into the subtype minute

minutes_of(timestamp)

minutes_of(t) :: integer

Returns the minutes (relatives) of a timestamp.

iex> a = KronosTest.mock(:day, 2017, 10, 10, 23, 45, 53)
...> Kronos.minutes_of(a)
45

iex> a = KronosTest.mock(:day, 1903, 10, 10, 13, 22, 7)
...> Kronos.minutes_of(a)
22

month()

References the subtype month

month(value)

Builds a value into the subtype month

new(timestamp)

new(integer) :: result

new(datetime_t) :: result

Converts an erlang datetime representation to a Kronos.result

new(date, time)

new(non_neg_triplet, non_neg_triplet) :: result

Converts two tuple (date, time) to a Kronos.result

new!(input)

new!(integer | datetime_t) :: t

Same of Kronos.new/1 but raise an ArgumentError if the timestamp creation failed.

new!(date, time)

new!(non_neg_triplet, non_neg_triplet) :: t

Same of Kronos.new/2 but raise an ArgumentError if the timestamp creation failed.

next(t, list)

next(metric, [{:of, t}]) :: t

Jump to the next value of a type. For example next(Kronos.day, of: Kronos.new({2017, 10, 10}, {22, 12, 12})) give the date : 2017-10-11, 0:0:0.

iex> t = KronosTest.mock(:day, 2017, 10, 10)
...> Kronos.next(Kronos.day, of: t)
KronosTest.mock(:day, 2017, 10, 11)

now()

now() :: t

Returns the current timestamp (in a Kronos.t)

one(arg)

overlap?(a, list)

overlap?(duration, [{:with, duration}]) :: boolean

Checks that two durations have an intersection.

iex> durationA = KronosTest.mock(:duration, 2016, 2018)
...> durationB = KronosTest.mock(:duration, 2017, 2019)
...> Kronos.overlap?(durationA, with: durationB)
true

pred(t, list)

pred(metric, [{:of, t}]) :: t

Jump to the pred value of a type. For example next(Kronos.day, of: Kronos.new({2017, 10, 10}, {22, 12, 12})) give the date : 2017-10-09, 0:0:0.

iex> t = KronosTest.mock(:day, 2017, 10, 10)
...> Kronos.pred(Kronos.day, of: t)
KronosTest.mock(:day, 2017, 10, 9)

second()

References the subtype second

second(value)

Builds a value into the subtype second

seconds_of(timestamp)

seconds_of(t) :: integer

Returns the seconds (relatives) of a timestamp.

iex> a = KronosTest.mock(:day, 2017, 10, 10, 23, 45, 53)
...> Kronos.seconds_of(a)
53

iex> a = KronosTest.mock(:day, 1903, 10, 10, 13, 22, 7)
...> Kronos.seconds_of(a)
7

to_datetime(timestamp)

to_datetime(t) :: {:ok, DateTime.t} | {:error, atom}

Converts a Kronos.t to a DateTime.t, the result is wrapped into {:ok, value} or {:error, reason}.

iex> ts = 1493119897
...> a  = Kronos.new!(ts)
...> b  = DateTime.from_unix(1493119897)
...> Kronos.to_datetime(a) == b 
true

to_datetime!(timestamp)

to_datetime!(t) :: DateTime.t

Converts a Kronos.t to a DateTime.t. Raise an ArgumentError if the timestamp is not valid.

iex> ts = 1493119897
...> a  = Kronos.new!(ts)
...> b  = DateTime.from_unix!(1493119897)
...> Kronos.to_datetime!(a) == b 
true

to_integer(timestamp)

to_integer(t) :: integer

Returns the wrapped values (into a Kronos.t) as an integer in second. This function is mainly used to convert Kronos.t toDateTime.t.

iex> x = Kronos.new!(2000)
...> Kronos.to_integer(x)
2000

to_string(value)

to_string(t) :: String.t

Convert a Kronos.t into a string, use the DateTime inspect.

truncate(timestamp, list)

truncate(t, [{:at, metric}]) :: t

Rounds the given timestamp (timestamp) to the given type (at).

iex> ts = Kronos.new!({2017, 10, 24}, {23, 12, 07})
...> Kronos.truncate(ts, at: Kronos.hour())
Kronos.new!({2017, 10, 24}, {23, 0, 0})

For example :

truncate of 2017/10/24 23:12:07 at minute gives : 2017/10/24 23:12:00
truncate of 2017/10/24 23:12:07 at hour gives : 2017/10/24 23:00:00
truncate of 2017/10/24 23:12:07 at day gives : 2017/10/24 00:00:00

week()

References the subtype week

week(value)

week([{:start, day_of_week}]) :: week_t

Builds a value into the subtype week

year()

References the subtype year

year(value)

Builds a value into the subtype year