Version: 1.10.2

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: { none: 'Noon' },
  midnight: { none: 'Midnight' },
  am: { none: 'AM', casing: 'Am' },
  pm: { none: 'PM', casing: 'Pm' },
  morning1: { none: 'Morning' },
  morning2: {},
  afternoon1: { none: 'Afternoon' },
  afternoon2: {},
  evening1: { none: 'Evening' },
  evening2: {},
  night1: { none: 'Night' },
  night2: {}
}

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': { none: 'Before Christ', sensitive: 'Before Common Era' },
  '1': { none: 'Anno Domini', sensitive: 'Common Era' }
}

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 | undefined

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, or undefined if dates are equivalent.

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, 0.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

firstDayOfWeek

Returns the weekday that starts the week in the date's locale, where 1 = SUNDAY, 2 = MONDAY, ..., 7 = SATURDAY

Syntax

firstDayOfWeek(): number

Example

let cldr = framework.get("en-US");
log(cldr.Calendars.firstDayOfWeek());

cldr = framework.get("und-EG");
log(cldr.Calendars.firstDayOfWeek());

1
7

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' }
]

formatDateWrapper

Formats a date and time string together using a wrapper format of the given width. This can be used when you need to format a date and time string separately and join them together.

Syntax

formatDateWrapper(date, time, options?): string

Parameters

date: string
- A formatted date string
time: string
- A formatted time string
options?: DateWrapperFormatOptions
- Options to control the calendar and width of the format

Example

const cldr = framework.get("en");
const date = cldr.Calendars.formatRelativeTimeField(1, "wed", {
  context: "begin-sentence",
});
const time = cldr.Calendars.formatDate(cldr.Calendars.now(), {
  time: "medium",
});
log(cldr.Calendars.formatDateWrapper(date, time, { width: "full" }));

Next Wednesday at 10:48:02 PM

formatDateWrapperToParts

Formats a date and time Part[] together using a wrapper format of the given width. This can be used when you need to format a date and time string separately and join them together.

Syntax

formatDateWrapper(date, time, options?): Part[]

Parameters

date: Part
- A formatted date Part[]
time: Part
- A formatted time Part[]
options?: DateWrapperFormatOptions
- Options to control the calendar and width of the format

Example

const cldr = framework.get("en");
const date = cldr.Calendars.formatRelativeTimeField(1, "wed", {
  context: "begin-sentence",
});
const time = cldr.Calendars.formatDateToParts(cldr.Calendars.now(), {
  time: "medium",
});
log(
  cldr.Calendars.formatDateWrapperToParts(
    [{ type: "reldate", value: date }],
    time,
    {
      width: "full",
    }
  )
);

[
  { type: 'reldate', value: 'Next Wednesday' },
  { type: 'literal', value: ' at ' },
  { type: 'hour', value: '10' },
  { type: 'literal', value: ':' },
  { type: 'minute', value: '48' },
  { type: 'literal', value: ':' },
  { type: 'second', value: '02' },
  { type: 'literal', value: ' ' },
  { type: 'dayperiod', value: 'PM' }
]

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

minDaysInFirstWeek

Minimum number of days in a week to count as the first week of the year.

Syntax

minDaysInFirstWeek(): number

Example

let cldr = framework.get("en");
log(cldr.Calendars.minDaysInFirstWeek());

cldr = framework.get("en-DE");
log(cldr.Calendars.minDaysInFirstWeek());

1
4

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

newBuddhistDate

Construct a date in the Buddhist calendar from one or more fields.

Syntax

newBuddhistDate(fields): BuddhistDate

Parameters

fields: CalendarDateFields
- Date and time fields

newGregorianDate

Construct a date in the Gregorian calendar from one or more fields.

Syntax

newGregorianDate(fields): GregorianDate

Parameters

fields: CalendarDateFields
- Date and time fields

Example

const en = framework.get("en");
log(
  en.Calendars.newGregorianDate({
    year: 2020,
    day: 15,
    hour: 17,
    minute: 45,
    zoneId: "America/New_York",
  })
);

Gregorian 2020-01-15 17:45:00.000 America/New_York

newISO8601Date

Construct a date in the ISO8601 calendar from one or more fields.

Syntax

newISO8601Date(fields): ISO8601Date

Parameters

fields: CalendarDateFields
- Date and time fields

newJapaneseDate

Construct a date in the Japanese calendar from one or more fields.

Syntax

newJapaneseDate(fields): JapaneseDate

Parameters

fields: CalendarDateFields
- Date and time fields

newPersianDate

Construct a date in the Persian calendar from one or more fields.

Syntax

newPersianDate(fields): PersianDate

Parameters

fields: CalendarDateFields
- Date and time fields

newISO8601Date

Construct a date in the ISO8601 calendar from one or more fields.

Syntax

newISO8601Date(fields): ISO8601Date

now

Construct a date in the Gregorian calendar representing the current date and time. Alias for nowGregorian

Syntax

now(zoneId?): GregorianDate

Parameters

zoneId?: string
- Timezone id. Defaults to 'Etc/UTC'

nowBuddhist

Construct a date in the Buddhist calendar representing the current date and time.

Syntax

nowBuddhist(zoneId?): BuddhistDate

Parameters

zoneId?: string
- Timezone id. Defaults to 'Etc/UTC'

Example

const en = framework.get("en");
log(en.Calendars.nowBuddhist());
log(en.Calendars.nowBuddhist("America/Los_Angeles"));

Buddhist 2022-12-06 22:48:02.635 Etc/UTC
Buddhist 2022-12-06 14:48:02.635 America/Los_Angeles

nowGregorian

Construct a date in the Gregorian calendar representing the current date and time.

Syntax

nowGregorian(zoneId?): GregorianDate

Parameters

zoneId?: string
- Timezone id. Defaults to 'Etc/UTC'

Example

const en = framework.get("en");
log(en.Calendars.nowGregorian());
log(en.Calendars.nowGregorian("America/Los_Angeles"));

Gregorian 2022-12-06 22:48:02.636 Etc/UTC
Gregorian 2022-12-06 14:48:02.636 America/Los_Angeles

nowISO8601

Construct a date in the ISO8601 calendar representing the current date and time.

Syntax

nowISO8601(zoneId?): ISO8601Date

Parameters

zoneId?: string
- Timezone id. Defaults to 'Etc/UTC'

Example

const en = framework.get("en");
log(en.Calendars.nowISO8601());
log(en.Calendars.nowISO8601("America/Los_Angeles"));

ISO8601 2022-12-06 22:48:02.637 Etc/UTC
ISO8601 2022-12-06 14:48:02.637 America/Los_Angeles

nowJapanese

Construct a date in the Japanese calendar representing the current date and time.

Syntax

nowJapanese(zoneId?): JapaneseDate

Parameters

zoneId?: string
- Timezone id. Defaults to 'Etc/UTC'

Example

const en = framework.get("en");
log(en.Calendars.nowJapanese());
log(en.Calendars.nowJapanese("America/Los_Angeles"));

Japanese 2022-12-06 22:48:02.637 Etc/UTC
Japanese 2022-12-06 14:48:02.638 America/Los_Angeles

nowPersian

Construct a date in the Persian calendar representing the current date and time.

Syntax

nowPersian(zoneId?): PersianDate

Parameters

zoneId?: string
- Timezone id. Defaults to 'Etc/UTC'

Example

const en = framework.get("en");
log(en.Calendars.nowPersian());
log(en.Calendars.nowPersian("America/Los_Angeles"));

Persian 1401-09-15 22:48:02.638 Etc/UTC
Persian 1401-09-15 14:48:02.638 America/Los_Angeles

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: Partial<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/Algiers
Africa/Bissau
Africa/Cairo
Africa/Casablanca
Africa/Ceuta
Africa/El_Aaiun
Africa/Johannesburg
Africa/Juba
Africa/Khartoum
...

timeZoneFromUTC

Returns the timezone info in effect for a timezone at a given UTC instant.

timeZoneFromUTC(timestamp, zoneid): ZoneInfo

Parameters

timestamp: number
- UTC timestamp in milliseconds.
id: string
- Time zone identifier.

Example

const en = framework.get("en");
const zoneid = "America/New_York";
// Sun Mar 8 2020 6:59 AM UTC
log(en.Calendars.timeZoneFromUTC(1583650740000, zoneid));
// 1 minute later
log(en.Calendars.timeZoneFromUTC(1583650800000, zoneid));

{ abbr: 'EST', dst: 0, offset: -18000000, zoneid: 'America/New_York' }
{ abbr: 'EDT', dst: 1, offset: -14400000, zoneid: 'America/New_York' }

timeZoneFromWall

Returns the timezone info in effect for a timezone at a given local "wall clock" instant. It returns a pair containing the adjusted UTC timestamp for the instant, and the timezone info.

Syntax

timeZoneFromWall(timestamp, zoneid): [number, ZoneInfo]

Parameters

timestamp: number
- Local "wall clock" timestamp in milliseconds.
id: string
- Time zone identifier.

Example

const en = framework.get("en");
const zoneid = "America/New_York";
// Sun Mar 8 2020 1:59 AM NY time
log(en.Calendars.timeZoneFromWall(1583632740000, zoneid));
// 1 minute later
log(en.Calendars.timeZoneFromWall(1583632800000, zoneid));

[
  1583650740000,
  {
    abbr: 'EST',
    dst: 0,
    offset: -18000000,
    zoneid: 'America/New_York'
  }
]
[
  1583650800000,
  {
    abbr: 'EDT',
    dst: 1,
    offset: -14400000,
    zoneid: 'America/New_York'
  }
]

timeData

Returns the preferred and allowed hour cycles for the current region.

Syntax

timeData(): TimeData

Example

const en = framework.get("en-US");
const info = en.Calendars.timeData();
log(info);

const date = {
  date: 1579633019000,
  zoneId: "America/New_York",
};

log(en.Calendars.formatDate(date, { skeleton: info.preferred }));
log(
  info.allowed.map((skeleton) => en.Calendars.formatDate(date, { skeleton }))
);

{ preferred: 'h', allowed: [ 'h', 'hb', 'H', 'hB' ] }
1 PM
[ '1 PM', '1 PM', '13', '1 in the afternoon' ]

timeZoneInfo

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

Syntax

timeZoneInfo(id): TimeZoneInfo[]

Parameters

id: string
- Time zone identifier.

Example

const en = framework.get("en");
const ids = [
  "America/New_York",
  "Pacific/Honolulu",
  "Europe/Berlin",
  "Asia/Tokyo",
];
for (const id of ids.slice(0, 4)) {
  log(en.Calendars.timeZoneInfo(id));
}
log("...");

{
  id: 'America/New_York',
  city: { name: 'New York' },
  countries: [ 'US' ],
  latitude: 40.714167,
  longitude: -74.006389,
  stdoffset: -18000000,
  metazone: 'America_Eastern',
  names: {
    long: {
      generic: 'Eastern Time',
      standard: 'Eastern Standard Time',
      daylight: 'Eastern Daylight Time'
    },
    short: { generic: 'ET', standard: 'EST', daylight: 'EDT' }
  }
}
{
  id: 'Pacific/Honolulu',
  city: { name: 'Unknown City' },
  countries: [ 'US', 'UM' ],
  latitude: 21.306944,
  longitude: -157.858333,
  stdoffset: -36000000,
  metazone: 'Hawaii_Aleutian',
  names: {
    long: {
      generic: 'Hawaii-Aleutian Time',
      standard: 'Hawaii-Aleutian Standard Time',
      daylight: 'Hawaii-Aleutian Daylight Time'
    },
    short: { generic: 'HAT', standard: 'HAST', daylight: 'HADT' }
  }
}
{
  id: 'Europe/Berlin',
  city: { name: 'Berlin' },
  countries: [ 'DE', 'DK', 'NO', 'SE', 'SJ' ],
  latitude: 52.5,
  longitude: 13.366667,
  stdoffset: 3600000,
  metazone: 'Europe_Central',
  names: {
    long: {
      generic: 'Central European Time',
      standard: 'Central European Standard Time',
      daylight: 'Central European Summer Time'
    },
    short: { generic: '', standard: '', daylight: '' }
  }
}
{
  id: 'Asia/Tokyo',
  city: { name: 'Tokyo' },
  countries: [ 'JP' ],
  latitude: 35.654444,
  longitude: 139.744722,
  stdoffset: 32400000,
  metazone: 'Japan',
  names: {
    long: {
      generic: 'Japan Time',
      standard: 'Japan Standard Time',
      daylight: 'Japan Daylight Time'
    },
    short: { generic: '', standard: '', daylight: '' }
  }
}
...

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 2018-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'
}

dateField​

Syntax​

Parameters​

Example​

dayPeriods​

Syntax​

Parameters​

Example​

eras​

Syntax​

Parameters​

Example​

fieldOfVisualDifference​

Syntax​

Parameters​

Return value​

Example​

firstDayOfWeek​

Syntax​

Example​

formatDate​

Syntax​

Parameters​

Example​

formatDateToParts​

Syntax​

Parameters​

Example​

formatDateInterval​

Syntax​

Parameters​

Example​

formatDateIntervalToParts​

Syntax​

Parameters​

Example​

formatDateRaw​

Syntax​

Parameters​

Example​

formatDateRawToParts​

Syntax​

Parameters​

Example​

formatDateWrapper​

Syntax​

Parameters​

Example​

formatDateWrapperToParts​

Syntax​

Parameters​

Example​

formatRelativeTime​

Syntax​

Parameters​

Example​

formatRelativeTimeField​

Syntax​

Parameters​

Example​

minDaysInFirstWeek​

Syntax​

Example​

months​

Syntax​

Parameters​

Example​

newBuddhistDate​

Syntax​

Parameters​

newGregorianDate​

Syntax​

Parameters​

Example​

newISO8601Date​

Syntax​

Parameters​

newJapaneseDate​

Syntax​

Parameters​

dateField

Syntax

Parameters

Example

dayPeriods

Syntax

Parameters

Example

eras

Syntax

Parameters

Example

fieldOfVisualDifference

Syntax

Parameters

Return value

Example

firstDayOfWeek

Syntax

Example

formatDate

Syntax

Parameters

Example

formatDateToParts

Syntax

Parameters

Example

formatDateInterval

Syntax

Parameters

Example

formatDateIntervalToParts

Syntax

Parameters

Example

formatDateRaw

Syntax

Parameters

Example

formatDateRawToParts

Syntax

Parameters

Example

formatDateWrapper

Syntax

Parameters

Example

formatDateWrapperToParts

Syntax

Parameters

Example

formatRelativeTime

Syntax

Parameters

Example

formatRelativeTimeField

Syntax

Parameters

Example

minDaysInFirstWeek

Syntax

Example

months

Syntax

Parameters

Example

newBuddhistDate

Syntax

Parameters

newGregorianDate

Syntax

Parameters

Example

newISO8601Date

Syntax

Parameters

newJapaneseDate

Syntax

Parameters