Lists, ranges & relative time¶
These methods join lists, format ranges, and describe relative time.
| Method | Use it for |
|---|---|
join(items, type?, width?) |
"A, B, and C" with the locale's list grammar |
number_range / money_range / date_range |
A low–high interval ("3–5", "$3 – $5") |
relative_duration(amount, unit, numeric?) |
"3 days ago" / "in 2 hours" from a signed amount |
relative_duration_between(target, reference?, numeric?) |
The same, computed between two moments |
Lists¶
join() combines items using the locale's list conventions. The type argument
chooses the connector, such as "and" or "or":
type |
English | Spanish |
|---|---|---|
conjunction (default) |
A, B, and C |
A, B y C |
disjunction |
A, B, or C |
A, B o C |
unit |
A, B, C (no connector — for measurements) |
A, B, C |
The width argument (full/long, medium/short, short/narrow) controls
spacing and the connector's verbosity.
en = Cosmo("en")
en.join(["A", "B", "C"]) # "A, B, and C"
en.join(["A", "B", "C"], "disjunction") # "A, B, or C"
Cosmo("es").join(["uno", "dos", "tres"]) # "uno, dos y tres"
Number, money & date ranges¶
A range formats two endpoints as a single interval, collapsing the shared parts
("Feb 2 – 5, 2020", not "Feb 2, 2020 – Feb 5, 2020"). Each mirrors a single-value
formatter on this site:
| Method | Mirrors | Signature |
|---|---|---|
number_range(start, end) |
number() |
two numbers |
money_range(start, end, code?) |
money() |
two amounts + currency |
date_range(start, end, dateWidth?, timeWidth?) |
date() |
two moments + widths |
date_range() defaults to medium date width (short numeric dates read poorly
as a range) and none time width.
Cosmo("en").number_range(3, 5) # "3–5"
Cosmo("en_US").money_range(3, 5, "USD") # "$3.00 – $5.00"
Cosmo("en").date_range(start, end) # "Feb 2 – 5, 2020"
Like money(), money_range() returns "" when no currency is
resolved and takes the currency from the currency modifier if you omit the code.
Relative / directed duration¶
A directed duration carries a past/future orientation — the counterpart of the
undirected duration(). There are two entry points:
relative_duration(amount, unit, numeric?)— you supply the signed amount and unit.relative_duration_between(target, reference?, numeric?)— you supply two moments; it computes the difference and picks the largest sensible unit.
The sign sets the direction: negative is past ("… ago"), positive is future
("in …"). The unit is one of second, minute, hour, day, week,
month, quarter, year (singular only). The numeric option chooses between
numeric and colloquial phrasing:
numeric |
relative_duration(-1, "day", …) |
|---|---|
always (default for relative_duration) |
"1 day ago" |
auto (default for relative_duration_between) |
"yesterday" |
c = Cosmo("en")
c.relative_duration(-3, "day") # "3 days ago"
c.relative_duration(2, "hour") # "in 2 hours"
c.relative_duration(-1, "day", "auto") # "1 day ago" (numeric — see note)
c.relative_duration_between(target, reference) # e.g. "in 5 days"
relative_duration_between() computes target − reference (with reference
defaulting to now), then walks up the unit scale — seconds, minutes, hours,
days, weeks, months, years — and formats at the first unit where the amount is
below the next threshold. So a 5-day gap renders as "in 5 days", a 40-day gap as
"in 2 months".
Relative text uses a single unit, such as "3 days ago", rather than a breakdown
such as "3 days, 5 hours ago". Use singular unit names (day, not days).
The numeric="auto" option still returns numeric text ("1 day ago") because
PyICU does not expose the word forms used for "yesterday" or "last week".
For an undirected span, use duration().
Practical examples¶
A "posted X ago" timestamp. Let relative_duration_between() choose the unit and
the colloquial wording: