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 DateTimeOffset. 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
var c = new Cosmo("en-GB", new Modifiers(timeZone: "Europe/London"));
var d = new DateTimeOffset(2020, 2, 2, 9, 25, 30, TimeSpan.Zero);

c.Date(d, "full");           // "Sunday, 2 February 2020"
c.Time(d, "short");          // "09:25"
c.Moment(d, "short", "short"); // date + time (both widths required)

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:

var fa = new Cosmo("fa-IR");
fa.Date(d, "long");                                    // Persian calendar
fa.Moment(d, "long", "none", "gregorian");             // forced Gregorian
new Cosmo("en", new Modifiers(calendar: "buddhist")).Date(d, "full");

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, withWords: true); // spelled-out form
new Cosmo("en").Duration(new Dictionary<string, double> { ["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
var c = new Cosmo("en", new Modifiers(timeZone: "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()[0];          // "January"
new Cosmo("en").WeekdayNames("medium");   // ["Sun", "Mon", … "Sat"]
new Cosmo("fa-IR").MonthNames()[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:

var w = new Cosmo("en-US").WeekInfo();
// w.FirstDay = 7, w.MinimalDays = 1, w.Weekend = [6, 7]

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).

Practical examples

A "last seen" label that degrades gracefully. Use relative time for recent moments and an absolute date for older ones:

string LastSeen(Cosmo c, DateTimeOffset when) {
    double ageDays = (DateTimeOffset.UtcNow - when).TotalDays;
    return ageDays < 7
        ? c.RelativeDurationBetween(when)    // "3 days ago"
        : c.Date(when, "medium");            // "2 Feb 2020"
}

A sortable log filename, then a friendly header. FormatMoment() for the machine name, the width presets for the human label:

var c = new Cosmo("en-GB", new Modifiers(timeZone: "UTC"));
string name   = c.FormatMoment(d, "yyyy-MM-dd'T'HH-mm-ss") + ".log"; // 2020-02-02T09-25-30.log
string header = c.Moment(d, "full", "short");                        // "Sunday, 2 February 2020 at 09:25"