tempo/period

Functions to use with the Period type in Tempo. Periods represent a positive range of dates or datetimes.

Example

import tempo/period
import tempo/date

pub fn get_days_between(datetime1, datetime2) {
  period.from_datetimes(start: datetime1, end: datetime2)
  |> period.as_days
  // -> 11
}

import tempo/period
import tempo/date

pub fn get_every_friday_between(date1, date2) {
  period.from_days(date1, date2)
  |> period.comprising_dates
  |> list.filter(fn(date) { 
    date.to_day_of_week(date) == date.Fri
  })
  // -> ["2024-06-21", "2024-06-28", "2024-07-05"]
}

Calendar and range of valid dates

The dates bounding a period are proleptic Gregorian calendar dates, and the functions that walk a period by calendar unit (comprising_dates, comprising_months, from_month) use Gregorian month lengths and the Gregorian leap year rule. as_days and as_seconds are plain elapsed counts and do not depend on the calendar.

Periods are built from dates and datetimes, so they inherit the years 1000 through 9999 construction range described in the tempo/date module docs.

Types

Unit

</>

pub type Unit {
  Year
  Month
  Week
  Day
  Hour
  Minute
  Second
  Millisecond
  Microsecond
}

Constructors

```
Year
```
```
Month
```
```
Week
```
```
Day
```
```
Hour
```
```
Minute
```
```
Second
```
```
Millisecond
```
```
Microsecond
```

Values

as_days

</>

pub fn as_days(period: tempo.Period) -> Int

Returns the number of days in the period.

Examples

period.new(
  start: naive_datetime.literal("2024-06-13T15:47:00"),
  end: naive_datetime.literal("2024-06-21T07:16:12"),
)
|> period.as_days
// -> 7

as_days_fractional

</>

pub fn as_days_fractional(period: tempo.Period) -> Float

Returns the number of days in the period.

Does not account for leap seconds like the rest of the package.

Examples

period.new(
  start: naive_datetime.literal("2024-06-13T15:47:00"),
  end: naive_datetime.literal("2024-06-21T07:16:12"),
)
|> period.as_days_fractional
// -> 7.645277777777778

as_duration

</>

pub fn as_duration(period: tempo.Period) -> duration.Duration

Returns a period as a duration, losing the context of the start and end datetimes.

Example

period.new(
  start: naive_datetime.literal("2024-06-13T15:47:00"),
  end: naive_datetime.literal("2024-06-21T07:16:12"),
)
|> period.as_duration
|> duration.as_weeks
// -> 1

as_seconds

</>

pub fn as_seconds(period: tempo.Period) -> Int

Returns the number of seconds in the period.

Does not account for leap seconds like the rest of the package.

Examples

period.new(
  start: naive_datetime.literal("2024-06-13T07:16:32"),
  end: naive_datetime.literal("2024-06-13T07:16:12"),
)
|> period.as_seconds
// -> 20

comprising_dates

</>

pub fn comprising_dates(period: tempo.Period) -> List(tempo.Date)

Returns a list over all the proleptic Gregorian calendar dates in the period, inclusive of the dates of both the start and end datetimes and ignoring the offset.

Examples

period.new_naive(
  start: naive_datetime.literal("2024-06-19T23:59:59-04:00"),
  end: naive_datetime.literal("2024-06-21T00:16:12+01:00"),
)
|> period.comprising_dates
// -> [
//   date.literal("2024-06-19"),
//   date.literal("2024-06-20"),
//   date.literal("2024-06-21"),
// ]

period.from_month(tempo.MonthYear(tempo.Feb, 2024))
|> period.comprising_dates
// -> [
//   date.literal("2024-02-01"),
//   ...
//   date.literal("2024-02-29"),
// ]

comprising_months

</>

pub fn comprising_months(
  period: tempo.Period,
) -> List(tempo.MonthYear)

Returns list over all the months in the period, inclusive of the months of both the start and end datetimes and ignoring the offset.

The months are Gregorian calendar months, walked in Gregorian order and rolling over from December to January.

Examples

period.new(
  start: datetime.literal("2024-10-25T00:47:00-04:00"),
  end: datetime.literal("2025-04-30T23:59:59-04:00"),
)
|> period.comprising_months
// -> [
//   tempo.MonthYear(tempo.Oct, 2024),
//   tempo.MonthYear(tempo.Nov, 2024),
//   tempo.MonthYear(tempo.Dec, 2024),
//   tempo.MonthYear(tempo.Jan, 2025),
//   tempo.MonthYear(tempo.Feb, 2025),
//   tempo.MonthYear(tempo.Mar, 2025),
//   tempo.MonthYear(tempo.Apr, 2025),
// ]

contains_date

</>

pub fn contains_date(
  period: tempo.Period,
  date: tempo.Date,
) -> Bool

Checks if a date is contained within a period, inclusive of the start and end datetimes.

Examples

period.from_month(tempo.MonthYear(tempo.Jun, 2024))
|> period.contains_date(date.literal("2024-06-30"))
// -> True

period.from_month(tempo.MonthYear(tempo.Jun, 2024))
|> period.contains_date(date.literal("2024-07-22"))
// -> False

date.as_period(
  start: date.literal("2024-06-13"),
  end: date.literal("2024-06-21"),
)
|> period.contains_date(date.literal("2024-06-21"))
// -> True

date.as_period(
  start: date.literal("2024-06-13"),
  end: date.literal("2024-06-21"),
)
|> period.contains_date(date.literal("2024-06-27"))
// -> False

contains_datetime

</>

pub fn contains_datetime(
  period: tempo.Period,
  datetime: tempo.DateTime,
) -> Bool

Checks if a datetime is contained within a period, inclusive of the start and end datetimes.

Examples

period.from_month(tempo.MonthYear(tempo.Jun, 2024))
|> period.contains_datetime(
  datetime.literal("2024-06-30T24:00:00-07:00"),
)
// -> True

datetime.as_period(
  start: datetime.literal("2024-06-13T15:47:00+06:00"),
  end: datetime.literal("2024-06-21T07:16:12+06:00"),
)
|> period.contains_datetime(
  datetime.literal("2024-06-20T07:16:12+06:00"),
)
// -> True

contains_naive_datetime

</>

pub fn contains_naive_datetime(
  period: tempo.Period,
  naive_datetime: tempo.NaiveDateTime,
) -> Bool

Checks if a naive datetime is contained within a period, inclusive of the start and end datetimes.

Examples

period.from_month(tempo.MonthYear(tempo.Jun, 2024))
|> period.contains_naive_datetime(
  naive_datetime.literal("2024-06-30T24:00:00"),
)
// -> True

period.from_month(tempo.MonthYear(tempo.Jun, 2024))
|> period.contains_naive_datetime(
  naive_datetime.literal("2024-07-22T24:00:00"),
)
// -> False

date.as_period(
  start: date.literal("2024-06-13"),
  end: date.literal("2024-06-21"),
)
|> period.contains_naive_datetime(
  naive_datetime.literal("2024-06-27T13:50:00"),
)
// -> False

date.as_period(
  start: date.literal("2024-06-13"),
  end: date.literal("2024-06-21"),
)
|> period.contains_naive_datetime(
  naive_datetime.literal("2024-06-21T13:50:00"),
)
// -> True

from_dates

</>

pub fn from_dates(
  start start: tempo.Date,
  end end: tempo.Date,
) -> tempo.Period

Creates a new period from the start and end dates.

Examples

period.from_dates(
  start: date.literal("2024-06-13"),
  end: date.literal("2024-06-21"),
)
|> period.as_days
// -> 7

from_datetimes

</>

pub fn from_datetimes(
  start start: tempo.DateTime,
  end end: tempo.DateTime,
) -> tempo.Period

Creates a new period from the start and end datetimes.

Examples

period.from_datetimes(
  start: datetime.literal("2024-06-13T15:47:00+06:00"),
  end: datetime.literal("2024-06-21T07:16:12+06:00"),
)
|> period.as_days
// -> 7

from_month

</>

pub fn from_month(my: tempo.MonthYear) -> tempo.Period

Creates a period of the specified month year, starting at 00:00:00 on the first day of the month and ending at 24:00:00 on the last day of the month.

The month is a Gregorian calendar month, so the last day is 28, 29, 30 or 31 depending on the month and whether it is a Gregorian leap year.

Examples

period.from_month(tempo.MonthYear(tempo.Feb, 2024))
|> period.contains_date(date.literal("2024-06-21"))
// -> False

from_naive_datetimes

</>

pub fn from_naive_datetimes(
  start start: tempo.NaiveDateTime,
  end end: tempo.NaiveDateTime,
) -> tempo.Period

Creates a new period from the start and end naive datetimes.

Examples

period.from_naive_datetimes(
  start: naive_datetime.literal("2024-06-13T15:47:00"),
  end: naive_datetime.literal("2024-06-21T07:16:12"),
)
|> period.as_days
// -> 7

new

</>

pub fn new(
  start start: tempo.DateTime,
  end end: tempo.DateTime,
) -> tempo.Period

Deprecated: Use `period.from_datetimes` instead

new_naive

</>

pub fn new_naive(
  start start: tempo.NaiveDateTime,
  end end: tempo.NaiveDateTime,
) -> tempo.Period

Deprecated: Use `period.from_naive_datetimes` instead