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 |
numberRange / moneyRange / dateRange |
A low–high interval ("3–5", "$3 – $5") |
relativeDuration(amount, unit, numeric?) |
"3 days ago" / "in 2 hours" from a signed amount |
relativeDurationBetween(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 = new Cosmo('en');
$en->join(['A', 'B', 'C']); // "A, B, and C"
$en->join(['A', 'B', 'C'], 'disjunction'); // "A, B, or C"
new 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 |
|---|---|---|
numberRange(start, end) |
number() |
two numbers |
moneyRange(start, end, code?) |
money() |
two amounts + currency |
dateRange(start, end, dateWidth?, timeWidth?) |
date() |
two moments + widths |
dateRange() defaults to medium date width (short numeric dates read poorly
as a range) and none time width.
new Cosmo('en')->numberRange(3, 5); // "3–5"
new Cosmo('en_US')->moneyRange(3, 5, 'USD'); // "$3.00–$5.00" (approximate)
new Cosmo('en')->dateRange($start, $end); // "Feb 2 – 5, 2020" (short/medium)
Like money(), moneyRange() returns "" when no currency is
resolved and takes the currency from the currency modifier if you omit the code.
Range limitations
Ranges are assembled from CLDR data. moneyRange() does not collapse shared
currency symbols. dateRange() supports short and medium widths only.
Relative / directed duration¶
A directed duration carries a past/future orientation — the counterpart of the
undirected duration(). There are two entry points:
relativeDuration(amount, unit, numeric?)— you supply the signed amount and unit.relativeDurationBetween(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 |
relativeDuration(-1, "day", …) |
|---|---|
always (default for relativeDuration) |
"1 day ago" |
auto (default for relativeDurationBetween) |
"yesterday" |
$c = new Cosmo('en');
$c->relativeDuration(-3, 'day'); // "3 days ago"
$c->relativeDuration(2, 'hour'); // "in 2 hours"
$c->relativeDuration(-1, 'day', 'auto'); // "yesterday" (word form)
$c->relativeDurationBetween($target, $reference); // e.g. "in 5 days"
relativeDurationBetween() 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).
For an undirected span, use duration().
Practical examples¶
A localised "and N more" tag list. Join the visible tags, then append an overflow phrase built from a plural message:
$c = new Cosmo('en');
$tags = ['news', 'sport', 'tech', 'travel', 'food'];
$shown = array_slice($tags, 0, 3);
$rest = count($tags) - count($shown);
$label = $c->join($shown);
if ($rest > 0) {
$label .= ' ' . $c->message('and {n, plural, one {# more} other {# more}}', ['n' => $rest]);
}
// "news, sport, and tech and 2 more"