So glad to see the additional release of ex_tempo_sql! (BTW the link isn’t working for me?)
I’ve been following Tempo off and on and I’d had the thought that a tstz{multi}range in Postgres would be a good way to persist that data. I’m happy to see that my instinct wasn’t too off the mark. And now that there’s a persistence story, it makes me want to start playing with Tempo for more serious uses.
Sometimes interesting (at least to me!) use cases surface. Since Tempo is a different way of thinking about time, it can take a while for cognition to switch. Therefore I think posting interesting recipes from time-to-time (no pun intended) might be useful.
@tubedude is working on a Financial Calulation library. Turns out that there are many ways to count days when calculating daily interest. Most of them are straight forward.
However, Brazil has a particular way of determining the day count: All of the working days of the year, not including the holidays declared by ANBIMA.
Here’s the recipe, following which we’ll work through the code step-by-step.
import Tempo.Sigils
{:ok, holidays} = Tempo.ICal.from_ical_file("feriados_anbima.ics")
settlement = ~o"2024-01-01"
maturity = ~o"2025-01-01"
{:ok, window} = Tempo.Interval.new(from: settlement, to: maturity)
{:ok, workdays} = Tempo.select(window, Tempo.workdays(:BR))
{:ok, business_days} = Tempo.members_outside(workdays, holidays)
Tempo.IntervalSet.count(business_days) / 252
#=> 1.003968253968254 (253 business days in 2024)
The recipe leverages the fact that in Tempo, everything is an interval (not an instant). And therefore, operations on an interval are set operations, not scalar.
# Import the ~o sigil which compiles an ISO8601 time expression
# into a `Tempo.t` struct at compile time.
iex> import Tempo.Sigils
# Import an `.ics` (iCalendar) file and interpret each event as a
# Tempo interval. This uses the fabulous [ical](https://hex.pm/packages/ical) library for parsing
# the calendar file. The data itself comes from [ANBIMA](https://www.anbima.com.br/feriados/feriados.asp) and is converted to an iCal file by [a script](https://github.com/kipcole9/tempo/blob/main/scripts/anbima_xls_to_ics.py).
iex> {:ok, holidays} = Tempo.ICal.from_ical_file("feriados_anbima.ics")
{:ok, #Tempo.IntervalSet<[#Tempo.Interval<~o"2001Y1M1D/2001Y1M2D" · Confraternização Universal>, #Tempo.Interval<~o"2001Y2M26D/2001Y2M27D" · Carnaval>, #Tempo.Interval<~o"2001Y2M27D/2001Y2M28D" · Carnaval>, #Tempo.Interval<~o"2001Y4M13D/2001Y4M14D", ....]>
# Now we describe the settlement and maturity dates. These look
# a lot like a ~D[2024-01-01] date in Elixir. But unlike the native
# Date type, ~o[2024-01-01] is describing an *implicit* interval of
# one year. We could also have entered it as an *explicit* interval
# as ~o"2024-01-01/2024-01-02". Note that Tempo intervals are
# [half-open](https://en.wikipedia.org/wiki/Interval_(mathematics))
iex> settlement = ~o"2024-01-01"
iex> maturity = ~o"2025-01-01"
# We are explicitly creating the interval for a loan here, we could
# also have used a the direct notation ~o"2024-01-01/2024-01-02"
# we described previously.
iex> {:ok, window} = Tempo.Interval.new(from: settlement, to: maturity)
# From all the days in the year, we want to select only
# those days that are working days. Since Tempo leans on
# [Localize](https://hex.pm/packages/localize), we can derive
# the working days directly for any given [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
# territory code. Notice that the return value is also a Tempo
# interval. In this case its the interval that selects the days of the
# week 1 through 5 denoting Monday through Friday. Different
# territories define different working weeks (try the example
# with the territory :SA).
iex> brazil_workdays = Tempo.workdays(:BR)
~o"{1,2,3,4,5}K"
# Now we're getting the heart of Tempo's power. Given the
# full year interval we described in `window`, select only the
# working days. This is more formally a *projection*, but `select`
# is a more common idiom so we use that.
# Tempo.select/2` picks the sub-intervals of a span that match a
# selector (workdays, the 15th, every Friday, holidays…) and
# returns them as an `IntervalSet`.
iex> {:ok, workdays} = Tempo.select(window, brazil_workdays)
{:ok,
#Tempo.IntervalSet<[~o"2024Y1M1D/2024Y1M2D", ~o"2024Y1M2D/2024Y1M3D", ~o"2024Y1M3D/2024Y1M4D", ~o"2024Y1M4D/2024Y1M5D", ~o"2024Y1M5D/2024Y1M6D", ...]>
# Tempo.members_outside is a member-preserving anti-overlap
# filter — returns the whole members of workdays that do NOT
# overlap any member of holidays.
iex> {:ok, business_days} = Tempo.members_outside(workdays, holidays)
{:ok,
#Tempo.IntervalSet<[~o"2024Y1M2D/2024Y1M3D", ~o"2024Y1M3D/2024Y1M4D", ~o"2024Y1M4D/2024Y1M5D", ~o"2024Y1M5D/2024Y1M6D", ~o"2024Y1M8D/2024Y1M9D", ~o"2024Y1M9D/2024Y1M10D", ~o"2024Y1M10D/2024Y1M11D", ~o"2024Y1M11D/2024Y1M12D", ...]>
# And how any days is that? It's the number of spans in the
# IntervalSet, so we can just count them.
iex> Tempo.IntervalSet.count(business_days)
253
All the pieces are in the documentation and the GitHub repo.
.ics file: tempo/scripts/anbima_xls_to_ics.py at main · kipcole9/tempo · GitHub
Here’s today’s recipe from the interval-sets-not-instants cookbook. This one is a bit of a Tempo party trick: a set operation across two different calendars.
UAE labour law (Article 17 of Federal Decree-Law No. 33 of 2021) reduces the private-sector workday by two hours - eight becomes six - for every day of Ramadan, for all employees regardless of religion, with no pay reduction.
The payroll year is Gregorian. Ramadan is the ninth month of the Islamic calendar, and because the Islamic year is ~11 days shorter, Ramadan drifts earlier through the Gregorian year - February one year, January a few years later. So “how many statutory working hours in 2026?” is an intersection between a Gregorian year and an Islamic month. Most (all?) date libraries can’t represent that question. In Tempo it’s the same set algebra as everything else.
import Tempo.Sigils
work_year = ~o"2026"
ramadan = ~o"1447-09[u-ca=islamic-civil]"
standard_hours = 8
ramadan_hours = 6
{:ok, workdays} = Tempo.select(work_year, Tempo.workdays(:AE))
{:ok, ramadan_workdays} = Tempo.members_overlapping(workdays, ramadan)
{:ok, normal_workdays} = Tempo.members_outside(workdays, ramadan)
Tempo.IntervalSet.count(normal_workdays) * standard_hours +
Tempo.IntervalSet.count(ramadan_workdays) * ramadan_hours
#=> 2044 (239 normal workdays × 8h + 22 Ramadan workdays × 6h — 44 hours reduced)
# Ramadan is month 9 of the Islamic year — here 1447 AH, written with
# the IXDTF u-ca suffix. The value lives in the Islamic calendar; its
# implicit span is the whole month, in its own calendar's terms:
iex> ramadan = ~o"1447-09[u-ca=islamic-civil]"
iex> Tempo.to_interval(ramadan)
{:ok, ~o"1447Y9M1D[u-ca=islamic-civil]/1447Y10M1D[u-ca=islamic-civil]"}
# Where does that land in the Gregorian year? Intersect it with 2026.
# Tempo converts calendars inside the set operation — note the result
# is plain Gregorian:
iex> Tempo.intersection(~o"2026", ramadan)
{:ok, #Tempo.IntervalSet<[~o"2026Y2M18D/2026Y3M20D"]>}
# The UAE's workweek comes from CLDR territory data — and it knows
# the UAE moved its weekend to Saturday–Sunday in 2022, so workdays
# are Monday–Friday. No hand-coded weekday list:
iex> Tempo.workdays(:AE)
~o"{1,2,3,4,5}K"
iex> {:ok, workdays} = Tempo.select(~o"2026", Tempo.workdays(:AE))
iex> Tempo.IntervalSet.count(workdays)
261
# Now partition the year's workdays by Ramadan. `members_overlapping`
# keeps the workdays that fall inside it; `members_outside` keeps the
# rest. Same member-preserving filters as the Business/252 recipe -
# one Gregorian operand, one Islamic:
iex> {:ok, ramadan_workdays} = Tempo.members_overlapping(workdays, ramadan)
iex> ramadan_workdays
#Tempo.IntervalSet<[~o"2026Y2M18D/2026Y2M19D", ~o"2026Y2M19D/2026Y2M20D", ~o"2026Y2M20D/2026Y2M21D", …]>
iex> Tempo.IntervalSet.count(ramadan_workdays)
22
# 22 six-hour days and 239 (being 261 - 22) eight-hour days:
iex> 239 * 8 + 22 * 6
2044
An additional benefit of doing this symbolically is that next year is the same pipeline with two new bindings. Ramadan 1448 drifts ten days earlier, and nothing else changes:
iex> Tempo.intersection(~o"2027", ~o"1448-09[u-ca=islamic-civil]")
{:ok, #Tempo.IntervalSet<[~o"2027Y2M8D/2027Y3M10D"]>}
Two real world caveats:. The tabular islamic-civil calendar is a planning approximation - the legal month begins with the moon-sighting announcement. And Eid al-Fitr, immediately after Ramadan, is a public holiday - subtract it with Tempo.members_outside/2 exactly as Business/252 subtracts ANBIMA holidays.
u-ca tag vocabulary is CLDR’s, via Localize.