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
calendarmodifier 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:
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: