tempo/period

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

Example

import tempo/period
import tempo/date

pub fn get_days_between(date1, date2) {
  date1
  |> date.difference(from: date2)
  |> period.as_days
  // -> 11
}

import tempo/period
import tempo/date

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

Types

Unit

</>

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

Constructors

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

Functions

as_days

</>

pub fn as_days(period: 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: 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: Period) -> 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: 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: Period) -> Iterator(Date)

Returns an iterator over all the 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
|> iterator.to_list
// -> [
//   date.literal("2024-06-19"),
//   date.literal("2024-06-20"),
//   date.literal("2024-06-21"),
// ]

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

comprising_months

</>

pub fn comprising_months(period: Period) -> Iterator(MonthYear)

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

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
|> iterator.to_list
// -> [
//   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: Period, date: Date) -> Bool

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

Examples

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

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

date.literal("2024-06-13")
|> date.difference(from: date.literal("2024-06-21"))
|> period.contains_date(date.literal("2024-06-21"))
// -> True

date.literal("2024-06-13")
|> date.difference(from: date.literal("2024-06-21"))
|> period.contains_date(date.literal("2024-06-27"))
// -> False

contains_datetime

</>

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

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

Examples

period.from_month(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: Period,
  naive_datetime: NaiveDateTime,
) -> Bool

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

Examples

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

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

date.literal("2024-06-13")
|> date.difference(from: date.literal("2024-06-21"))
|> period.contains_naive_datetime(
  naive_datetime.literal("2024-06-21T13: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_month

</>

pub fn from_month(month: Month, year: Int) -> Period

Creates a period of the specified month, 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.

Examples

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

new

</>

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

Creates a new period from the start and end datetimes.

Examples

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

new_naive

</>

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

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

Examples

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