Narrow a Tempo span by a selector — the composition primitive for "workdays of June", "the 15th of every month", "every Dec 25 in the next decade", and user-supplied holidays.

Tempo.select(~o"2026-06", Tempo.workdays(:US))  # workdays of June — locale-aware
Tempo.select(~o"2026-06", Tempo.weekend(:US))   # weekend days of June
Tempo.select(~o"2026", [1, 15])
Tempo.select(~o"2026", ~o"12-25")
Tempo.select(~o"2026", ~o"10O")     # ISO 8601-2 ordinal day — the 10th day of 2026
Tempo.select(~o"2026-06", ~o"5K")   # ISO 8601-2 day-of-week — every Friday in June 2026
Tempo.select(~o"2026", ~o"-1M")     # ISO 8601-2 negative — the last month of 2026
Tempo.select(~o"2026-06", ~o"-1D")  # ISO 8601-2 negative — the last day of June 2026
Tempo.select(~o"2026", &my_holidays/1)

Every call returns {:ok, %Tempo.IntervalSet{}} (or {:error, reason}), consistent with the other set-algebra operations — the result composes directly into Tempo.union/2, Tempo.intersection/2, Tempo.difference/2.

Tempo.select/2 is a pure function. It has no opts, no ambient locale read, no implicit territory resolution. Every input that can affect the result is a value on the selector. Locale-dependent constraints like "workdays" or "weekend" are constructed by Tempo.workdays/1 and Tempo.weekend/1 (which read the locale once at construction time) and composed in:

interval
|> Tempo.select(Tempo.workdays(:US))

That means the workdays(:US) call is where territory resolution happens — not inside select/2 — and the resulting value is safe to capture anywhere, including module attributes.

Selector shapes

Base can be a Tempo.t/0, Tempo.Interval.t/0, or Tempo.IntervalSet.t/0. IntervalSet bases flat-map the selector across each member and collect the results.

Time-of-day windows — interval selectors project as spans

Narrowing every member of a day set to the same part of each day is one expression: an interval selector keeps its whole extent, so "nine to five" is a single eight-hour span per member — half-open, written as nine to five, with no off-by-one and no coalesce/1. A list gives several windows per member (the business-hours-with-lunch case), and the duration form expresses windows that are not hour-aligned:

{:ok, workdays} = Tempo.select(~o"2026-07", Tempo.workdays(:AU))
{:ok, open}     = Tempo.select(workdays, [~o"T09/T12", ~o"T13/T17"])
{:ok, shift}    = Tempo.select(workdays, ~o"T09/PT7H36M")

"The workdays of July, nine to five with an hour for lunch."

A window whose to is at or before its from crosses midnight and rolls forward: ~o"T21/T05" on the 15th is the span from the 15th 21:00 to the 16th 05:00 — a night shift reads the way a roster writes it. Use the duration form (~o"T21/PT8H") to say the same thing explicitly.

Negative components — "last N from the end"

ISO 8601-2 §4.4.1 allows any integer component to be negative, meaning "count from the end of the containing time-scale unit". Tempo.select/2 honours this: the resolution is context-aware and produces end-of-span selections without string munging or calendar arithmetic at the call site.

Tempo.select(~o"2026",    ~o"-1M")   #=> December 2026 (last month of year)
Tempo.select(~o"2026",    ~o"-1D")   #=> Dec 31 2026 (last day of year)
Tempo.select(~o"2026",    ~o"-1W")   #=> week 52 of 2026 (last ISO week)
Tempo.select(~o"2026-06", ~o"-1D")   #=> Jun 30 2026 (last day of month)
Tempo.select(~o"2026-02", ~o"-1D")   #=> Feb 28 2026 (leap-aware — Feb 29 in 2024)
Tempo.select(~o"2026-06-15", ~o"-1H") #=> 23:00 (last hour of day)
Tempo.select(~o"2026-06-15T14", ~o"T-1M") #=> 14:59 (last minute of hour)

The resolution is calendar-aware — Tempo.select(~o"2024-02", ~o"-1D") returns Feb 29 because 2024 is a leap year. It is also axis-aware: -1W on a year base uses ISO weeks-in-year (52 or 53); -1W on a month base uses weeks of that month (4 or 5). -1M always refers to the calendar month; -1K to the week's last day-of-week; -1O to the year's last ordinal day.

Time-of-day components (:hour, :minute, :second, :day_of_week) have fixed ranges and resolve at parse time — ~o"-1H" parses directly as hour: 23, ~o"T-1M" as minute: 59, ~o"T-1S" as second: 59, ~o"-1K" as day_of_week: 7. Calendar-dependent units (:month, :week, :day, :day_of_year) keep their negative value through parse and are resolved against the base context when Tempo.select/2 materialises them.

~o"-1M" is always "last month" (never "last minute") — use the T time designator (~o"T-1M") to select minute-of-hour.

Negative :year values are preserved (BC designator per ISO 8601-2 expanded year form) — they're not flipped to "last year" because a time line has no "end" to count from.