GoodTimes v1.1.1 GoodTimes

Convenient and expressive functions dealing with dates and times.

This is the core module of the GoodTimes library. For other modules and their functionality, see Associated modules below.

Unless explicitly stated, all functions operate on and return an Erlang datetime based on the Coordinated Universal Time (UTC).

Functions overview

The following functions are available for each time unit (second, minute, hour, day, week, month, or year); all return a datetime that is offset the specified amount of time units.

  • <time_units>_after/2
  • <time_units>_before/2
  • <time_units>_from_now/1
  • <time_units>_ago/1

You can use the following functions when only adjusting the datetime by a single time unit.

  • a_<time_unit>_after/1
  • a_<time_unit>_before/1
  • a_<time_unit>_from_now/0
  • a_<time_unit>_ago/0

In addition, now/0 and at/2 are included for convenience.

  • now/0 - returns the current datetime
  • at/2 - merges a given date or datetime with a time

Examples

iex> now
{{2015, 2, 27}, {18, 30, 45}}
iex> an_hour_ago
{{2015, 2, 27}, {17, 30, 45}}
iex> a_month_before {{2016, 3, 31}, {9, 30, 0}}
{{2016, 2, 29}, {9, 30, 0}}
iex> 2 |> weeks_from_now |> at {12, 15, 0}
{{2015, 3, 13}, {12, 15, 0}}

Known limitations

As the entire library builds upon Erlang’s calendar module, dates before year 0 are not supported.

Associated modules

Aside from the core module, the GoodTimes library consistes of these modules.

Summary

Functions

Returns the UTC date and time a day after the given datetime

Returns the UTC date and time a day ago

Returns the UTC date and time a day before the given datetime

Returns the UTC date and time a day from now

Returns the UTC date and time a minute after the given datetime

Returns the UTC date and time a minute ago

Returns the UTC date and time a minute before the given datetime

Returns the UTC date and time a minute from now

Returns the UTC date and time a month after the given datetime

Returns the UTC date and time a month ago

Returns the UTC date and time a month before the given datetime

Returns the UTC date and time a month from now

Returns the UTC date and time a second after the given datetime

Returns the UTC date and time a second ago

Returns the UTC date and time a second before the given datetime

Returns the UTC date and time a second from now

Returns the UTC date and time a week after the given datetime

Returns the UTC date and time a week ago

Returns the UTC date and time a week before the given datetime

Returns the UTC date and time a week from now

Returns the UTC date and time a year after the given datetime

Returns the UTC date and time a year ago

Returns the UTC date and time a year before the given datetime

Returns the UTC date and time a year from now

Returns the UTC date and time an hour after the given datetime

Returns the UTC date and time an hour ago

Returns the UTC date and time an hour before the given datetime

Returns the UTC date and time an hour from now

Merges the date from the given date or datetime with the given time

Returns the UTC date and time the specified days after the given datetime

Returns the UTC date and time the specified days ago

Returns the UTC date and time the specified days before the given datetime

Returns the UTC date and time the specified days from now

Returns the UTC date and time the specified hours after the given datetime

Returns the UTC date and time the specified hours ago

Returns the UTC date and time the specified hours before the given datetime

Returns the UTC date and time the specified hours from now

Returns the UTC date and time the specified minutes after the given datetime

Returns the UTC date and time the specified minutes ago

Returns the UTC date and time the specified minutes before the given datetime

Returns the UTC date and time the specified minutes from now

Returns the UTC date and time the specified months after the given datetime

Returns the UTC date and time the specified months ago

Returns the UTC date and time the specified months before the given datetime

Returns the UTC date and time the specified months from now

Returns the current UTC time as a datetime

Returns the UTC date and time the specified seconds after the given datetime

Returns the UTC date and time the specified seconds ago

Returns the UTC date and time the specified seconds before the given datetime

Returns the UTC date and time the specified seconds from now

Returns the UTC date and time the specified weeks after the given datetime

Returns the UTC date and time the specified weeks ago

Returns the UTC date and time the specified weeks before the given datetime

Returns the UTC date and time the specified weeks from now

Returns the UTC date and time the specified years after the given datetime

Returns the UTC date and time the specified years ago

Returns the UTC date and time the specified years before the given datetime

Returns the UTC date and time the specified years from now

Types

date :: {year, month, day}
day :: 1..31
hour :: 0..23
minute :: 0..59
month :: 1..12
second :: 0..59
year :: non_neg_integer

Functions

a_day_after(datetime)

Specs

a_day_after(datetime) :: datetime

Returns the UTC date and time a day after the given datetime.

Examples

iex> a_day_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 28}, {18, 30, 45}}
a_day_ago()

Specs

a_day_ago :: datetime

Returns the UTC date and time a day ago.

Examples

iex> a_day_ago
{{2015, 2, 26}, {18, 30, 45}}
a_day_before(datetime)

Specs

a_day_before(datetime) :: datetime

Returns the UTC date and time a day before the given datetime.

Examples

iex> a_day_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 26}, {18, 30, 45}}
a_day_from_now()

Specs

a_day_from_now :: datetime

Returns the UTC date and time a day from now.

Examples

iex> a_day_from_now
{{2015, 2, 28}, {18, 30, 45}}
a_minute_after(datetime)

Specs

a_minute_after(datetime) :: datetime

Returns the UTC date and time a minute after the given datetime.

Examples

iex> a_minute_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 31, 45}}
a_minute_ago()

Specs

a_minute_ago :: datetime

Returns the UTC date and time a minute ago.

Examples

iex> a_minute_ago
{{2015, 2, 27}, {18, 29, 45}}
a_minute_before(datetime)

Specs

a_minute_before(datetime) :: datetime

Returns the UTC date and time a minute before the given datetime.

Examples

iex> a_minute_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 29, 45}}
a_minute_from_now()

Specs

a_minute_from_now :: datetime

Returns the UTC date and time a minute from now.

Examples

iex> a_minute_from_now
{{2015, 2, 27}, {18, 31, 45}}
a_month_after(datetime)

Specs

a_month_after(datetime) :: datetime

Returns the UTC date and time a month after the given datetime.

Examples

iex> a_month_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 3, 27}, {18, 30, 45}}
a_month_ago()

Specs

a_month_ago :: datetime

Returns the UTC date and time a month ago.

Examples

iex> a_month_ago
{{2015, 1, 27}, {18, 30, 45}}
a_month_before(datetime)

Specs

a_month_before(datetime) :: datetime

Returns the UTC date and time a month before the given datetime.

Examples

iex> a_month_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 1, 27}, {18, 30, 45}}
a_month_from_now()

Specs

a_month_from_now :: datetime

Returns the UTC date and time a month from now.

Examples

iex> a_month_from_now
{{2015, 3, 27}, {18, 30, 45}}
a_second_after(datetime)

Specs

a_second_after(datetime) :: datetime

Returns the UTC date and time a second after the given datetime.

Examples

iex> a_second_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 30, 46}}
a_second_ago()

Specs

a_second_ago :: datetime

Returns the UTC date and time a second ago.

iex> a_second_ago
{{2015, 2, 27}, {18, 30, 44}}
a_second_before(datetime)

Specs

a_second_before(datetime) :: datetime

Returns the UTC date and time a second before the given datetime.

Examples

iex> a_second_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 30, 44}}
a_second_from_now()

Specs

a_second_from_now :: datetime

Returns the UTC date and time a second from now.

Examples

iex> a_second_from_now
{{2015, 2, 27}, {18, 30, 46}}
a_week_after(datetime)

Specs

a_week_after(datetime) :: datetime

Returns the UTC date and time a week after the given datetime.

Examples

iex> a_week_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 3, 6}, {18, 30, 45}}
a_week_ago()

Specs

a_week_ago :: datetime

Returns the UTC date and time a week ago.

Examples

iex> a_week_ago
{{2015, 2, 20}, {18, 30, 45}}
a_week_before(datetime)

Specs

a_week_before(datetime) :: datetime

Returns the UTC date and time a week before the given datetime.

Examples

iex> a_week_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 20}, {18, 30, 45}}
a_week_from_now()

Specs

a_week_from_now :: datetime

Returns the UTC date and time a week from now.

Examples

iex> a_week_from_now
{{2015, 3, 6}, {18, 30, 45}}
a_year_after(datetime)

Specs

a_year_after(datetime) :: datetime

Returns the UTC date and time a year after the given datetime.

Examples

iex> a_year_after({{2015, 2, 27}, {18, 30, 45}})
{{2016, 2, 27}, {18, 30, 45}}
a_year_ago()

Specs

a_year_ago :: datetime

Returns the UTC date and time a year ago.

Examples

iex> a_year_ago
{{2014, 2, 27}, {18, 30, 45}}
a_year_before(datetime)

Specs

a_year_before(datetime) :: datetime

Returns the UTC date and time a year before the given datetime.

Examples

iex> a_year_before({{2015, 2, 27}, {18, 30, 45}})
{{2014, 2, 27}, {18, 30, 45}}
a_year_from_now()

Specs

a_year_from_now :: datetime

Returns the UTC date and time a year from now.

Examples

iex> a_year_from_now
{{2016, 2, 27}, {18, 30, 45}}
an_hour_after(datetime)

Specs

an_hour_after(datetime) :: datetime

Returns the UTC date and time an hour after the given datetime.

Examples

iex> an_hour_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {19, 30, 45}}
an_hour_ago()

Specs

an_hour_ago :: datetime

Returns the UTC date and time an hour ago.

Examples

iex> an_hour_ago
{{2015, 2, 27}, {17, 30, 45}}
an_hour_before(datetime)

Specs

an_hour_before(datetime) :: datetime

Returns the UTC date and time an hour before the given datetime.

Examples

iex> an_hour_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {17, 30, 45}}
an_hour_from_now()

Specs

an_hour_from_now :: datetime

Returns the UTC date and time an hour from now.

Examples

iex> an_hour_from_now
{{2015, 2, 27}, {19, 30, 45}}
at(date_or_datetime, time)

Specs

Merges the date from the given date or datetime with the given time.

Examples

iex> now |> at {10, 30, 15}
{{2015, 2, 27}, {10, 30, 15}}
iex> {2015, 2, 27} |> at {10, 30, 15}
{{2015, 2, 27}, {10, 30, 15}}
days_after(days, datetime)

Specs

days_after(integer, datetime) :: datetime

Returns the UTC date and time the specified days after the given datetime.

Examples

iex> 3 |> days_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 3, 2}, {18, 30, 45}}
days_ago(days)

Specs

days_ago(integer) :: datetime

Returns the UTC date and time the specified days ago.

Examples

iex> 7 |> days_ago
{{2015, 2, 20}, {18, 30, 45}}
days_before(days, datetime)

Specs

days_before(integer, datetime) :: datetime

Returns the UTC date and time the specified days before the given datetime.

Examples

iex> 3 |> days_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 24}, {18, 30, 45}}
days_from_now(days)

Specs

days_from_now(integer) :: datetime

Returns the UTC date and time the specified days from now.

Examples

iex> 2 |> days_from_now
{{2015, 3, 1}, {18, 30, 45}}
hours_after(hours, datetime)

Specs

hours_after(integer, datetime) :: datetime

Returns the UTC date and time the specified hours after the given datetime.

Examples

iex> 15 |> hours_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 28}, {9, 30, 45}}
hours_ago(hours)

Specs

hours_ago(integer) :: datetime

Returns the UTC date and time the specified hours ago.

Examples

iex> 2 |> hours_ago
{{2015, 2, 27}, {16, 30, 45}}
hours_before(hours, datetime)

Specs

hours_before(integer, datetime) :: datetime

Returns the UTC date and time the specified hours before the given datetime.

Examples

iex> 15 |> hours_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {3, 30, 45}}
hours_from_now(hours)

Specs

hours_from_now(integer) :: datetime

Returns the UTC date and time the specified hours from now.

Examples

iex> 6 |> hours_from_now
{{2015, 2, 28}, {0, 30, 45}}
minutes_after(minutes, datetime)

Specs

minutes_after(integer, datetime) :: datetime

Returns the UTC date and time the specified minutes after the given datetime.

Examples

iex> 15 |> minutes_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 45, 45}}
minutes_ago(minutes)

Specs

minutes_ago(integer) :: datetime

Returns the UTC date and time the specified minutes ago.

Examples

iex> 5 |> minutes_ago
{{2015, 2, 27}, {18, 25, 45}}
minutes_before(minutes, datetime)

Specs

minutes_before(integer, datetime) :: datetime

Returns the UTC date and time the specified minutes before the given datetime.

Examples

iex> 15 |> minutes_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 15, 45}}
minutes_from_now(minutes)

Specs

minutes_from_now(integer) :: datetime

Returns the UTC date and time the specified minutes from now.

Examples

iex> 10 |> minutes_from_now
{{2015, 2, 27}, {18, 40, 45}}
months_after(months, arg)

Specs

months_after(integer, datetime) :: datetime

Returns the UTC date and time the specified months after the given datetime.

Examples

iex> 3 |> months_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 5, 27}, {18, 30, 45}}
months_ago(months)

Specs

months_ago(integer) :: datetime

Returns the UTC date and time the specified months ago.

Examples

iex> 2 |> months_ago
{{2014, 12, 27}, {18, 30, 45}}
months_before(months, datetime)

Specs

months_before(integer, datetime) :: datetime

Returns the UTC date and time the specified months before the given datetime.

Examples

iex> 3 |> months_before({{2015, 2, 27}, {18, 30, 45}})
{{2014, 11, 27}, {18, 30, 45}}
months_from_now(months)

Specs

months_from_now(integer) :: datetime

Returns the UTC date and time the specified months from now.

Examples

iex> 2 |> months_from_now
{{2015, 4, 27}, {18, 30, 45}}
now()

Specs

now :: datetime

Returns the current UTC time as a datetime.

Examples

iex> now
{{2015, 2, 27}, {18, 30, 45}}
seconds_after(seconds, datetime)

Specs

seconds_after(integer, datetime) :: datetime

Returns the UTC date and time the specified seconds after the given datetime.

Examples

iex> 15 |> seconds_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 31, 0}}
seconds_ago(seconds)

Specs

seconds_ago(integer) :: datetime

Returns the UTC date and time the specified seconds ago.

Examples

iex> 20 |> seconds_ago
{{2015, 2, 27}, {18, 30, 25}}
seconds_before(seconds, datetime)

Specs

seconds_before(integer, datetime) :: datetime

Returns the UTC date and time the specified seconds before the given datetime.

Examples

iex> 15 |> seconds_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 27}, {18, 30, 30}}
seconds_from_now(seconds)

Specs

seconds_from_now(integer) :: datetime

Returns the UTC date and time the specified seconds from now.

Examples

iex> 15 |> seconds_from_now
{{2015, 2, 27}, {18, 31, 0}}
weeks_after(weeks, datetime)

Specs

weeks_after(integer, datetime) :: datetime

Returns the UTC date and time the specified weeks after the given datetime.

Examples

iex> 3 |> weeks_after({{2015, 2, 27}, {18, 30, 45}})
{{2015, 3, 20}, {18, 30, 45}}
weeks_ago(weeks)

Specs

weeks_ago(integer) :: datetime

Returns the UTC date and time the specified weeks ago.

Examples

iex> 2 |> weeks_ago
{{2015, 2, 13}, {18, 30, 45}}
weeks_before(weeks, datetime)

Specs

weeks_before(integer, datetime) :: datetime

Returns the UTC date and time the specified weeks before the given datetime.

Examples

iex> 3 |> weeks_before({{2015, 2, 27}, {18, 30, 45}})
{{2015, 2, 6}, {18, 30, 45}}
weeks_from_now(weeks)

Specs

weeks_from_now(integer) :: datetime

Returns the UTC date and time the specified weeks from now.

Examples

iex> 2 |> weeks_from_now
{{2015, 3, 13}, {18, 30, 45}}
years_after(years, datetime)

Specs

years_after(integer, datetime) :: datetime

Returns the UTC date and time the specified years after the given datetime.

Examples

iex> 3 |> years_after({{2015, 2, 27}, {18, 30, 45}})
{{2018, 2, 27}, {18, 30, 45}}
years_ago(years)

Specs

years_ago(integer) :: datetime

Returns the UTC date and time the specified years ago.

Examples

iex> 2 |> years_ago
{{2013, 2, 27}, {18, 30, 45}}
years_before(years, datetime)

Specs

years_before(integer, datetime) :: datetime

Returns the UTC date and time the specified years before the given datetime.

Examples

iex> 3 |> years_before({{2015, 2, 27}, {18, 30, 45}})
{{2012, 2, 27}, {18, 30, 45}}
years_from_now(years)

Specs

years_from_now(integer) :: datetime

Returns the UTC date and time the specified years from now.

Examples

iex> 2 |> years_from_now
{{2017, 2, 27}, {18, 30, 45}}