CLDR.Calendars

The CLDR.Calendars namespace allows you to:

• Construct dates in different calendars
• Format dates and times
• Format date-time intervals
• Format relative times
• Obtain weekday and month names for a given calendar
• Calculate the field of greatest difference between two dates

dateField

Formats a date field's name.

Syntax

dateField(type: DateFieldType, options?: DateFieldFormatOptions): string

Parameters

• field: DateFieldType
  • Field indicating the field name to be formatter, e.g. "month"
• options?: DateFieldFormatOptions
  • Options for field width, context, etc.

Example

for (const id of ['en', 'es', 'de', 'fr', 'zh']) {
  const cldr = framework.get(id);
  const s = cldr.Calendars.dateField('year', { context: 'begin-sentence' });
  log(s);
}

Year
Año
Jahr
Année
年

dayPeriods

Returns a mapping of day period key to name for the current locale.

Syntax

dayPeriods(options?): any

Parameters

• options?: CalendarFieldOptions
  • Options for field width, context, etc.

Example

const en = framework.get('en');
log(en.Calendars.dayPeriods({ width: 'wide', context: 'begin-sentence' }));

{
  noon: 'Noon',
  midnight: 'Midnight',
  am: 'AM',
  pm: 'PM',
  morning1: 'Morning',
  afternoon1: 'Afternoon',
  evening1: 'Evening',
  night1: 'Night'
}

eras

Return a mapping of era key to name for the current locale.

Syntax

eras(options?): any

Parameters

• options?: EraFieldOptions
  • Options for field width, context, etc.

Example

const en = framework.get('en');
log(en.Calendars.eras({ width: 'names' }));

{ '0': 'Before Christ', '1': 'Anno Domini' }

fieldOfVisualDifference

Computes the "first field of visual difference" between two dates. Date arguments can be CalendarDate, ZonedDateTime instances, or a bare JavaScript Date.

Syntax

fieldOfVisualDifference(a, b): DateTimePatternFieldType

Parameters

• a: CalendarDate | ZonedDateTime | Date
  • First date to compare
• b: CalendarDate | ZonedDateTime | Date
  • Second date to compare

Return value

• A DateTimePatternFieldType indicating the first field of visual difference

Example

const cldr = framework.get('en');

// June 27, 2018 4:23:00 AM
const date = 1530087780000;
const zoneId = 'America/New_York';
const d1 = cldr.Calendars.toGregorianDate({ date, zoneId });

const factors = [0.0002, 0.005, 0.25, .75, 3, 50, 425, 1000];
factors.forEach(f => {
  const days = f * 86400 * 1000;
  const d2 = cldr.Calendars.toGregorianDate({ date: date + days, zoneId });
  const field = cldr.Calendars.fieldOfVisualDifference(d1, d2);
  log(`${field} ->  ${d2.toString()}`);
});

s ->  Gregorian 2018-06-27 04:23:17.280 America/New_York
m ->  Gregorian 2018-06-27 04:30:12.000 America/New_York
H ->  Gregorian 2018-06-27 10:23:00.000 America/New_York
a ->  Gregorian 2018-06-27 22:23:00.000 America/New_York
d ->  Gregorian 2018-06-30 04:23:00.000 America/New_York
M ->  Gregorian 2018-08-16 04:23:00.000 America/New_York
y ->  Gregorian 2019-08-26 04:23:00.000 America/New_York
y ->  Gregorian 2021-03-23 04:23:00.000 America/New_York

formatDate

Format a date to a string.

Syntax

formatDate(date, options?): string

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to format
• options?: DateFormatOptions
  • Options to control formatting

Example

const cldr = framework.get('en');
const date = 1530087780000;
const zoneId = 'America/New_York';
log(cldr.Calendars.formatDate({ date, zoneId }, { datetime: 'full' }));

Wednesday, June 27, 2018 at 4:23:00 AM Eastern Daylight Time

formatDateToParts

Format a date to an array of parts.

Syntax

formatDateToParts(date, options?): Part[]

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to format
• options?: DateFormatOptions
  • Options to control formatting

Example

const cldr = framework.get('en');
// June 27, 2018 4:23:00 AM
const date = 1530087780000;
const zoneId = 'America/New_York';
log(cldr.Calendars.formatDateToParts({ date, zoneId }, { datetime: 'short' }));

[
  { type: 'month', value: '6' },
  { type: 'literal', value: '/' },
  { type: 'day', value: '27' },
  { type: 'literal', value: '/' },
  { type: 'year', value: '18' },
  { type: 'literal', value: ', ' },
  { type: 'hour', value: '4' },
  { type: 'literal', value: ':' },
  { type: 'minute', value: '23' },
  { type: 'literal', value: ' ' },
  { type: 'dayperiod', value: 'AM' }
]

formatDateInterval

Format a start and end date range to a string.

Syntax

formatDateInterval(start, end, options?): string

Parameters

• start: CalendarDate | ZonedDateTime | Date
  • Start of the date range
• end: CalendarDate | ZonedDateTime | Date
  • End of the date range
• options?: DateIntervalFormatOptions
  • Options to control the format

Example

const cldr = framework.get('en');

// June 27, 2018 4:23:00 AM
const epoch = 1530087780000;
const zoneId = 'America/New_York';

const day = 86400000;
const start = { date: epoch, zoneId };
for (const days of [1.2, 3, 17, 73, 1000]) {
  const end = { date: epoch + (days * day), zoneId };
  const result = cldr.Calendars.formatDateInterval(start, end, { skeleton: 'yMMMd' });
  log(result);
}

Jun 27 – 28, 2018
Jun 27 – 30, 2018
Jun 27 – Jul 14, 2018
Jun 27 – Sep 8, 2018
Jun 27, 2018 – Mar 23, 2021

formatDateIntervalToParts

Format a start and end date range to an array of parts.

Syntax

formatDateIntervalToParts(start, end, options?): Part[]

Parameters

• start: CalendarDate | ZonedDateTime | Date
  • Start of the date range
• end: CalendarDate | ZonedDateTime | Date
  • End of the date range
• options?: DateIntervalFormatOptions
  • Options to control the format

Example

const cldr = framework.get('en');

// June 27, 2018 4:23:00 AM
const epoch = 1530087780000;
const zoneId = 'America/New_York';

const day = 86400000;
const start = { date: epoch, zoneId };
const end = { date: epoch + (day * 10), zoneId };
log(cldr.Calendars.formatDateIntervalToParts(start, end, { skeleton: 'yMMMd' }));

[
  { type: 'month', value: 'Jun' },
  { type: 'literal', value: ' ' },
  { type: 'day', value: '27' },
  { type: 'literal', value: ' – ' },
  { type: 'month', value: 'Jul' },
  { type: 'literal', value: ' ' },
  { type: 'day', value: '7' },
  { type: 'literal', value: ', ' },
  { type: 'year', value: '2018' }
]

formatDateRaw

Format a date to a string using a user-supplied pattern.

Warning: Only use this if you know what you're doing. Using a pre-defined CLDR format is recommended.

Syntax

formatDateRaw(date, options?): string

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to format
• options?: DateRawFormatOptions
  • Options to control formatting

Example

const cldr = framework.get('en');

// June 27, 2018 4:23:00 AM
const date = 1530087780000;
const zoneId = 'America/New_York';

const s = cldr.Calendars.formatDateRaw({ date, zoneId }, { pattern: 'EEE MMM y, d' });
log(s);

Wed Jun 2018, 27

formatDateRawToParts

Format a date to parts using a user-supplied pattern.

Warning: Only use this if you know what you're doing. Using a pre-defined CLDR format is recommended.

Syntax

formatDateRawToParts(date, options?): Part[]

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to format
• options?: DateRawFormatOptions
  • Options to control formatting

Example

const cldr = framework.get('en');

// June 27, 2018 4:23:00 AM
const date = 1530087780000;
const zoneId = 'America/New_York';

const p = cldr.Calendars.formatDateRawToParts({ date, zoneId }, { pattern: 'EEE MMM y, d' });
log(p);

[
  { type: 'weekday', value: 'Wed' },
  { type: 'literal', value: ' ' },
  { type: 'month', value: 'Jun' },
  { type: 'literal', value: ' ' },
  { type: 'year', value: '2018' },
  { type: 'literal', value: ', ' },
  { type: 'day', value: '27' }
]

formatRelativeTime

Formats the time period between two dates as a relative time.

Syntax

formatRelativeTime(start, end, options?): string

Parameters

• start: CalendarDate | ZonedDateTime | Date
  • Time period start date
• end: CalendarDate | ZonedDateTime | Date
  • Time period end date
• options?: RelativeTimeFormatOptions
  • Options for field width, context, etc.

Example

const cldr = framework.get('en');
const start = cldr.Calendars.toGregorianDate({ date: new Date(2019, 6, 11) });
for (const month of [-2, -1, 0, 1, 3 ]) {
  const end = start.add({ month });
  const a = cldr.Calendars.formatRelativeTime(start, end);
  const b = cldr.Calendars.formatRelativeTime(start, end, { field: 'day' });
  log(`${a}  (${b})`);
}

2 months ago  (61 days ago)
last month  (30 days ago)
now  (today)
next month  (in 31 days)
in 3 months  (in 92 days)

formatRelativeTimeField

Formats a value as a unit of relative time.

Syntax

formatRelativeTimeField(value, field, options?): string

Parameters

• value: number | string | Decimal
  • Number of units
• field: RelativeTimeFieldType
  • Field indicating the unit of relative time, e.g. "month"
• options?: RelativeTimeFieldFormatOptions
  • Options to control the format

Example

import { Decimal } from '@phensley/cldr';
const cldr = framework.get('en');
for (const value of ['-2', -1, '0', 1, 3, new Decimal('12.5')]) {
  const result = cldr.Calendars.formatRelativeTimeField(value, 'month', { });
  log(result);
}

2 months ago
last month
this month
next month
in 3 months
in 12 months

months

Returns a mapping of month ordinal number to name for the current locale.

Syntax

months(options?): any

Parameters

• options?: CalendarFieldOptions
  • Options for field width, context, etc.

Example

const en = framework.get('en');
const fr = framework.get('fr');

const context = 'begin-sentence';
const monthsEN = en.Calendars.months({ context });
const monthsFR = fr.Calendars.months({ context });

log(monthsEN);
log(monthsFR);

const date = en.Calendars.toGregorianDate({
  date: new Date(2018, 5, 11, 12, 1, 12),
  zoneId: 'America/New_York'
});

log(`month is ${monthsEN[date.month()]} / ${monthsFR[date.month()]}`);

{
  '1': 'January',
  '2': 'February',
  '3': 'March',
  '4': 'April',
  '5': 'May',
  '6': 'June',
  '7': 'July',
  '8': 'August',
  '9': 'September',
  '10': 'October',
  '11': 'November',
  '12': 'December'
}
{
  '1': 'Janvier',
  '2': 'Février',
  '3': 'Mars',
  '4': 'Avril',
  '5': 'Mai',
  '6': 'Juin',
  '7': 'Juillet',
  '8': 'Août',
  '9': 'Septembre',
  '10': 'Octobre',
  '11': 'Novembre',
  '12': 'Décembre'
}
month is June / Juin

quarters

Return a mapping of quarter ordinal number to name for the current locale.

Syntax

quarters(options?): any

Parameters

• options?: CalendarFieldOptions
  • Options for field width, context, etc.

Example

const en = framework.get('en');
log(en.Calendars.quarters());

{
  '1': '1st quarter',
  '2': '2nd quarter',
  '3': '3rd quarter',
  '4': '4th quarter'
}

resolveTimeZoneId

Given a timezone id or alias, returns the canonical tzdb (timezone database) identifier.

Syntax

resolveTimeZoneId(string): string;

Example

const en = framework.get('en');
log(en.Calendars.resolveTimeZoneId('UTC'));
log(en.Calendars.resolveTimeZoneId('US/East-Indiana'));
log(en.Calendars.resolveTimeZoneId('Antarctica/McMurdo'));

Etc/UTC
America/Indiana/Indianapolis
Pacific/Auckland

timePeriodToQuantity

Converts a TimePeriod into a Quantity sequence, suitable for unit formatting.

Syntax

timePeriodToQuantity(period): Quantity[]

Parameters

• date: TimePeriod
  • Time period to convert

Return value

• A Quantity array containing the unit and value pairs.

Example

const en = framework.get('en');
const date = en.Calendars.toGregorianDate({ date: 1530124872456 });
const end = date.add({ year: 2, month: 5, day: 20, hour: 12 });
const t = date.difference(end, ['year', 'day']);
const q = en.Calendars.timePeriodToQuantity(t);

let s: string;
s = en.Units.formatQuantitySequence(q)
log(s);

s = en.Units.formatQuantitySequence(q, { length: 'short', maximumFractionDigits: 0 });
log(s);

s = en.Units.formatQuantitySequence(q, { length: 'narrow', maximumFractionDigits: 0 });
log(s);

2 years, 173.5 days
2 yrs, 174 days
2y 174d

timeZoneIds

Returns an array of timezone identifiers from the latest IANA tzdb (timezone database).

Syntax

timeZoneIds(): string[]

Example

const en = framework.get('en');
const ids = en.Calendars.timeZoneIds();
for (const id of ids.slice(0, 10)) {
  log(id);
}
log('...');

Africa/Abidjan
Africa/Accra
Africa/Algiers
Africa/Bissau
Africa/Cairo
Africa/Casablanca
Africa/Ceuta
Africa/El_Aaiun
Africa/Johannesburg
Africa/Juba
...

timeZoneInfo

Returns an array of TimeZoneInfo objects, including the exemplar city for each.

Syntax

timeZoneInfo(): TimeZoneInfo[]

Example

const en = framework.get('en');
const ids = en.Calendars.timeZoneIds();
for (const id of ids.slice(0, 10)) {
  log(en.Calendars.timeZoneInfo(id));
}
log('...');

{ id: 'Africa/Abidjan', city: { name: 'Abidjan' } }
{ id: 'Africa/Accra', city: { name: 'Accra' } }
{ id: 'Africa/Algiers', city: { name: 'Algiers' } }
{ id: 'Africa/Bissau', city: { name: 'Bissau' } }
{ id: 'Africa/Cairo', city: { name: 'Cairo' } }
{ id: 'Africa/Casablanca', city: { name: 'Casablanca' } }
{ id: 'Africa/Ceuta', city: { name: 'Ceuta' } }
{ id: 'Africa/El_Aaiun', city: { name: 'El Aaiun' } }
{ id: 'Africa/Johannesburg', city: { name: 'Johannesburg' } }
{ id: 'Africa/Juba', city: { name: 'Juba' } }
...

toBuddhistDate

Converts a date to a BuddhistDate instance.

Syntax

toBuddhistDate(date): BuddhistDate

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to convert

Example

const cldr = framework.get('en');
log(cldr.Calendars.toBuddhistDate({
  date: 1530124872456, zoneId: 'America/New_York'}));

Buddhist 2561-06-27 14:41:12.456 America/New_York

toGregorianDate

Converts a date to a GregorianDate instance.

Syntax

toGregorianDate(date): GregorianDate

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to convert

Example

const cldr = framework.get('en');
log(cldr.Calendars.toGregorianDate({
  date: 1530124872456, zoneId: 'America/New_York' }));

Gregorian 2018-06-27 14:41:12.456 America/New_York

const cldr = framework.get('en');

// JavaScript Date is interpreted as a UTC date time
let date = new Date(2018, 1, 17, 12, 34, 56, 789);
const zoneId = 'America/New_York';

const d = cldr.Calendars.toGregorianDate({ date, zoneId  });
log(d);

date = new Date(2018, 6, 17, 12, 34, 56, 789);
d = cldr.Calendars.toGregorianDate({ date, zoneId });
log(d);

Gregorian 2018-02-17 12:34:56.789 America/New_York
Gregorian 2018-07-17 12:34:56.789 America/New_York

toISO8601Date

Converts a date to a ISO8601Date instance.

toISO8601Date(date): ISO8601Date

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to convert

Example

const cldr = framework.get('en');
const weekdays = cldr.Calendars.weekdays();
const date = cldr.Calendars.toGregorianDate({ date: new Date(2017, 0, 1) });
const iso = cldr.Calendars.toISO8601Date(date);

const wk = (d: CalendarDate) => `week starts on ${weekdays[d.firstDayOfWeek()]}`;
const woy = (d: CalendarDate) => `week of year: ${d.yearOfWeekOfYear()}-${d.weekOfYear()}`;

log(`gregorian ${wk(date)}, ${woy(date)}`);
log(` iso-8601 ${wk(iso)}, ${woy(iso)}`);

gregorian week starts on Sunday, week of year: 2017-1
 iso-8601 week starts on Monday, week of year: 2016-52

toJapaneseDate

Converts a date to a JapaneseDate instance.

toJapaneseDate(date): JapaneseDate

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to convert

Example

const cldr = framework.get('en');
const date = cldr.Calendars.toJapaneseDate({
  date: 1530124872456, zoneId: 'America/New_York' });
log(date);
log(date.relatedYear());
log(date.year());

Japanese 2018-06-27 14:41:12.456 America/New_York
2018
30

toPersianDate

Converts a date to a PersianDate instance.

toPersianDate(date): PersianDate

Parameters

• date: CalendarDate | ZonedDateTime | Date
  • Date or timestamp to convert

weekdays

Return a mapping of weekday ordinal number to name for the current locale.

Syntax

weekdays(options?): any

Parameters

• options?: CalendarFieldOptions
  • Options for field width, context, etc.

Example

const en = framework.get('en');
const es = framework.get('es');
const context = 'ui-list-or-menu';

log(en.Calendars.weekdays({ context }));
log(es.Calendars.weekdays({ context }));

{
  '1': 'Sunday',
  '2': 'Monday',
  '3': 'Tuesday',
  '4': 'Wednesday',
  '5': 'Thursday',
  '6': 'Friday',
  '7': 'Saturday'
}
{
  '1': 'Domingo',
  '2': 'Lunes',
  '3': 'Martes',
  '4': 'Miércoles',
  '5': 'Jueves',
  '6': 'Viernes',
  '7': 'Sábado'
}