Temporal.PlainMonthDay

Table of Contents

A Temporal.PlainMonthDay represents a particular day on the calendar, but without a year. For example, it could be used to represent a yearly recurring event, like "Bastille Day is on the 14th of July."

If you need to refer to a certain instance of a calendar event, in a particular year, use Temporal.PlainDate or even Temporal.PlainDateTime. A Temporal.PlainMonthDay can be converted into a Temporal.PlainDate by combining it with a year, using the toPlainDate() method.

Constructor

new Temporal.PlainMonthDay(isoMonth: number, isoDay: number, calendar: string | object = "iso8601", referenceISOYear: number = 1972) : Temporal.PlainMonthDay

Parameters:

Returns: a new Temporal.PlainMonthDay object.

The calendar and referenceISOYear parameters should be avoided because equals or compare will consider new Temporal.PlainMonthDay(3, 14, 'iso8601', 1977) and new Temporal.PlainMonthDay(3, 14, 'iso8601', 2000) unequal even though they refer to the same month and day. When creating instances for non-ISO-8601 calendars (except when implementing a custom calendar) use the from() method which will automatically set a valid and equals-compatible reference year.

All values are given as reckoned in the ISO 8601 calendar. Together, referenceISOYear, isoMonth, and isoDay must represent a valid date in that calendar, even if you are passing a different calendar as the calendar parameter.

Usually calendar will be a string containing the identifier of a built-in calendar, such as 'islamic' or 'gregory'. Use an object if you need to supply custom calendar behaviour.

The referenceISOYear ensures that month/day combinations like February 29 (a leap day in the ISO 8601 calendar) or 15 Adar I (in a leap month in the Hebrew calendar) can be used for Temporal.PlainMonthDay, even though those dates don't occur every calendar year. referenceISOYear corresponds to a calendar year where this month and day actually exist.

NOTE: The isoMonth argument ranges from 1 to 12, which is different from legacy Date where months are represented by zero-based indices (0 to 11).

Usage examples:

// Pi day
md = new Temporal.PlainMonthDay(3, 14); // => 03-14
// Leap day
md = new Temporal.PlainMonthDay(2, 29); // => 02-29

Static methods

Temporal.PlainMonthDay.from(thing: any, options?: object) : Temporal.PlainMonthDay

Parameters:

Returns: a new Temporal.PlainMonthDay object.

This static method creates a new Temporal.PlainMonthDay object from another value. If the value is a Temporal.PlainMonthDay, Temporal.PlainDate, Temporal.PlainDateTime, or Temporal.ZonedDateTime object, a new object representing the object's same month and day is returned. If the value is any other object, it:

Any non-object value will be converted to a string, which is expected to be in ISO 8601 format. For the ISO 8601 calendar, only the month and day will be parsed from the string. For other calendars, the year and calendar are also parsed in addition to month and day. Any other parts of the string are optional and will be ignored.

If the string isn't valid according to ISO 8601, then a RangeError will be thrown regardless of the value of overflow. A RangeError will also be thrown for strings that contain a Z in place of a numeric UTC offset, because interpreting these strings as a local date is usually a bug.

The overflow option works as follows, if thing is an object:

The overflow option is ignored if thing is a string.

NOTE: The allowed values for the thing.month property start at 1, which is different from legacy Date where months are represented by zero-based indices (0 to 11).

Example usage:

md = Temporal.PlainMonthDay.from('08-24'); // => 08-24
md = Temporal.PlainMonthDay.from('0824'); // => 08-24
md = Temporal.PlainMonthDay.from('2006-08-24'); // => 08-24
md = Temporal.PlainMonthDay.from('2006-08-24T15:43:27'); // => 08-24
md = Temporal.PlainMonthDay.from('2006-08-24T15:43:27+01:00[Europe/Brussels]');
// => 08-24
md === Temporal.PlainMonthDay.from(md); // => false

md = Temporal.PlainMonthDay.from({ monthCode: 'M08', day: 24 }); // => 08-24
md = Temporal.PlainMonthDay.from(Temporal.PlainDate.from('2006-08-24'));
// => 08-24
// (same as above; Temporal.PlainDate has month and day properties)

// Different overflow modes
md = Temporal.PlainMonthDay.from({ month: 13, day: 1, year: 2000 }, { overflow: 'constrain' });
// => 12-01
md = Temporal.PlainMonthDay.from({ month: 1, day: 32, year: 2000 }, { overflow: 'constrain' });
// => 01-31
md = Temporal.PlainMonthDay.from({ month: 13, day: 1, year: 2000 }, { overflow: 'reject' });
// => throws
md = Temporal.PlainMonthDay.from({ month: 1, day: 32, year: 2000 }, { overflow: 'reject' });
// => throws
md = Temporal.PlainMonthDay.from({ month: 2, day: 29, year: 2001 }, { overflow: 'reject' });
// => throws (this year is not a leap year in the ISO 8601 calendar)

// non-ISO calendars
md = Temporal.PlainMonthDay.from({ monthCode: 'M05L', day: 15, calendar: 'hebrew' });
// => 1970-02-21[u-ca=hebrew]
md = Temporal.PlainMonthDay.from({ month: 6, day: 15, year: 5779, calendar: 'hebrew' });
// => 1970-02-21[u-ca=hebrew]
/* WRONG */ md = Temporal.PlainMonthDay.from({ month: 6, day: 15, calendar: 'hebrew' });
// => throws (either year or monthCode is required)
md = Temporal.PlainMonthDay.from('2019-02-20[u-ca=hebrew]');
md.monthCode; // => 'M05L'
md.day; // => 15
md.month; // undefined
// (month property is not present in this type; use monthCode instead)

Properties

monthDay.monthCode : string

monthDay.day : number

The above read-only properties allow accessing each component of the date individually.

Note that this type has no month property, because month is ambiguous for some calendars without knowing the year. Instead, the monthCode property is used which is year-independent in all calendars.

Usage examples:

md = Temporal.PlainMonthDay.from('08-24');
md.monthCode; // => 'M08'
md.day; // => 24
md.month; // => undefined
// (no `month` property; use `monthCode` instead)

md = Temporal.PlainMonthDay.from('2019-02-20[u-ca=hebrew]');
md.monthCode; // => 'M05L'
md.day; // => 15
md.month; // => undefined
// (no `month` property; use `monthCode` instead)

monthDay.calendarId : object

The calendarId read-only property gives the calendar that the monthCode and day properties are interpreted in. If monthDay was created with a custom calendar object, this gives the id property of that object.

Methods

monthDay.with(monthDayLike: object, options?: object) : Temporal.PlainMonthDay

Parameters:

There are two ways to change the month: providing monthCode or month. If month is used and calendar is provided, then year must be provided as well because month is ambiguous in some calendars without knowing the year. If monthCode is provided in addition to month and/or year, then the properties must not conflict or a RangeError will be thrown.

Returns: a new Temporal.PlainMonthDay object.

This method creates a new Temporal.PlainMonthDay which is a copy of monthDay, but any properties present on monthDayLike override the ones already present on monthDay.

The overflow option tells what should happen when out-of-range values are given or when the result would be an invalid month-day combination, such as "June 31":

NOTE: For the purpose of this method, February is treated as having 29 days, so that it remains possible to construct a Temporal.PlainMonthDay for February 29.

NOTE: The allowed values for the monthDayLike.month property start at 1, which is different from legacy Date where months are represented by zero-based indices (0 to 11).

Since Temporal.PlainMonthDay objects each represent a fixed month and day, use this method instead of modifying one.

NOTE: calendar and timeZone properties are not allowed on monthDayLike. It is not possible to convert a Temporal.PlainMonthDay to another calendar system without knowing the year. If you need to do this, use monthDay.toPlainDate({ year }).withCalendar(calendar).toPlainMonthDay().

Usage example:

md = Temporal.PlainMonthDay.from('11-15');
// What's the last day of that month?
md.with({ day: 31 }); // => 11-30
Temporal.PlainMonthDay.from('02-01').with({ day: 31 }); // => 02-29

monthDay.equals(other: Temporal.PlainMonthDay | object | string) : boolean

Parameters:

Returns: true if monthDay and other are equal, or false if not.

Compares two Temporal.PlainMonthDay objects for equality.

This function exists because it's not possible to compare using monthDay == other or monthDay === other, due to ambiguity in the primitive representation and between Temporal types.

Note that two Temporal.PlainMonthDays expressed in different calendar systems can never be equal, because it's impossible to tell whether they fall on the same day without knowing the year.

If other is not a Temporal.PlainMonthDay object, then it will be converted to one as if it were passed to Temporal.PlainMonthDay.from().

Example usage:

md1 = Temporal.PlainMonthDay.from('02-28');
md2 = Temporal.PlainMonthDay.from('02-29');
md1.equals(md2); // => false
md1.equals('02-29'); // => false
md1.equals({ monthCode: 'M02', day: 29 }); // => false
md2.equals(md2); // => true
md2.equals('02-29'); // => true
md2.equals({ monthCode: 'M02', day: 29 }); // => true

monthDay.toString() : string

Parameters:

Returns: a string in the ISO 8601 date format representing monthDay.

This method overrides the Object.prototype.toString() method and provides a convenient, unambiguous string representation of monthDay. The string can be passed to Temporal.PlainMonthDay.from() to create a new Temporal.PlainMonthDay object.

Normally, a calendar annotation is shown when monthDay's calendar is not the ISO 8601 calendar. By setting the calendarName option to 'always' or 'never' this can be overridden to always or never show the annotation, respectively. Normally not necessary, a value of 'critical' is equivalent to 'always' but the annotation will contain an additional ! for certain interoperation use cases. For more information on the calendar annotation, see the Temporal string formats documentation.

Example usage:

md = Temporal.PlainMonthDay.from('08-24');
md.toString(); // => '08-24'

monthDay.toLocaleString(locales?: string | array<string>, options?: object) : string

Parameters:

Returns: a language-sensitive representation of monthDay.

This method overrides Object.prototype.toLocaleString() to provide a human-readable, language-sensitive representation of monthDay.

The locales and options arguments are the same as in the constructor to Intl.DateTimeFormat.

The calendar in the output locale (given by new Intl.DateTimeFormat(locales, options).resolvedOptions().calendar) must match monthDay.calendar, or this method will throw an exception. This is because it's not possible to convert a Temporal.PlainMonthDay from one calendar to another without more information. In order to ensure that the output always matches monthDay's internal calendar, you must either explicitly construct monthDay with the locale's calendar, or explicitly specify the calendar in the options parameter:

monthDay.toLocaleString(locales, { calendar: monthDay.calendar });

// OR

monthDay = Temporal.PlainMonthDay.from({ /* ... */, calendar: localeCalendar });
monthDay.toLocaleString();

Example usage:

let calendar;
({ calendar } = new Intl.DateTimeFormat().resolvedOptions());
md = Temporal.PlainMonthDay.from({ monthCode: 'M08', day: 24, calendar });
md.toLocaleString(); // example output: '8/24'
// Same as above, but explicitly specifying the calendar:
md.toLocaleString(undefined, { calendar }); // example output: '8/24'

md.toLocaleString('de-DE', { calendar }); // => '24.8.'
md.toLocaleString('de-DE', { month: 'long', day: 'numeric', calendar }); // => '24. August'
md.toLocaleString(`en-US-u-nu-fullwide-ca-${calendar}`); // => '８/２４'

monthDay.toJSON() : string

Returns: a string in the ISO 8601 date format representing monthDay.

This method is the same as monthDay.toString(). It is usually not called directly, but it can be called automatically by JSON.stringify().

The reverse operation, recovering a Temporal.PlainMonthDay object from a string, is Temporal.PlainMonthDay.from(), but it cannot be called automatically by JSON.parse(). If you need to rebuild a Temporal.PlainMonthDay object from a JSON string, then you need to know the names of the keys that should be interpreted as Temporal.PlainMonthDays. In that case you can build a custom "reviver" function for your use case.

Example usage:

const holiday = {
  name: 'Canada Day',
  holidayMonthDay: Temporal.PlainMonthDay.from({ monthCode: 'M07', day: 1 })
};
const str = JSON.stringify(holiday, null, 2);
console.log(str);
// =>
// {
//   "name": "Canada Day",
//   "holidayMonthDay": "07-01"
// }

// To rebuild from the string:
function reviver(key, value) {
  if (key.endsWith('MonthDay')) return Temporal.PlainMonthDay.from(value);
  return value;
}
JSON.parse(str, reviver);

monthDay.valueOf()

This method overrides Object.prototype.valueOf() and always throws an exception. This is because it's not possible to compare Temporal.PlainMonthDay objects with the relational operators <, <=, >, or >=. Instead, use monthDay.equals() to check for equality.

monthDay.toPlainDate(year: object) : Temporal.PlainDate

Parameters:

Returns: a Temporal.PlainDate object that represents the calendar date of monthDay in year.

This method can be used to convert Temporal.PlainMonthDay into a Temporal.PlainDate, by supplying a year to use. The converted object carries a copy of all the relevant fields of monthDay.

Usage example:

md = Temporal.PlainMonthDay.from('08-24');
md.toPlainDate({ year: 2017 }); // => 2017-08-24

md = Temporal.PlainMonthDay.from('02-29');
md.toPlainDate({ year: 2020 }); // => 2020-02-29
md.toPlainDate({ year: 2017 }); // => 2017-02-28

In calendars where more information than just the year is needed to convert a Temporal.PlainMonthDay to a Temporal.PlainDate, you can pass the necessary properties in the year object.

Example:

md = Temporal.PlainMonthDay.from({
  calendar: 'japanese',
  monthCode: 'M01',
  day: 1
});

date = md.toPlainDate({ era: 'reiwa', eraYear: 2 }); // => 2020-01-01[u-ca=japanese]

monthDay.getCalendar(): object

Returns: a Temporal.Calendar instance or plain object representing the calendar in which monthDay is reckoned.

This method is mainly useful if you need an object on which to call calendar methods. Most code will not need to use it.

monthDay.getISOFields(): { isoYear: number, isoMonth: number, isoDay: number, calendar: string | object }

Returns: a plain object with properties expressing monthDay in the ISO 8601 calendar, as well as the calendar (usually a string, but may be an object) in which monthDay is reckoned.

This method is mainly useful if you are implementing a custom calendar. Most code will not need to use it.

The value of the isoYear property will be equal to the referenceISOYear constructor argument passed when monthDay was constructed.

Usage example:

md = Temporal.PlainMonthDay.from('08-24');
md.getISOFields().isoDay; // => 24