Skip to content

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"