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.
Parameters:
isoMonth
(number): A month, ranging between 1 and 12 inclusive.isoDay
(number): A day of the month, ranging between 1 and 31 inclusive.calendar
(optional string): A calendar to project the date into.referenceISOYear
(optional for ISO 8601 calendar; required for other calendars):
A reference year in the ISO 8601 calendar for disambiguation when implementing calendar systems.
The default for the ISO 8601 calendar is the first leap year after the Unix epoch.
This value is required for other calendar systems. If you don't know what to put here, use the from
method instead.Returns: a new Temporal.PlainMonthDay
object.
The
calendar
andreferenceISOYear
parameters should be avoided becauseequals
orcompare
will considernew Temporal.PlainMonthDay(3, 14, 'iso8601', 1977)
andnew 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 use thefrom()
method which will automatically set a valid andequals
-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.
calendar
is a string containing the identifier of a built-in calendar, such as 'islamic'
or 'gregory'
.
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 legacyDate
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
Parameters:
item
: a value convertible to a Temporal.PlainMonthDay
.options
(optional object): An object with properties representing options for constructing the date.
The following options are recognized:overflow
(string): How to deal with out-of-range values if item
is an object.
Allowed values are 'constrain'
and 'reject'
.
The default is 'constrain'
.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:
day
propertymonthCode
or month
property.
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.calendar
property. If omitted, the ISO 8601 calendar will be used by default.If the value is not an object, it must be 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 item
is an object:
'constrain'
mode (the default), any out-of-range values are clamped to the nearest in-range value, with "nearest" defined by the calendar.'reject'
mode, the presence of out-of-range values will cause the function to throw a RangeError
.
If day
, month
and year
are provided, that calendar date must exist in the provided calendar or a RangeError
will be thrown.The overflow
option is ignored if item
is a string.
NOTE: The allowed values for the
item.month
property start at 1, which is different from legacyDate
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)
The above read-only properties allow accessing each component of the date individually.
monthCode
is a calendar-specific string that identifies the month in a year-independent way.
For common (non-leap) months, monthCode
should be
M${month}
, where month
is zero padded up to two digits.
For uncommon (leap) months in lunisolar calendars like Hebrew or Chinese, the month code is the previous month's code with an "L" suffix appended.
Examples: 'M02'
=> February; 'M08L'
=> repeated 8th month in the Chinese calendar; 'M05L'
=> Adar I in the Hebrew calendar.day
is a positive integer representing the day of the month.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)
The calendarId
read-only property gives the calendar that the monthCode
and day
properties are interpreted in.
Parameters:
monthDayLike
(object): an object with some or all of the properties that are accepted by Temporal.PlainMonthDay.from
.options
(optional object): An object with properties representing options for the operation.
The following options are recognized:overflow
(string): How to deal with out-of-range values.
Allowed values are 'constrain'
and 'reject'
.
The default is 'constrain'
.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":
'constrain'
mode (the default), any out-of-range values are clamped to the nearest in-range value, so June 31 would become June 30.'reject'
mode, the presence of out-of-range values will cause the constructor to throw a RangeError
.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 legacyDate
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
andtimeZone
properties are not allowed onmonthDayLike
. It is not possible to convert aTemporal.PlainMonthDay
to another calendar system without knowing the year. If you need to do this, usemonthDay.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
Parameters:
other
(Temporal.PlainMonthDay
or value convertible to one): Another month-day to compare.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.PlainMonthDay
s 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
Parameters:
options
(optional object): An object with properties influencing the formatting.
The following options are recognized:calendarName
(string): Whether to show the calendar annotation in the return value.
Valid values are 'auto'
, 'always'
, 'never'
, and 'critical'
.
The default is 'auto'
.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'
Parameters:
locales
(optional string or array of strings): A string with a BCP 47 language tag with an optional Unicode extension key, or an array of such strings.options
(optional object): An object with properties influencing the formatting.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}`); // => '8/24'
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.PlainMonthDay
s.
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);
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.
Parameters:
year
(object): An object with a 'year'
property, which must have a day corresponding to monthDay
.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]