Skip to content

Dates & times

Format dates, times, durations, and calendar metadata using the locale's own calendar and conventions. The width argument controls how much detail appears in the formatted result:

width date() in en-GB time() in en-GB
none (omits this part) (omits this part)
short 02/02/2020 09:25
medium 2 Feb 2020 09:25:30
long 2 February 2020 09:25:30 GMT
full Sunday, 2 February 2020 09:25:30 Greenwich Mean Time

What's a moment?

A moment is a single point on the timeline. Accepted values are

a java.util.Date or java.time.Instant. See Terminology for the distinction between moments, durations, and ranges.

Date, time, and both

moment() formats a date and a time; date() and time() are thin shortcuts that set the other width to none.

Method Parameters Defaults
moment(value, dateWidth, timeWidth, calendar?) both widths + optional calendar short, short
date(value, width) date width only short
time(value, width) time width only short
Cosmo c = new Cosmo("en_GB", new Modifiers(null, null, "Europe/London"));
Date d = Date.from(Instant.parse("2020-02-02T09:25:30Z"));

c.date(d, "full");           // "Sunday, 2 February 2020"
c.time(d, "short");          // "09:25"
c.moment(d, "short", "short"); // date + time (Java needs both widths)

Calendars

The calendar follows the locale automatically — fa_IR renders in the Persian calendar, th can render Buddhist. Two ways to control it:

  • set the calendar modifier on the instance ({ calendar: "buddhist" }), or
  • pass a calendar to moment() for a one-off.

Pass the special value "gregorian" to force the proleptic Gregorian calendar even when the locale would imply another:

Duration

duration() formats an undirected span — magnitude only, no past/future. For "3 days ago" you want the directed relative time.

It takes either a scalar number of seconds or a unit breakdown, and a withWords flag that switches between the digital-clock form and the spelled form:

Input withWords Result
1222060 (seconds) false (default) "339:27:40"
1222060 (seconds) true "339 hours, 27 minutes, 40 seconds"
{hours: 3, minutes: 5} false "3 hr, 5 min"
{hours: 3, minutes: 5} true "3 hours, 5 minutes"
new Cosmo("en").duration(1222060);              // "339:27:40"
new Cosmo("en").duration(1222060, true);        // spelled-out form
new Cosmo("en").duration(Map.of("hours", 3, "minutes", 5));

The breakdown keys are years, months, weeks, days, hours, minutes, seconds, milliseconds. Scalar input is always interpreted as seconds and split into the hours/minutes/seconds clock form.

Time-zone name

timeZoneName() returns the localised display name of the instance's timeZone modifier (falling back to the runtime zone). The style chooses the form:

style Example (Australia/Sydney, en)
long (default) Australian Eastern Standard Time
short AEST
shortOffset GMT+10
longOffset GMT+10:00
shortGeneric Sydney Time
longGeneric Australian Eastern Time
Cosmo c = new Cosmo("en", new Modifiers(null, null, "Australia/Sydney"));
c.timeZoneName();                // "Australian Eastern Standard Time"
c.timeZoneName("shortOffset");   // "GMT+10"

The generic styles drop the standard/daylight distinction (good for labelling a zone in settings); the offset styles reflect the offset at the current instant, so they swing with daylight saving.

Calendar names

Localised month and weekday names, aligned to the active calendar. Both take a width: full (default), long, medium, short. Weekdays are Sunday-first (ICU symbol order) regardless of the locale's first day — use weekInfo() to find where the week actually starts.

new Cosmo("en").monthNames().get(0);          // "January"
new Cosmo("en").weekdayNames("medium");       // ["Sun", "Mon", … "Sat"]
new Cosmo("fa_IR").monthNames().get(0);       // "فروردین"

Week information

weekInfo() returns the locale's week conventions — the first day of the week and the minimal-days-in-first-week rule, plus the weekend days:

Days are 1 = Monday … 7 = Sunday.

Arbitrary patterns & ranges

Use these methods to format date intervals or specify a custom date pattern:

  • formatMoment(value, pattern) renders a moment with a raw ICU date/time pattern (yyyy-MM-dd, EEEE, d MMM, …) — exact control for filenames, ISO output, or bespoke layouts.

  • dateRange(start, end, dateWidth?, timeWidth?) formats an interval, collapsing the shared parts ("Feb 2 – 5, 2020").

new Cosmo("en").formatMoment(d, "yyyy-MM-dd");    // "2020-02-02"
new Cosmo("en").formatMoment(d, "EEEE, d MMM");   // "Sunday, 2 Feb"
new Cosmo("en").dateRange(start, end);            // "Feb 2 – 5, 2020"

Common pattern letters: y year · M month (MMM/MMMM for names) · d day · E weekday · H/h hour · m minute · s second · a AM/PM · z/Z zone. Literal text goes in single quotes ('on' d MMM).