From 7d9cdfe47732fed4a7270d6092c20185b9a614f9 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sun, 29 Dec 2024 22:06:35 -0500 Subject: [PATCH] PlainMonthDay docs, copy date-related fields to PlainDateTime --- .../temporal/duration/duration/index.md | 2 +- .../global_objects/temporal/duration/index.md | 2 +- .../temporal/duration/tolocalestring/index.md | 9 +- .../global_objects/temporal/index.md | 2 +- .../global_objects/temporal/instant/index.md | 2 +- .../temporal/instant/tolocalestring/index.md | 9 +- .../temporal/plaindate/add/index.md | 4 +- .../temporal/plaindate/compare/index.md | 6 +- .../temporal/plaindate/day/index.md | 15 +- .../temporal/plaindate/dayofweek/index.md | 2 +- .../temporal/plaindate/dayofyear/index.md | 2 +- .../temporal/plaindate/daysinmonth/index.md | 14 +- .../temporal/plaindate/daysinweek/index.md | 2 +- .../temporal/plaindate/daysinyear/index.md | 2 +- .../temporal/plaindate/equals/index.md | 8 +- .../temporal/plaindate/era/index.md | 2 +- .../temporal/plaindate/erayear/index.md | 2 +- .../temporal/plaindate/from/index.md | 6 +- .../temporal/plaindate/index.md | 13 +- .../temporal/plaindate/inleapyear/index.md | 2 +- .../temporal/plaindate/month/index.md | 3 +- .../temporal/plaindate/monthcode/index.md | 4 +- .../temporal/plaindate/monthsinyear/index.md | 2 +- .../temporal/plaindate/plaindate/index.md | 2 +- .../temporal/plaindate/subtract/index.md | 4 +- .../plaindate/tolocalestring/index.md | 21 +-- .../plaindate/toplaindatetime/index.md | 1 + .../plaindate/toplainmonthday/index.md | 1 + .../plaindate/toplainyearmonth/index.md | 1 + .../temporal/plaindate/tostring/index.md | 2 +- .../plaindate/tozoneddatetime/index.md | 1 + .../temporal/plaindate/until/index.md | 2 +- .../temporal/plaindate/weekofyear/index.md | 2 +- .../temporal/plaindate/with/index.md | 2 +- .../temporal/plaindate/year/index.md | 2 +- .../temporal/plaindate/yearofweek/index.md | 2 +- .../plaindatetime/calendarid/index.md | 21 ++- .../temporal/plaindatetime/day/index.md | 24 ++- .../temporal/plaindatetime/dayofweek/index.md | 24 ++- .../temporal/plaindatetime/dayofyear/index.md | 23 ++- .../plaindatetime/daysinmonth/index.md | 24 ++- .../plaindatetime/daysinweek/index.md | 24 ++- .../plaindatetime/daysinyear/index.md | 23 ++- .../temporal/plaindatetime/era/index.md | 24 ++- .../temporal/plaindatetime/erayear/index.md | 30 +++- .../temporal/plaindatetime/index.md | 36 +++-- .../plaindatetime/inleapyear/index.md | 24 ++- .../temporal/plaindatetime/month/index.md | 25 ++- .../temporal/plaindatetime/monthcode/index.md | 24 ++- .../plaindatetime/monthsinyear/index.md | 23 ++- .../plaindatetime/plaindatetime/index.md | 2 +- .../plaindatetime/weekofyear/index.md | 23 ++- .../temporal/plaindatetime/year/index.md | 24 ++- .../plaindatetime/yearofweek/index.md | 21 ++- .../plainmonthday/calendarid/index.md | 35 ++++- .../temporal/plainmonthday/day/index.md | 59 ++++++- .../temporal/plainmonthday/equals/index.md | 26 ++-- .../temporal/plainmonthday/from/index.md | 146 ++++++++++++++++-- .../temporal/plainmonthday/index.md | 60 +++++-- .../temporal/plainmonthday/monthcode/index.md | 51 +++++- .../plainmonthday/plainmonthday/index.md | 39 +++-- .../temporal/plainmonthday/tojson/index.md | 37 +++-- .../plainmonthday/tolocalestring/index.md | 68 ++++++-- .../plainmonthday/toplaindate/index.md | 36 +++-- .../temporal/plainmonthday/tostring/index.md | 61 ++++++-- .../temporal/plainmonthday/with/index.md | 53 +++++-- .../temporal/plaintime/index.md | 2 +- .../temporal/plaintime/plaintime/index.md | 2 +- .../temporal/plainyearmonth/index.md | 2 +- .../plainyearmonth/plainyearmonth/index.md | 2 +- .../temporal/zoneddatetime/index.md | 2 +- .../zoneddatetime/zoneddatetime/index.md | 2 +- 72 files changed, 965 insertions(+), 295 deletions(-) diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/duration/duration/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/duration/duration/index.md index 9b8ddfc729fc1b9..14ea602634fc0df 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/duration/duration/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/duration/duration/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.Duration.Duration The **`Temporal.Duration()`** constructor creates {{jsxref("Temporal.Duration")}} objects. -Like all other `Temporal` classes, you should usually construct `Temporal.Duration` objects using the {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}} static method, which can handle a variety of input types. +This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.Duration` objects using the {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}} static method, which can handle a variety of input types. ## Syntax diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/duration/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/duration/index.md index 9b08c52a4798f93..6fdad958c771e22 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/duration/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/duration/index.md @@ -83,7 +83,7 @@ Because a duration is a difference between two time points, it can be positive, ## Constructor - {{jsxref("Temporal/Duration/Duration", "Temporal.Duration()")}} - - : Creates a new `Temporal.Duration` object. + - : Creates a new `Temporal.Duration` object by directly supplying the underlying data. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/duration/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/duration/tolocalestring/index.md index 78d1366d8fb1232..1cde68e6e63a44c 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/duration/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/duration/tolocalestring/index.md @@ -23,20 +23,13 @@ toLocaleString(locales, options) The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used. -In implementations that support the [`Intl.DurationFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat), these parameters correspond exactly to the [`Intl.DurationFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat) constructor's parameters. Implementations without `Intl.DurationFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. +In implementations that support the [`Intl.DurationFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat), these parameters correspond exactly to the [`Intl.DurationFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat) constructor's parameters. Implementations without `Intl.DurationFormat` support return the exact same string as {{jsxref("Temporal/Duration/toString", "toString()")}}, ignoring both parameters. - `locales` {{optional_inline}} - - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat#locales) parameter of the `Intl.DurationFormat()` constructor. - - In implementations without `Intl.DurationFormat` support, this parameter is ignored and the host's locale is usually used. - - `options` {{optional_inline}} - - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat#options) parameter of the `Intl.DurationFormat()` constructor. - In implementations without `Intl.DurationFormat` support, this parameter is ignored. - See the [`Intl.DurationFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/DurationFormat) for details on these parameters and how to use them. ### Return value diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/index.md index ad9a31339de2312..a9c37abbed18e3f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/index.md @@ -334,7 +334,7 @@ The concept of a "week" is not connected with any astronomical event, but is a c - {{jsxref("Temporal.PlainDateTime")}} - : Represents a date (calendar date) and time (wall-clock time) without a time zone. It is fundamentally represented as a combination of a [date](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate) (with an associated calendar system) and a [time](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime). - {{jsxref("Temporal.PlainMonthDay")}} - - : Represents the month and day of a calendar date, without a year or time zone; for example, an event on a calendar that recurs every year and happens during the whole day. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The year is used to disambiguate the month-day in some calendar systems. + - : Represents the month and day of a calendar date, without a year or time zone; for example, an event on a calendar that recurs every year and happens during the whole day. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The year is used to disambiguate the month-day in non-ISO calendar systems. - {{jsxref("Temporal.PlainTime")}} - : Represents a time without a date or time zone; for example, a recurring event that happens at the same time every day. It is fundamentally represented as a combination of hour, minute, second, millisecond, microsecond, and nanosecond values. - {{jsxref("Temporal.PlainYearMonth")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md index 0e89b03eecb30f4..a67d018fb12d2d4 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/index.md @@ -47,7 +47,7 @@ When serializing, you can configure the fractional second digits and offset. ## Constructor - {{jsxref("Temporal/Instant/Instant", "Temporal.Instant()")}} - - : Creates a new `Temporal.Instant` object. + - : Creates a new `Temporal.Instant` object by directly supplying the underlying data. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/tolocalestring/index.md index 15558e3710e1df3..3c0a693a5e92574 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/tolocalestring/index.md @@ -23,20 +23,13 @@ toLocaleString(locales, options) The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used. -In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. +In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support return the exact same string as {{jsxref("Temporal/Instant/toString", "toString()")}}, ignoring both parameters. - `locales` {{optional_inline}} - - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) parameter of the `Intl.DateTimeFormat()` constructor. - - In implementations without `Intl.DateTimeFormat` support, this parameter is ignored and the host's locale is usually used. - - `options` {{optional_inline}} - - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) parameter of the `Intl.DateTimeFormat()` constructor. - In implementations without `Intl.DateTimeFormat` support, this parameter is ignored. - See the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) for details on these parameters and how to use them. ### Return value diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/add/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/add/index.md index 9631f4438d561d6..955b8dfebc0e2ee 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/add/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/add/index.md @@ -25,7 +25,7 @@ add(duration, options) - `overflow` {{optional_inline}} - : A string specifying the behavior when a date component is out of range. Possible values are: - `"constrain"` (default) - - : The date component is clamped to the valid range. + - : The date component is [clamped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping) to the valid range. - `"reject"` - : A {{jsxref("RangeError")}} is thrown if the date component is out of range. @@ -37,7 +37,7 @@ A new `Temporal.PlainDate` object representing the date specified by the origina The `duration` is handled in this way: -- Move forward by the number of years, keeping the `monthCode` and `day` the same. If the `monthCode` is invalid in the resulting year (impossible for Gregorian and ISO 8601, but possible for calendars with leap months), we adjust based on the `overflow` option: for `constrain`, we pick another month according to the cultural conventions of that calendar's users. For example, because the leap month is usually thought of as a duplicate of the previous month, we might choose the month before the leap month. +- Move forward by the number of years, keeping the `monthCode` and `day` the same. If the `monthCode` is invalid in the resulting year (impossible for Gregorian and ISO 8601, but possible for calendars with leap months), we adjust based on the `overflow` option: for `constrain`, we pick another month according to the cultural conventions of that calendar's users. For example, because the leap month is usually thought of as a duplicate of another month, we may pick the month that it is a duplicate of. - Move forward by the number of months, adjusting the year if necessary, keeping the `day` the same. If the `day` is invalid in the resulting month (e.g., February 30), we adjust based on the `overflow` option: for `constrain`, we pick the closest valid day (e.g., February 28 or 29). - All commonly supported calendars use fixed-length weeks, so the number of weeks is just converted to the number of days. If the rule is more complex, we may take an approach similar to shifting months. - For all [non-calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) units (days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds), they are converted to the number of days. Fractional part of a day is ignored. Then, we move forward by that number of days, adjusting the month and year if necessary. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/compare/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/compare/index.md index 6efe6fccceb109c..53f338b1cdf0b08 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/compare/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/compare/index.md @@ -34,10 +34,10 @@ Returns `-1` if `date1` comes before `date2`, `0` if they are the same, and `1` const date1 = Temporal.PlainDate.from("2021-08-01"); const date2 = Temporal.PlainDate.from("2021-08-02"); -console.log(Temporal.Instant.compare(instant1, instant2)); // -1 +console.log(Temporal.PlainDate.compare(date1, date2)); // -1 -const instant3 = Temporal.Instant.from("2021-07-31"); -console.log(Temporal.Instant.compare(instant1, instant3)); // 1 +const date3 = Temporal.PlainDate.from("2021-07-31"); +console.log(Temporal.PlainDate.compare(date1, date3)); // 1 ``` ### Comparing dates in different calendars diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/day/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/day/index.md index 5b7bedce840378f..c3b3608533673c5 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/day/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/day/index.md @@ -7,11 +7,14 @@ browser-compat: javascript.builtins.Temporal.PlainDate.day {{JSRef}} -The **`day`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`day`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. It generally starts at 1 and is continuous, but not always. If you want to loop through all the days in a month, first use {{jsxref("Temporal/PlainDate/with", "with()")}} with `{ day: 1 }` (which sets to the beginning of the month, even if the actual number is not `1`), then repeatedly use {{jsxref("Temporal/PlainDate/add", "add()")}} with `{ days: 1 }`, until the month changes. -The set accessor of `calendarId` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDate/with", "with()")}} method to create a new `Temporal.PlainDate` object with the desired new value. +> [!NOTE] +> Usually, the day index only changes when transitioning from one calendar system into another, such as [from the Julian to the Gregorian calendar](https://en.wikipedia.org/wiki/Adoption_of_the_Gregorian_calendar). In practice, all currently built-in calendars are [proleptic](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), meaning the calendar system is extended indefinitely into the past and future. Assuming `day` is non-continuous guards against future introductions of non-proleptic calendars. + +The set accessor of `day` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDate/with", "with()")}} method to create a new `Temporal.PlainDate` object with the desired new value. ## Examples @@ -54,14 +57,16 @@ const newDate = date.add({ days: 14 }); console.log(newDate.toString()); // 2021-07-15 ``` -By default, `with()` constrains the day to the range of valid values. So you can use `{ day: 1 }` to set the day to the first day of the month, even if the first day does not have the number `1`. Similarly, both of the following will set the day to the last day of the month: +By default, `with()` constrains the day to the range of valid values. So you can use `{ day: 1 }` to set the day to the first day of the month, even if the first day does not have the number `1`. Similarly, the following will set the day to the last day of the month: ```js const date = Temporal.PlainDate.from("2021-07-01"); -const lastDay = date.with({ day: date.daysInMonth }); // 2021-07-31 -const lastDay2 = date.with({ day: Number.MAX_VALUE }); // 2021-07-31 +const lastDay = date.with({ day: Number.MAX_VALUE }); // 2021-07-31 ``` +> [!NOTE] +> Avoid using {{jsxref("Temporal/PlainDate/daysInMonth", "daysInMonth")}} to set the day to the last day of the month. The last day of the month is not always the same as the number of days in the month, in the rare case where a month may have a few days skipped. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofweek/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofweek/index.md index 7b3317036fc4f16..ff330fcf9e1e6b0 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofweek/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofweek/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.dayOfWeek {{JSRef}} -The **`dayOfWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the week of this date. Days in a week are numbered sequentially from `1` to {{jsxref("Temporal/PlainDate/daysInWeek", "daysInWeek")}}, with each number mapping to its name. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. 1 usually represents Monday in the calendar, even when locales using the calendar may consider a different day as the first day of the week (see {{jsxref("Intl/Locale/getWeekInfo", "Intl.Locale.prototype.getWeekInfo()")}}). +The **`dayOfWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the week of this date. Days in a week are numbered sequentially from `1` to {{jsxref("Temporal/PlainDate/daysInWeek", "daysInWeek")}}, with each number mapping to its name. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. 1 usually represents Monday in the calendar, even when locales using the calendar may consider a different day as the first day of the week (see {{jsxref("Intl/Locale/getWeekInfo", "Intl.Locale.prototype.getWeekInfo()")}}). All commonly supported calendars use 7-day weeks, and you could generally expect this property to return the same value for the same date across different calendars. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofyear/index.md index 96d2bea9d087fd6..b284636ab436a0f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/dayofyear/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.dayOfYear {{JSRef}} -The **`dayOfYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the year of this date. The first day of this year is `1`, and the last day is the {{jsxref("Temporal/PlainDate/daysInYear", "daysInYear")}}. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`dayOfYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based day index in the year of this date. The first day of this year is `1`, and the last day is the {{jsxref("Temporal/PlainDate/daysInYear", "daysInYear")}}. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. The set accessor of `dayOfYear` is `undefined`. You cannot change this property directly. To create a new `Temporal.PlainDate` object with the desired new `dayOfYear` value, use the {{jsxref("Temporal/PlainDate/add", "add()")}} or {{jsxref("Temporal/PlainDate/subtract", "subtract()")}} method with the appropriate number of `days`. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinmonth/index.md index efd4ea447e3ab78..4b64fbb34c81e83 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinmonth/index.md @@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainDate.daysInMonth {{JSRef}} -The **`daysInMonth`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the month of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`daysInMonth`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the month of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. + +Note that the days in month is not always equal to the {{jsxref("Temporal/PlainDate/day", "day")}} of the last day of the month, in the rare case where a month may have a few days skipped. The set accessor of `daysInMonth` is `undefined`. You cannot change this property directly. @@ -40,6 +42,16 @@ const secondLastDay = date.with({ day: date.daysInMonth - 1 }); console.log(secondLastDay.toString()); // 2021-07-30 ``` +This is not totally safe, though, because `daysInMonth` is not guaranteed to have any connection with the day index. Here's a safer way to get the second last day: + +```js +const date = Temporal.PlainDate.from("2021-07-01"); +const secondLastDay = date + .with({ day: Number.MAX_SAFE_INTEGER }) + .subtract({ days: 1 }); +console.log(secondLastDay.toString()); // 2021-07-30 +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinweek/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinweek/index.md index 0c588bb05ae85f5..58b030522c47591 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinweek/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinweek/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.daysInWeek {{JSRef}} -The **`daysInWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the week of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`daysInWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the week of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For the ISO 8601 calendar, this is always 7, but in other calendar systems it may differ from week to week. All commonly supported calendars use 7-day weeks. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinyear/index.md index a9be99d7e178546..35bf63c80719c94 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/daysinyear/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.daysInYear {{JSRef}} -The **`daysInYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the year of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`daysInYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of days in the year of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For the ISO 8601 calendar, this is 365, or 366 in a leap year. In other calendar systems, it likely differs, especially in non-solar calendars. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/equals/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/equals/index.md index b9545ab223d2e21..9a86255ea04aada 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/equals/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/equals/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.equals {{JSRef}} -The **`equals()`** method of {{jsxref("Temporal.PlainDate")}} instances returns `true` if this date is equal to another date (in a form convertible by {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}), and `false` otherwise. They are compared both by their date values and their calendars. +The **`equals()`** method of {{jsxref("Temporal.PlainDate")}} instances returns `true` if this date is equivalent in value to another date (in a form convertible by {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}), and `false` otherwise. They are compared both by their date values and their calendars, so two dates from different calendars may be considered equal by {{jsxref("Temporal/PlainDate/compare", "Temporal.PlainDate.compare()")}} but not by `equals()`. ## Syntax @@ -31,13 +31,13 @@ equals(other) ```js const date1 = Temporal.PlainDate.from("2021-08-01"); const date2 = Temporal.PlainDate.from({ year: 2021, month: 8, day: 1 }); -console.log(instant1.equals(instant2)); // true +console.log(date1.equals(date2)); // true const date3 = Temporal.PlainDate.from("2021-08-01[u-ca=japanese]"); -console.log(instant1.equals(instant3)); // false +console.log(date1.equals(date3)); // false const date4 = Temporal.PlainDate.from("2021-08-02"); -console.log(instant1.equals(instant4)); // false +console.log(date1.equals(date4)); // false ``` ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md index 59e8db0ab36cce6..6cc7f66721daf2f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/era/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.era {{JSRef}} -The **`era`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g. ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For Gregorian, it is either `"gregory"` or `"gregory-inverse"`. +The **`era`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g. ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For Gregorian, it is either `"gregory"` or `"gregory-inverse"`. The set accessor of `era` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDate/with", "with()")}} method to create a new `Temporal.PlainDate` object with the desired new value. When setting eras, each code may have some aliases; for example, `"ce"` and `"ad"` are equivalent to `"gregory"`, and `"bce"` and `"bc"` are equivalent to `"gregory-inverse"`. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md index ea0ff8bf8c90c8e..52f58e193fa9dba 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/erayear/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.eraYear {{JSRef}} -The **`eraYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a non-negative integer representing the year of this date within the era, or `undefined` if the calendar does not use eras (e.g. ISO 8601). The year index usually starts from 1 (more common) or 0, and years in an era can decrease with time (e.g. Gregorian BCE). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`eraYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a non-negative integer representing the year of this date within the era, or `undefined` if the calendar does not use eras (e.g. ISO 8601). The year index usually starts from 1 (more common) or 0, and years in an era can decrease with time (e.g. Gregorian BCE). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. Unlike `year`, `era` and `eraYear` may change in the middle of a calendar year. For example, Japan started the Reiwa era on May 1, 2019, so dates from 2019-01-01 to 2019-04-30 have `{ era: "heisei", eraYear: 31 }`, and dates from 2019-05-01 onwards have `{ era: "reiwa", eraYear: 1 }`, but the `year` is always 2019 (because the Japanese calendar uses the ISO 8601 year as the default year). diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md index 760a61f792b0c89..e12947a86d6f20a 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/from/index.md @@ -40,20 +40,20 @@ Temporal.PlainDate.from(info, options) - `year` - : Corresponds to the {{jsxref("Temporal/PlainDate/year", "year")}} property. - - An [ISO 8601](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#iso_8601_format) string representing a duration. + - An [ISO 8601](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#iso_8601_format) string containing a date and optionally a calendar. - `options` {{optional_inline}} - : An object containing the following property: - `overflow` {{optional_inline}} - : A string specifying the behavior when a date component is out of range. Possible values are: - `"constrain"` (default) - - : The date component is clamped to the valid range. + - : The date component is [clamped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping) to the valid range. - `"reject"` - : A {{jsxref("RangeError")}} is thrown if the date component is out of range. ### Return value -A new `Temporal.PlainDate` object, representing the date specified by `info` (in the specified `calendar`), interpreted in the calendar system specified by `calendar`. +A new `Temporal.PlainDate` object, representing the date specified by `info` in the specified `calendar`. ### Exceptions diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md index 3f9276a6ebe6523..2975d16d33d5ff8 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/index.md @@ -11,6 +11,8 @@ The **`Temporal.PlainDate`** object represents a date without a time or time zon ## Description +A `PlainDate` is essentially the date part of a {{jsxref("Temporal.PlainDateTime")}} object, with the time information removed. Because the date and time information don't have much interaction, all general information about date properties is documented here. + ### ISO 8601 format `PlainDate` objects can be serialized and parsed using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) (with some extensions specified by ECMAScript). The string has the following form (spaces are only for readability and should not be present in the actual string): @@ -32,6 +34,15 @@ As an input, you may optionally include the time, offset, and time zone identifi When serializing, you can configure whether to display the calendar ID, and whether to add a critical flag for it. +### Invalid date clamping + +The {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}, {{jsxref("Temporal/PlainDate/with", "Temporal.PlainDate.prototype.with()")}}, {{jsxref("Temporal/PlainDate/add", "Temporal.PlainDate.prototype.add()")}}, {{jsxref("Temporal/PlainDate/subtract", "Temporal.PlainDate.prototype.subtract()")}} methods, and the counterparts in other `Temporal` objects, allow constructing dates using calendar-specific properties. The date components may be out of range. In the ISO calendar, this is always an _overflow_, such as the month being greater than 12 or the day being greater than the number of days, and fixing it would only involve clamping the value to the maximum allowed value. In other calendars, the invalid case may be more complex. When using the `overflow: "constrain"` option, invalid dates are fixed to a valid one in the following way: + +- If the day doesn't exist but the month does: pick the closest day in the same month. If there are two equally-close dates in that month, pick the later one. +- If the month is a leap month that doesn't exist in the year: pick another date according to the cultural conventions of that calendar's users. Usually this will result in the same day in the month before or after where that month would normally fall in a leap year. +- If the month doesn't exist in the year for other reasons: pick the closest date that is still in the same year. If there are two equally-close dates in that year, pick the later one. +- If the entire year doesn't exist: pick the closest date in a different year. If there are two equally-close dates, pick the later one. + ## Constructor - {{jsxref("Temporal/PlainDate/PlainDate", "Temporal.PlainDate()")}} @@ -90,7 +101,7 @@ These properties are defined on `Temporal.PlainDate.prototype` and shared by all - {{jsxref("Temporal/PlainDate/add", "Temporal.PlainDate.prototype.add()")}} - : Returns a new `Temporal.PlainDate` object representing this date moved forward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}). - {{jsxref("Temporal/PlainDate/equals", "Temporal.PlainDate.prototype.equals()")}} - - : Returns `true` if this date is equal to another date (in a form convertible by {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}), and `false` otherwise. They are compared both by their date values and their calendars. + - : Returns `true` if this date is equivalent in value to another date (in a form convertible by {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}), and `false` otherwise. They are compared both by their date values and their calendars. - {{jsxref("Temporal/PlainDate/since", "Temporal.PlainDate.prototype.since()")}} - : Returns a new {{jsxref("Temporal.Duration")}} object representing the duration from another date (in a form convertible by {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}) to this date. The duration is positive if the other date is before this date, and negative if after. - {{jsxref("Temporal/PlainDate/subtract", "Temporal.PlainDate.prototype.subtract()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/inleapyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/inleapyear/index.md index d153af9c107be08..cc0d0ee486e78db 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/inleapyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/inleapyear/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.inLeapYear {{JSRef}} -The **`inLeapYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a boolean indicating whether this date is in a leap year. A leap year is a year that has more days (a leap day or leap month) than a common year. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`inLeapYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a boolean indicating whether this date is in a leap year. A leap year is a year that has more days (a leap day or leap month) than a common year. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For the ISO 8601 calendar, a leap year is a year that is evenly divisible by 4, except for years that are evenly divisible by 100, unless the year is also evenly divisible by 400. For the ISO 8601 calendar, leap years have 366 days, while common years have 365 days. For other calendar systems, the rules likely differ, and leap years may have more days added (such as a leap month). diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/month/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/month/index.md index d7a9b8b2da0fd9d..e787faf7f98d6ee 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/month/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/month/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.month {{JSRef}} -The **`month`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based month index in the year of this date. The first month of this year is `1`, and the last month is the {{jsxref("Temporal/PlainDate/monthsInYear", "monthsInYear")}}. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`month`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based month index in the year of this date. The first month of this year is `1`, and the last month is the {{jsxref("Temporal/PlainDate/monthsInYear", "monthsInYear")}}. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. Note that unlike {{jsxref("Date/getMonth", "Date.prototype.getMonth()")}}, the index is 1-based. If the calendar has leap months, then the month with the same {{jsxref("Temporal/PlainDate/monthCode", "monthCode")}} may have different `month` indexes for different years. @@ -95,6 +95,7 @@ const lastMonth2 = date.with({ month: Number.MAX_VALUE }); // 2021-12-01 - {{jsxref("Temporal/PlainDate/add", "Temporal.PlainDate.prototype.add()")}} - {{jsxref("Temporal/PlainDate/subtract", "Temporal.PlainDate.prototype.subtract()")}} - {{jsxref("Temporal/PlainDate/year", "Temporal.PlainDate.prototype.year")}} +- {{jsxref("Temporal/PlainDate/day", "Temporal.PlainDate.prototype.day")}} - {{jsxref("Temporal/PlainDate/monthCode", "Temporal.PlainDate.prototype.monthCode")}} - {{jsxref("Temporal/PlainDate/daysInMonth", "Temporal.PlainDate.prototype.daysInMonth")}} - {{jsxref("Temporal/PlainDate/monthsInYear", "Temporal.PlainDate.prototype.monthsInYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md index f32e4837850bcbc..c830cafac1af69e 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthcode/index.md @@ -7,9 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainDate.monthCode {{JSRef}} -The **`monthCode`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a calendar-specific string representing the month of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`monthCode`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a calendar-specific string representing the month of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -Usually it is `M` plus a two-digit month number. For leap months, it is the previous month's code followed by `L`. If the leap month is the first month of the year, the code is `M00L`. +Usually it is `M` plus a two-digit month number. For leap months, it is the previous month's code followed by `L` (even if it's conceptually a derivative of the following month; for example, in the Hebrew calendar, Adar I has code `M05L` but Adar II has code `M06`). If the leap month is the first month of the year, the code is `M00L`. > [!NOTE] > Don't assume that `monthCode` is a user-friendly string; use `toLocaleString()` to format your date instead. Generally, don't cache the name of months in an array or object. Even though `monthCode` usually maps to the month's name within one calendar, we recommend always computing the month's name using, for example, `date.toLocaleString("en-US", { calendar: date.calendarId, month: "long" })`. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthsinyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthsinyear/index.md index 68086a017790839..cd2aa5b608dafca 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthsinyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/monthsinyear/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.monthsInYear {{JSRef}} -The **`monthsInYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of months in the year of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`monthsInYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the number of months in the year of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. For the ISO 8601 calendar, this is always 12, but in other calendar systems it may differ. For example, in calendars using leap months, leap years will have one more month than common years. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md index 9b26073bd39f163..fd3e8802f4a774c 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/plaindate/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.PlainDate The **`Temporal.PlainDate()`** constructor creates {{jsxref("Temporal.PlainDate")}} objects. -Like all other `Temporal` classes, you should usually construct `Temporal.PlainDate` objects using the {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}} static method, which can handle a variety of input types. +This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.PlainDate` objects using the {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}} static method, which can handle a variety of input types. ## Syntax diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/subtract/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/subtract/index.md index f3e5001364b80f0..623ce15a22473c0 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/subtract/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/subtract/index.md @@ -25,7 +25,7 @@ subtract(duration, options) - `overflow` {{optional_inline}} - : A string specifying the behavior when a date component is out of range. Possible values are: - `"constrain"` (default) - - : The date component is clamped to the valid range. + - : The date component is [clamped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping) to the valid range. - `"reject"` - : A {{jsxref("RangeError")}} is thrown if the date component is out of range. @@ -62,5 +62,5 @@ For more examples, see {{jsxref("Temporal/PlainDate/add", "add()")}}. - {{jsxref("Temporal.PlainDate")}} - {{jsxref("Temporal.Duration")}} - {{jsxref("Temporal/PlainDate/add", "Temporal.PlainDate.prototype.add()")}} -- {{jsxref("Temporal/PlainDate/since", "Temporal.Instant.prototype.since()")}} +- {{jsxref("Temporal/PlainDate/since", "Temporal.PlainDate.prototype.since()")}} - {{jsxref("Temporal/PlainDate/until", "Temporal.PlainDate.prototype.until()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tolocalestring/index.md index c5ee999d0318b71..c82fc97765192f0 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tolocalestring/index.md @@ -23,14 +23,10 @@ toLocaleString(locales, options) The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used. -In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support are asked to ignore both parameters, making the locale used and the form of the string returned entirely implementation-dependent. +In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support return the exact same string as {{jsxref("Temporal/PlainDate/toString", "toString()")}}, ignoring both parameters. - `locales` {{optional_inline}} - - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) parameter of the `Intl.DateTimeFormat()` constructor. - - In implementations without `Intl.DateTimeFormat` support, this parameter is ignored and the host's locale is usually used. - - `options` {{optional_inline}} - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) parameter of the `Intl.DateTimeFormat()` constructor. If this date's calendar is not `"iso8601"`, the `calendar` option must be provided with the same value; otherwise, if this date's calendar is `"iso8601"`, the `calendar` option can be any value. Regarding the [date-time component options](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#date-time_component_options) and the style shortcuts (`dateStyle` and `timeStyle`), the options should follow one of these forms: @@ -39,8 +35,6 @@ In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/ - Provide `dateStyle` only. - Provide some date-time component options, where at least one of them is a date option (`weekday`, `year`, `month`, `day`). Only the specified date components will be included in the output. - In implementations without `Intl.DateTimeFormat` support, this parameter is ignored. - See the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) for details on these parameters and how to use them. ### Return value @@ -71,11 +65,12 @@ const date = Temporal.PlainDate.from("2021-08-01"); console.log(date.toLocaleString()); // 8/1/2021 (assuming en-US locale) ``` -If the date's calendar is not ISO 8601, when formatting, the `calendar` option must be provided with the same value. +If the date's calendar doesn't match the locale's default calendar, and the date's calendar is not `iso8601`, an explicit `calendar` option must be provided with the same value. ```js -const date = Temporal.PlainDate.from("2021-08-01", { calendar: "gregory" }); -date.toLocaleString("en-US", { calendar: "gregory" }); // 8/1/2021 +const date = Temporal.PlainDate.from("2021-08-01[u-ca=japanese]"); +// The ja-JP locale uses the Gregorian calendar by default +date.toLocaleString("ja-JP", { calendar: "japanese" }); // R3/8/1 ``` ### Using toLocaleString() with options @@ -103,7 +98,7 @@ date.toLocaleString("en-US", { year: "numeric", month: "long" }); // August 2021 ## See also -- {{jsxref("Temporal.Instant")}} +- {{jsxref("Temporal.PlainDate")}} - {{jsxref("Intl.DateTimeFormat")}} -- {{jsxref("Temporal/Instant/toJSON", "Temporal.Instant.prototype.toJSON()")}} -- {{jsxref("Temporal/Instant/toString", "Temporal.Instant.prototype.toString()")}} +- {{jsxref("Temporal/PlainDate/toJSON", "Temporal.PlainDate.prototype.toJSON()")}} +- {{jsxref("Temporal/PlainDate/toString", "Temporal.PlainDate.prototype.toString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplaindatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplaindatetime/index.md index ad0cf896b753a32..0764e27ae6b9d59 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplaindatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplaindatetime/index.md @@ -58,3 +58,4 @@ console.log(dateTime2.toString()); // 2021-07-01T12:34:56[u-ca=chinese] - {{jsxref("Temporal/PlainDate/toPlainMonthDay", "Temporal.PlainDate.prototype.toPlainMonthDay()")}} - {{jsxref("Temporal/PlainDate/toPlainYearMonth", "Temporal.PlainDate.prototype.toPlainYearMonth()")}} - {{jsxref("Temporal/PlainDate/toZonedDateTime", "Temporal.PlainDate.prototype.toZonedDateTime()")}} +- {{jsxref("Temporal/PlainDateTime/toPlainDate", "Temporal.PlainDateTime.prototype.toPlainDate()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainmonthday/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainmonthday/index.md index a6a91e46c170a78..bec062d14802886 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainmonthday/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainmonthday/index.md @@ -50,3 +50,4 @@ console.log(monthDay.toString()); // 07-01 - {{jsxref("Temporal/PlainDate/toPlainDateTime", "Temporal.PlainDate.prototype.toPlainDateTime()")}} - {{jsxref("Temporal/PlainDate/toPlainYearMonth", "Temporal.PlainDate.prototype.toPlainYearMonth()")}} - {{jsxref("Temporal/PlainDate/toZonedDateTime", "Temporal.PlainDate.prototype.toZonedDateTime()")}} +- {{jsxref("Temporal/PlainMonthDay/toPlainDate", "Temporal.PlainMonthDay.prototype.toPlainDate()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainyearmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainyearmonth/index.md index 577478660427600..d4e48aec26dc405 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainyearmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/toplainyearmonth/index.md @@ -48,3 +48,4 @@ console.log(yearMonth.toString()); // 2021-07 - {{jsxref("Temporal/PlainDate/toPlainDateTime", "Temporal.PlainDate.prototype.toPlainDateTime()")}} - {{jsxref("Temporal/PlainDate/toPlainMonthDay", "Temporal.PlainDate.prototype.toPlainMonthDay()")}} - {{jsxref("Temporal/PlainDate/toZonedDateTime", "Temporal.PlainDate.prototype.toZonedDateTime()")}} +- {{jsxref("Temporal/PlainYearMonth/toPlainDate", "Temporal.PlainYearMonth.prototype.toPlainDate()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tostring/index.md index 6f9dfa39f6dcc21..cff1999e0b2ad16 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tostring/index.md @@ -33,7 +33,7 @@ toString(options) ### Return value -A string in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant#iso_8601_format) representing this date. The calendar annotation is included as specified. +A string in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#iso_8601_format) representing this date. The calendar annotation is included as specified. ### Exceptions diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tozoneddatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tozoneddatetime/index.md index 85587611787a6c9..221decf02eec297 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tozoneddatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/tozoneddatetime/index.md @@ -83,3 +83,4 @@ console.log(springTime.toString()); // 2021-03-01T00:00:00-05:00[America/New_Yor - {{jsxref("Temporal/PlainDate/toPlainDateTime", "Temporal.PlainDate.prototype.toPlainDateTime()")}} - {{jsxref("Temporal/PlainDate/toPlainMonthDay", "Temporal.PlainDate.prototype.toPlainMonthDay()")}} - {{jsxref("Temporal/PlainDate/toPlainYearMonth", "Temporal.PlainDate.prototype.toPlainYearMonth()")}} +- {{jsxref("Temporal/ZonedDateTime/toPlainDate", "Temporal.ZonedDateTime.prototype.toPlainDate()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/until/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/until/index.md index 71f73459b75cd50..8b113468dd30406 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/until/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/until/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.until {{JSRef}} -The **`until()`** method of {{jsxref("Temporal.PlainDate")}} instances returns a new {{jsxref("Temporal.Duration")}} object representing the duration from this date to another date (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}). The duration is positive if the other date is after this date, and negative if before. +The **`until()`** method of {{jsxref("Temporal.PlainDate")}} instances returns a new {{jsxref("Temporal.Duration")}} object representing the duration from this date to another date (in a form convertible by {{jsxref("Temporal/PlainDate/from", "Temporal.PlainDate.from()")}}). The duration is positive if the other date is after this date, and negative if before. This method does `other - this`. To do `this - other`, use the {{jsxref("Temporal/PlainDate/since", "since()")}} method. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/weekofyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/weekofyear/index.md index 2827c844820b9e7..0feb1c764efa8f0 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/weekofyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/weekofyear/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.weekOfYear {{JSRef}} -The **`weekOfYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based week index in the {{jsxref("Temporal/PlainDate/yearOfWeek", "yearOfWeek")}} of this date, or `undefined` if the calendar does not have a well-defined week system. The first week of the year is `1`. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`weekOfYear`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns a positive integer representing the 1-based week index in the {{jsxref("Temporal/PlainDate/yearOfWeek", "yearOfWeek")}} of this date, or `undefined` if the calendar does not have a well-defined week system. The first week of the year is `1`. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. Note that for ISO 8601, the first and last few days of the year may be attributed to the last week of the previous year or the first week of the next year. Namely, if a week crosses two years, then it belongs to the year that has the majority of its days. To get the year that the `weekOfYear` belongs to, use the {{jsxref("Temporal/PlainDate/yearOfWeek", "yearOfWeek")}} property, not the {{jsxref("Temporal/PlainDate/year", "year")}} property. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/with/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/with/index.md index b24dc34fbabc130..1ff9e53ac81e55c 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/with/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/with/index.md @@ -37,7 +37,7 @@ with(info, options) - `overflow` {{optional_inline}} - : A string specifying the behavior when a date component is out of range. Possible values are: - `"constrain"` (default) - - : The date component is clamped to the valid range. + - : The date component is [clamped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping) to the valid range. - `"reject"` - : A {{jsxref("RangeError")}} is thrown if the date component is out of range. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md index 9f54daa934f0132..7fa39b49bd2d478 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/year/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.year {{JSRef}} -The **`year`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns an integer representing the number of years of this date relative to the start of a calendar-specific epoch year. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`year`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns an integer representing the number of years of this date relative to the start of a calendar-specific epoch year. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. This property has the same function as the {{jsxref("Temporal/PlainDate/era", "era")}}/{{jsxref("Temporal/PlainDate/eraYear", "eraYear")}} pair as a unique identifier of a year in a calendar. Usually year 1 is either the first year of the latest era or the ISO 8601 year `0001`. Because `year` is relative to the start of the epoch year, not the epoch date, if the epoch is in the middle of the year, the year will have the same value before and after the start date of the era. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/yearofweek/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/yearofweek/index.md index 045b54bca68b247..373dd37b05d8103 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/yearofweek/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindate/yearofweek/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainDate.yearOfWeek {{JSRef}} -The **`yearOfWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns an integer representing the year to be paired with the {{jsxref("Temporal/PlainDate/weekOfYear", "weekOfYear")}} of this date, or `undefined` if the calendar does not have a well-defined week system. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. +The **`yearOfWeek`** accessor property of {{jsxref("Temporal.PlainDate")}} instances returns an integer representing the year to be paired with the {{jsxref("Temporal/PlainDate/weekOfYear", "weekOfYear")}} of this date, or `undefined` if the calendar does not have a well-defined week system. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. Usually this is the year of the date, but for ISO 8601, the first and last few days of the year may be attributed to the last week of the previous year or the first week of the next year, causing the `yearOfWeek` to differ by 1. See {{jsxref("Temporal/PlainDate/weekOfYear", "weekOfYear")}} for more details. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/calendarid/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/calendarid/index.md index 7629d5522fe9cc6..18413f1783c5bb9 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/calendarid/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/calendarid/index.md @@ -7,15 +7,26 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.calendarId {{JSRef}} -The **`calendarId`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`calendarId`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a string representing the [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars) used to interpret the internal ISO 8601 date. -## Description +For a list of commonly supported values, see {{jsxref("Intl/Locale/getCalendars", "Intl.Locale.prototype.getCalendars()")}}. -TODO +The set accessor of `calendarId` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/withCalendar", "withCalendar()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value. ## Examples -TODO +### Using calendarId + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T08:00:00"); +console.log(dt.calendarId); // "iso8601"; default + +const dt2 = Temporal.PlainDateTime.from("2021-07-01T08:00:00[u-ca=chinese]"); +console.log(dt2.calendarId); // "chinese" + +const dt3 = dt2.withCalendar("hebrew"); +console.log(dt3.calendarId); // "hebrew" +``` ## Specifications @@ -27,4 +38,4 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/day/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/day/index.md index bcc98340e3c44fa..b391d071f6effd4 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/day/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/day/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.day {{JSRef}} -The **`day`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`day`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `day` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/day", "Temporal.PlainDate.prototype.day")}}. ## Examples -TODO +### Using day + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); // ISO 8601 calendar +console.log(dt.day); // 1 +``` ## Specifications @@ -27,4 +32,13 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}} +- {{jsxref("Temporal/PlainDateTime/daysInMonth", "Temporal.PlainDateTime.prototype.daysInMonth")}} +- {{jsxref("Temporal/PlainDateTime/dayOfWeek", "Temporal.PlainDateTime.prototype.dayOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/dayOfYear", "Temporal.PlainDateTime.prototype.dayOfYear")}} +- {{jsxref("Temporal/PlainDate/day", "Temporal.PlainDate.prototype.day")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofweek/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofweek/index.md index b7cf76cb4f7f782..c121b1709998e01 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofweek/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofweek/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.dayOfWeek {{JSRef}} -The **`dayOfWeek`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`dayOfWeek`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the 1-based day index in the week of this date. Days in a week are numbered sequentially from `1` to {{jsxref("Temporal/PlainDateTime/daysInWeek", "daysInWeek")}}, with each number mapping to its name. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `dayOfWeek` is `undefined`. You cannot change this property directly. To create a new `Temporal.PlainDateTime` object with the desired new `dayOfWeek` value, use the {{jsxref("Temporal/PlainDateTime/add", "add()")}} or {{jsxref("Temporal/PlainDateTime/subtract", "subtract()")}} method with the appropriate number of `days`. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/dayOfWeek", "Temporal.PlainDate.prototype.dayOfWeek")}}. ## Examples -TODO +### Using dayOfWeek + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.dayOfWeek); // 4; Thursday +``` ## Specifications @@ -27,4 +32,13 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/day", "Temporal.PlainDateTime.prototype.day")}} +- {{jsxref("Temporal/PlainDateTime/dayOfYear", "Temporal.PlainDateTime.prototype.dayOfYear")}} +- {{jsxref("Temporal/PlainDateTime/daysInWeek", "Temporal.PlainDateTime.prototype.daysInWeek")}} +- {{jsxref("Temporal/PlainDateTime/weekOfYear", "Temporal.PlainDateTime.prototype.weekOfYear")}} +- {{jsxref("Temporal/PlainDateTime/yearOfWeek", "Temporal.PlainDateTime.prototype.yearOfWeek")}} +- {{jsxref("Temporal/PlainDate/dayOfWeek", "Temporal.PlainDate.prototype.dayOfWeek")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofyear/index.md index b89d1086fd39521..4ae32ce4db39912 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/dayofyear/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.dayOfYear {{JSRef}} -The **`dayOfYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`dayOfYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the 1-based day index in the year of this date. The first day of this year is `1`, and the last day is the {{jsxref("Temporal/PlainDateTime/daysInYear", "daysInYear")}}. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `dayOfYear` is `undefined`. You cannot change this property directly. To create a new `Temporal.PlainDateTime` object with the desired new `dayOfYear` value, use the {{jsxref("Temporal/PlainDateTime/add", "add()")}} or {{jsxref("Temporal/PlainDateTime/subtract", "subtract()")}} method with the appropriate number of `days`. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/dayOfYear", "Temporal.PlainDate.prototype.dayOfYear")}}. ## Examples -TODO +### Using dayOfYear + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.dayOfYear); // 182 +``` ## Specifications @@ -27,4 +32,12 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/day", "Temporal.PlainDateTime.prototype.day")}} +- {{jsxref("Temporal/PlainDateTime/dayOfWeek", "Temporal.PlainDateTime.prototype.dayOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}} +- {{jsxref("Temporal/PlainDate/dayOfYear", "Temporal.PlainDate.prototype.dayOfYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinmonth/index.md index 42647b45b004a41..8014207b9300141 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinmonth/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.daysInMonth {{JSRef}} -The **`daysInMonth`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`daysInMonth`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the number of days in the month of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `daysInMonth` is `undefined`. You cannot change this property directly. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/daysInMonth", "Temporal.PlainDate.prototype.daysInMonth")}}. ## Examples -TODO +### Using daysInMonth + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.daysInMonth); // 31 +``` ## Specifications @@ -27,4 +32,13 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}} +- {{jsxref("Temporal/PlainDateTime/day", "Temporal.PlainDateTime.prototype.day")}} +- {{jsxref("Temporal/PlainDateTime/daysInWeek", "Temporal.PlainDateTime.prototype.daysInWeek")}} +- {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}} +- {{jsxref("Temporal/PlainDate/daysInMonth", "Temporal.PlainDate.prototype.daysInMonth")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinweek/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinweek/index.md index 3adaf21a52dd6a2..d476c3622a02fb2 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinweek/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinweek/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.daysInWeek {{JSRef}} -The **`daysInWeek`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`daysInWeek`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the number of days in the week of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `daysInWeek` is `undefined`. You cannot change this property directly. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/daysInWeek", "Temporal.PlainDate.prototype.daysInWeek")}}. ## Examples -TODO +### Using daysInWeek + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.daysInWeek); // 7 +``` ## Specifications @@ -27,4 +32,13 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/yearOfWeek", "Temporal.PlainDateTime.prototype.yearOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/weekOfYear", "Temporal.PlainDateTime.prototype.weekOfYear")}} +- {{jsxref("Temporal/PlainDateTime/dayOfWeek", "Temporal.PlainDateTime.prototype.dayOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/daysInMonth", "Temporal.PlainDateTime.prototype.daysInMonth")}} +- {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}} +- {{jsxref("Temporal/PlainDate/daysInWeek", "Temporal.PlainDate.prototype.daysInWeek")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinyear/index.md index a0036042c6743b9..9c538aeae053ec2 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/daysinyear/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.daysInYear {{JSRef}} -The **`daysInYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`daysInYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the number of days in the year of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `daysInWeek` is `undefined`. You cannot change this property directly. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/daysInYear", "Temporal.PlainDate.prototype.daysInYear")}}. ## Examples -TODO +### Using daysInYear + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.daysInYear); // 365 +``` ## Specifications @@ -27,4 +32,12 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/dayOfYear", "Temporal.PlainDateTime.prototype.dayOfYear")}} +- {{jsxref("Temporal/PlainDateTime/daysInMonth", "Temporal.PlainDateTime.prototype.daysInMonth")}} +- {{jsxref("Temporal/PlainDateTime/daysInWeek", "Temporal.PlainDateTime.prototype.daysInWeek")}} +- {{jsxref("Temporal/PlainDate/daysInYear", "Temporal.PlainDate.prototype.daysInYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md index bebc3c1a0917115..2331707500393b4 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/era/index.md @@ -7,15 +7,23 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.era {{JSRef}} -The **`era`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`era`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g. ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `era` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/era", "Temporal.PlainDate.prototype.era")}}. ## Examples -TODO +### Using era + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); // ISO 8601 calendar +console.log(dt.era); // undefined + +const dt2 = Temporal.PlainDateTime.from("2021-07-01[u-ca=gregory]"); +console.log(dt2.era); // gregory +``` ## Specifications @@ -27,4 +35,10 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/eraYear", "Temporal.PlainDateTime.prototype.eraYear")}} +- {{jsxref("Temporal/PlainDate/era", "Temporal.PlainDate.prototype.era")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/erayear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/erayear/index.md index 0ecd83c4663ff34..9e020d5620740de 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/erayear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/erayear/index.md @@ -7,15 +7,29 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.eraYear {{JSRef}} -The **`eraYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`eraYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a non-negative integer representing the year of this date within the era, or `undefined` if the calendar does not use eras (e.g. ISO 8601). The year index usually starts from 1 (more common) or 0, and years in an era can decrease with time (e.g. Gregorian BCE). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `eraYear` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/eraYear", "Temporal.PlainDate.prototype.eraYear")}}. ## Examples -TODO +### Using eraYear + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); // ISO 8601 calendar +console.log(dt.eraYear); // undefined + +const dt2 = Temporal.PlainDateTime.from("2021-07-01[u-ca=gregory]"); +console.log(dt2.eraYear); // 2021 + +const dt3 = Temporal.PlainDateTime.from("-002021-07-01[u-ca=gregory]"); +console.log(dt3.eraYear); // 2022; 0000 is used for the year 1 BC + +const dt4 = Temporal.PlainDateTime.from("2021-07-01[u-ca=japanese]"); +console.log(dt4.eraYear); // 3 +``` ## Specifications @@ -27,4 +41,10 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/era", "Temporal.PlainDateTime.prototype.era")}} +- {{jsxref("Temporal/PlainDate/eraYear", "Temporal.PlainDate.prototype.eraYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md index 8c12599a6f179f7..92239c936cfb7e7 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/index.md @@ -11,6 +11,8 @@ The **`Temporal.PlainDateTime`** object represents a date (calendar date) and ti ## Description +A `PlainDateTime` is essentially the combination of a {{jsxref("Temporal.PlainDate")}} and a {{jsxref("Temporal.PlainTime")}}. Because the date and time information don't have much interaction, all general information about date properties is documented in the `PlainDate` object, and all general information about time properties is documented in the `PlainTime` object. + ### ISO 8601 format `PlainDateTime` objects can be serialized and parsed using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) (with some extensions specified by ECMAScript). The string has the following form (spaces are only for readability and should not be present in the actual string): @@ -43,7 +45,7 @@ When serializing, you can configure the fractional second digits, whether to dis ## Constructor - {{jsxref("Temporal/PlainDateTime/PlainDateTime", "Temporal.PlainDateTime()")}} - - : Creates a new `Temporal.PlainDateTime` object. + - : Creates a new `Temporal.PlainDateTime` object by directly supplying the underlying data. ## Static methods @@ -57,29 +59,29 @@ When serializing, you can configure the fractional second digits, whether to dis These properties are defined on `Temporal.PlainDateTime.prototype` and shared by all `Temporal.PlainDateTime` instances. - {{jsxref("Temporal/PlainDateTime/calendarId", "Temporal.PlainDateTime.prototype.calendarId")}} - - : TODO + - : Returns a string representing the [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars) used to interpret the internal ISO 8601 date. - {{jsxref("Object/constructor", "Temporal.PlainDateTime.prototype.constructor")}} - : The constructor function that created the instance object. For `Temporal.PlainDateTime` instances, the initial value is the {{jsxref("Temporal/PlainDateTime/PlainDateTime", "Temporal.PlainDateTime()")}} constructor. - {{jsxref("Temporal/PlainDateTime/day", "Temporal.PlainDateTime.prototype.day")}} - - : TODO + - : Returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/dayOfWeek", "Temporal.PlainDateTime.prototype.dayOfWeek")}} - - : TODO + - : Returns a positive integer representing the 1-based day index in the week of this date. Days in a week are numbered sequentially from `1` to {{jsxref("Temporal/PlainDateTime/daysInWeek", "daysInWeek")}}, with each number mapping to its name. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/dayOfYear", "Temporal.PlainDateTime.prototype.dayOfYear")}} - - : TODO + - : Returns a positive integer representing the 1-based day index in the year of this date. The first day of this year is `1`, and the last day is the {{jsxref("Temporal/PlainDateTime/daysInYear", "daysInYear")}}. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/daysInMonth", "Temporal.PlainDateTime.prototype.daysInMonth")}} - - : TODO + - : Returns a positive integer representing the number of days in the month of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/daysInWeek", "Temporal.PlainDateTime.prototype.daysInWeek")}} - - : TODO + - : Returns a positive integer representing the number of days in the week of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}} - - : TODO + - : Returns a positive integer representing the number of days in the year of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/era", "Temporal.PlainDateTime.prototype.era")}} - - : TODO + - : Returns a calendar-specific lowercase string representing the era of this date, or `undefined` if the calendar does not use eras (e.g. ISO 8601). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/eraYear", "Temporal.PlainDateTime.prototype.eraYear")}} - - : TODO + - : Returns a non-negative integer representing the year of this date within the era, or `undefined` if the calendar does not use eras (e.g. ISO 8601). The year index usually starts from 1 (more common) or 0, and years in an era can decrease with time (e.g. Gregorian BCE). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/hour", "Temporal.PlainDateTime.prototype.hour")}} - : TODO - {{jsxref("Temporal/PlainDateTime/inLeapYear", "Temporal.PlainDateTime.prototype.inLeapYear")}} - - : TODO + - : Returns a boolean indicating whether this date is in a leap year. A leap year is a year that has more days (a leap day or leap month) than a common year. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}} - : TODO - {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}} @@ -87,21 +89,21 @@ These properties are defined on `Temporal.PlainDateTime.prototype` and shared by - {{jsxref("Temporal/PlainDateTime/minute", "Temporal.PlainDateTime.prototype.minute")}} - : TODO - {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}} - - : TODO + - : Returns a positive integer representing the 1-based month index in the year of this date. The first month of this year is `1`, and the last month is the {{jsxref("Temporal/PlainDateTime/monthsInYear", "monthsInYear")}}. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/monthCode", "Temporal.PlainDateTime.prototype.monthCode")}} - - : TODO + - : Returns a calendar-specific string representing the month of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/monthsInYear", "Temporal.PlainDateTime.prototype.monthsInYear")}} - - : TODO + - : Returns a positive integer representing the number of months in the year of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}} - : TODO - {{jsxref("Temporal/PlainDateTime/second", "Temporal.PlainDateTime.prototype.second")}} - : TODO - {{jsxref("Temporal/PlainDateTime/weekOfYear", "Temporal.PlainDateTime.prototype.weekOfYear")}} - - : TODO + - : Returns a positive integer representing the 1-based week index in the {{jsxref("Temporal/PlainDateTime/yearOfWeek", "yearOfWeek")}} of this date, or `undefined` if the calendar does not have a well-defined week system. The first week of the year is `1`. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} - - : TODO + - : Returns an integer representing the number of years of this date relative to the start of a calendar-specific epoch year. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainDateTime/yearOfWeek", "Temporal.PlainDateTime.prototype.yearOfWeek")}} - - : TODO + - : Returns an integer representing the year to be paired with the {{jsxref("Temporal/PlainDateTime/weekOfYear", "weekOfYear")}} of this date, or `undefined` if the calendar does not have a well-defined week system. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - `Temporal.PlainDateTime.prototype[Symbol.toStringTag]` - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Temporal.PlainDateTime"`. This property is used in {{jsxref("Object.prototype.toString()")}}. diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/inleapyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/inleapyear/index.md index 51f60de68342425..6bc7c23e3f2f16d 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/inleapyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/inleapyear/index.md @@ -7,15 +7,22 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.inLeapYear {{JSRef}} -The **`inLeapYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`inLeapYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a boolean indicating whether this date is in a leap year. A leap year is a year that has more days (a leap day or leap month) than a common year. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `inLeapYear` is `undefined`. You cannot change this property directly. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/inLeapYear", "Temporal.PlainDate.prototype.inLeapYear")}}. ## Examples -TODO +### Using inLeapYear + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.inLeapYear); // false +console.log(dt.daysInYear); // 365 +console.log(dt.monthsInYear); // 12 +``` ## Specifications @@ -27,4 +34,11 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}} +- {{jsxref("Temporal/PlainDateTime/monthsInYear", "Temporal.PlainDateTime.prototype.monthsInYear")}} +- {{jsxref("Temporal/PlainDate/inLeapYear", "Temporal.PlainDate.prototype.inLeapYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/month/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/month/index.md index 93254e6aa4c47bf..b3add32074d8df3 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/month/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/month/index.md @@ -7,15 +7,21 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.month {{JSRef}} -The **`month`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`month`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the 1-based month index in the year of this date. The first month of this year is `1`, and the last month is the {{jsxref("Temporal/PlainDateTime/monthsInYear", "monthsInYear")}}. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `month` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/month", "Temporal.PlainDate.prototype.month")}}. ## Examples -TODO +### Using month + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); // ISO 8601 calendar +console.log(dt.monthCode); // "M07" +console.log(dt.month); // 7 +``` ## Specifications @@ -27,4 +33,13 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/day", "Temporal.PlainDateTime.prototype.day")}} +- {{jsxref("Temporal/PlainDateTime/monthCode", "Temporal.PlainDateTime.prototype.monthCode")}} +- {{jsxref("Temporal/PlainDateTime/daysInMonth", "Temporal.PlainDateTime.prototype.daysInMonth")}} +- {{jsxref("Temporal/PlainDateTime/monthsInYear", "Temporal.PlainDateTime.prototype.monthsInYear")}} +- {{jsxref("Temporal/PlainDate/month", "Temporal.PlainDate.prototype.month")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthcode/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthcode/index.md index 3fbcb6c549a7f6d..5ec5500ce694ff7 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthcode/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthcode/index.md @@ -7,15 +7,21 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.monthCode {{JSRef}} -The **`monthCode`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`monthCode`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a calendar-specific string representing the month of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `monthCode` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/monthCode", "Temporal.PlainDate.prototype.monthCode")}}. ## Examples -TODO +### Using monthCode + +```js +const date = Temporal.PlainDateTime.from("2021-07-01"); // ISO 8601 calendar +console.log(date.monthCode); // "M07" +console.log(date.month); // 7 +``` ## Specifications @@ -27,4 +33,12 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}} +- {{jsxref("Temporal/PlainDateTime/daysInMonth", "Temporal.PlainDateTime.prototype.daysInMonth")}} +- {{jsxref("Temporal/PlainDateTime/monthsInYear", "Temporal.PlainDateTime.prototype.monthsInYear")}} +- {{jsxref("Temporal/PlainDate/monthCode", "Temporal.PlainDate.prototype.monthCode")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthsinyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthsinyear/index.md index b56ed2086c1a551..25aa0a9d880a6c6 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthsinyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/monthsinyear/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.monthsInYear {{JSRef}} -The **`monthsInYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`monthsInYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the number of months in the year of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `monthsInYear` is `undefined`. You cannot change this property directly. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/monthsInYear", "Temporal.PlainDate.prototype.monthsInYear")}}. ## Examples -TODO +### Using monthsInYear + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.monthsInYear); // 12 +``` ## Specifications @@ -27,4 +32,12 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}} +- {{jsxref("Temporal/PlainDateTime/monthCode", "Temporal.PlainDateTime.prototype.monthCode")}} +- {{jsxref("Temporal/PlainDateTime/daysInMonth", "Temporal.PlainDateTime.prototype.daysInMonth")}} +- {{jsxref("Temporal/PlainDate/monthsInYear", "Temporal.PlainDate.prototype.monthsInYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md index 995192e19743d83..c684397fe6b3eec 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/plaindatetime/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.PlainDateTime The **`Temporal.PlainDateTime()`** constructor creates {{jsxref("Temporal.PlainDateTime")}} objects. -Like all other `Temporal` classes, you should usually construct `Temporal.PlainDateTime` objects using the {{jsxref("Temporal/PlainDateTime/from", "Temporal.PlainDateTime.from()")}} static method, which can handle a variety of input types. +This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.PlainDateTime` objects using the {{jsxref("Temporal/PlainDateTime/from", "Temporal.PlainDateTime.from()")}} static method, which can handle a variety of input types. ## Syntax diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/weekofyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/weekofyear/index.md index 512c011734e29ed..56edce75046590a 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/weekofyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/weekofyear/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.weekOfYear {{JSRef}} -The **`weekOfYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`weekOfYear`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a positive integer representing the 1-based week index in the {{jsxref("Temporal/PlainDateTime/yearOfWeek", "yearOfWeek")}} of this date, or `undefined` if the calendar does not have a well-defined week system. The first week of the year is `1`. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `weekOfYear` is `undefined`. You cannot change this property directly. To create a new `Temporal.PlainDateTime` object with the desired new `weekOfYear` value, use the {{jsxref("Temporal/PlainDateTime/add", "add()")}} or {{jsxref("Temporal/PlainDateTime/subtract", "subtract()")}} method with the appropriate number of `weeks`. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/weekOfYear", "Temporal.PlainDate.prototype.weekOfYear")}}. ## Examples -TODO +### Using weekOfYear + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); +console.log(dt.weekOfYear); // 26 +``` ## Specifications @@ -27,4 +32,12 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/yearOfWeek", "Temporal.PlainDateTime.prototype.yearOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/dayOfWeek", "Temporal.PlainDateTime.prototype.dayOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/daysInWeek", "Temporal.PlainDateTime.prototype.daysInWeek")}} +- {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}} +- {{jsxref("Temporal/PlainDate/weekOfYear", "Temporal.PlainDate.prototype.weekOfYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/year/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/year/index.md index 1d7f5695ddb87eb..f71d4e560dbac4e 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/year/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/year/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.year {{JSRef}} -The **`year`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`year`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns an integer representing the number of years of this date relative to the start of a calendar-specific epoch year. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `year` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/year", "Temporal.PlainDate.prototype.year")}}. ## Examples -TODO +### Using year + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01"); // ISO 8601 calendar +console.log(dt.year); // 2021 +``` ## Specifications @@ -27,4 +32,13 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/era", "Temporal.PlainDateTime.prototype.era")}} +- {{jsxref("Temporal/PlainDateTime/eraYear", "Temporal.PlainDateTime.prototype.eraYear")}} +- {{jsxref("Temporal/PlainDateTime/yearOfWeek", "Temporal.PlainDateTime.prototype.yearOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}} +- {{jsxref("Temporal/PlainDateTime/day", "Temporal.PlainDateTime.prototype.day")}} +- {{jsxref("Temporal/PlainDate/year", "Temporal.PlainDate.prototype.year")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/yearofweek/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/yearofweek/index.md index e4600c6c70c2d1a..6920061dd600420 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/yearofweek/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/yearofweek/index.md @@ -7,15 +7,11 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.yearOfWeek {{JSRef}} -The **`yearOfWeek`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`yearOfWeek`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns an integer representing the year to be paired with the {{jsxref("Temporal/PlainDateTime/weekOfYear", "weekOfYear")}} of this date, or `undefined` if the calendar does not have a well-defined week system. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `yearOfWeek` is `undefined`. You cannot change this property directly. -TODO - -## Examples - -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/yearOfWeek", "Temporal.PlainDate.prototype.yearOfWeek")}}. ## Specifications @@ -27,4 +23,13 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainDateTime")}} +- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}} +- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}} +- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}} +- {{jsxref("Temporal/PlainDateTime/weekOfYear", "Temporal.PlainDateTime.prototype.weekOfYear")}} +- {{jsxref("Temporal/PlainDateTime/dayOfWeek", "Temporal.PlainDateTime.prototype.dayOfWeek")}} +- {{jsxref("Temporal/PlainDateTime/daysInWeek", "Temporal.PlainDateTime.prototype.daysInWeek")}} +- {{jsxref("Temporal/PlainDateTime/daysInYear", "Temporal.PlainDateTime.prototype.daysInYear")}} +- {{jsxref("Temporal.PlainDate/yearOfWeek", "Temporal.PlainDate.prototype.yearOfWeek")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/calendarid/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/calendarid/index.md index 88df8b2b231beff..18d9460dec975e8 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/calendarid/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/calendarid/index.md @@ -7,15 +7,40 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.calendarId {{JSRef}} -The **`calendarId`** accessor property of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`calendarId`** accessor property of {{jsxref("Temporal.PlainMonthDay")}} instances returns a string representing the [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars) used to interpret the internal ISO 8601 date. -## Description +For a list of commonly supported values, see {{jsxref("Intl/Locale/getCalendars", "Intl.Locale.prototype.getCalendars()")}}. -TODO +The set accessor of `calendarId` is `undefined`. You cannot change this property directly. There's no obvious way to create a new `Temporal.PlainMonthDay` object with a different calendar that represents the same month-day, so you need to convert it to a {{jsxref("Temporal.PlainDate")}} object first using {{jsxref("Temporal/PlainMonthDay/toPlainDate", "toPlainDate()")}}, change the calendar, and then convert it back. ## Examples -TODO +### Using calendarId + +```js +const md = Temporal.PlainMonthDay.from("07-01"); +console.log(md.calendarId); // "iso8601"; default + +const md2 = Temporal.PlainMonthDay.from("07-01[u-ca=chinese]"); +console.log(md2.calendarId); // "chinese" +``` + +### Changing calendarId + +```js +const md = Temporal.PlainMonthDay.from("07-01"); +const newMD = md + .toPlainDate({ year: 2021 }) + .withCalendar("chinese") + .toPlainMonthDay(); +console.log(newMD.monthCode, newMD.day); // "M05", 22 + +const newMD2 = md + .toPlainDate({ year: 2022 }) + .withCalendar("chinese") + .toPlainMonthDay(); +console.log(newMD2.monthCode, newMD2.day); // "M06", 3 +``` ## Specifications @@ -27,4 +52,4 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/day/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/day/index.md index 049e2e30b55fe09..fde9d94f15bc797 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/day/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/day/index.md @@ -7,15 +7,62 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.day {{JSRef}} -The **`day`** accessor property of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`day`** accessor property of {{jsxref("Temporal.PlainMonthDay")}} instances returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +The set accessor of `day` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainMonthDay/with", "with()")}} method to create a new `Temporal.PlainMonthDay` object with the desired new value. -TODO +For general information and more examples, see {{jsxref("Temporal/PlainDate/day", "Temporal.PlainDate.prototype.day")}}. ## Examples -TODO +### Using day + +```js +const md = Temporal.PlainMonthDay.from("07-01"); // ISO 8601 calendar +console.log(md.day); // 1 + +const md2 = Temporal.PlainMonthDay.from("2021-07-01[u-ca=chinese]"); +console.log(md2.day); // 22; it is May 22 in the Chinese calendar +``` + +### Changing day + +```js +const md = Temporal.PlainMonthDay.from("07-01"); +const newMD = md.with({ day: 15 }); +console.log(newMD.toString()); // 07-15 +``` + +By default, `with()` constrains the day to the range of valid values. So you can use `{ day: 1 }` to set the day to the first day of the month, even if the first day does not have the number `1`. Similarly, the following will set the day to the last day of the month: + +```js +const md = Temporal.PlainMonthDay.from("07-01"); +const lastMD = md.with({ day: Number.MAX_VALUE }); // 07-31 +``` + +For the purpose of `PlainMonthDay`, February is always considered to have 29 days. + +```js +const md = Temporal.PlainMonthDay.from("02-01"); +const lastMD = md.with({ day: Number.MAX_VALUE }); // 02-29 +console.log(lastMD.day); // 29 +``` + +For other calendars, as long as there exists a year in which the month-day is valid, the month-day is considered valid, and the underlying reference year may therefore change. For example: + +```js +const md = Temporal.PlainMonthDay.from({ + monthCode: "M02", + day: 29, + calendar: "hebrew", +}); +console.log(md.toString()); // 1972-11-06[u-ca=hebrew] +console.log(md.toLocaleString("en-US", { calendar: "hebrew" })); // 29 Heshvan +const lastMD = md.with({ day: Number.MAX_VALUE }); +// 30 Heshvan does not exist in 1972, so the reference year changes to 1971 +console.log(lastMD.toString()); // 1971-11-18[u-ca=hebrew] +console.log(lastMD.toLocaleString("en-US", { calendar: "hebrew" })); // 30 Heshvan +``` ## Specifications @@ -27,4 +74,6 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal/PlainMonthDay/with", "Temporal.PlainMonthDay.prototype.with()")}} +- {{jsxref("Temporal/PlainMonthDay/monthCode", "Temporal.PlainMonthDay.prototype.monthCode")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/equals/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/equals/index.md index a9a82b39a25dcbf..d37ca8bf79263ce 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/equals/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/equals/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.equals {{JSRef}} -The **`equals()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`equals()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns `true` if this month-day is equivalent in value to another month-day (in a form convertible by {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}}), and `false` otherwise. They are compared both by their date values and their calendars. ## Syntax @@ -18,23 +18,27 @@ equals(other) ### Parameters - `other` - - : TODO + - : A string, an object, or a {{jsxref("Temporal.PlainMonthDay")}} instance representing the other month-day to compare. It is converted to a `Temporal.PlainMonthDay` object using the same algorithm as {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}}. ### Return value -TODO +`true` if this month-day is equal to `other` both in their date value and their calendar, `false` otherwise. -### Exceptions - -TODO +## Examples -## Description +### Using equals() -TODO +```js +const md1 = Temporal.PlainMonthDay.from("2021-08-01"); +const md2 = Temporal.PlainMonthDay.from({ year: 2020, month: 8, day: 1 }); // Year doesn't matter +console.log(md1.equals(md2)); // true -## Examples +const md3 = Temporal.PlainMonthDay.from("2021-08-01[u-ca=japanese]"); +console.log(md1.equals(md3)); // false -TODO +const md4 = Temporal.PlainDate.from("2021-08-02"); +console.log(md1.equals(md4)); // false +``` ## Specifications @@ -46,4 +50,4 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/from/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/from/index.md index fb450ef2975bf16..59589ec4e0d5509 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/from/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/from/index.md @@ -19,25 +19,151 @@ Temporal.PlainMonthDay.from(info, options) ### Parameters - `info` - - : TODO + + - : One of the following: + + - A {{jsxref("Temporal.PlainMonthDay")}} instance, which creates a copy of the instance. + - An object containing the following properties (in the order they are retrieved and validated): + + - `calendar` {{optional_inline}} + - : A string that corresponds to the {{jsxref("Temporal/PlainMonthDay/calendarId", "calendarId")}} property. Defaults to `"iso8601"`. All other properties are interpreted in this calendar system (unlike the {{jsxref("Temporal/PlainMonthDay/PlainMonthDay", "Temporal.PlainMonthDay()")}} constructor, which interprets the values in the ISO calendar system). + - `day` + - : An integer that corresponds to the {{jsxref("Temporal/PlainMonthDay/day", "day")}} property. Must be positive regardless of the `overflow` option. + - `era` and `eraYear` {{optional_inline}} + - : A string and an integer that can be used instead of `year`. See {{jsxref("Temporal/PlainDate/era", "era")}} and {{jsxref("Temporal/PlainDate/eraYear", "eraYear")}} of `PlainDate`. Are only used if the calendar system has eras. `era` and `eraYear` must be provided simultaneously. If all of `era`, `eraYear`, and `year` are provided, they must be consistent. + - `month` {{optional_inline}} + - : A positive integer that can be used instead of `monthCode`. See {{jsxref("Temporal/PlainDate/month", "month")}} of `PlainDate`. Must be positive regardless of the `overflow` option. If `month` is provided, and the calendar is not `iso8601`, then `year` (or `era` + `eraYear` as a substitution) must be provided too, because the same `month` may map to multiple possible `monthCode` values in different years. + - `monthCode` + - : Corresponds to the {{jsxref("Temporal/PlainMonthDay/monthCode", "monthCode")}} property. If both `month` and `monthCode` are provided, they must be consistent. + - `year` {{optional_inline}} + - : An integer used to disambiguate `month` if provided, because for some calendars, the same `month` can mean different `monthCode` in different years. See {{jsxref("Temporal/PlainDate/year", "year")}} of `PlainDate`. If a year is provided, then the `overflow` option validates the month-day in the given year, not just any year. + + Other `Temporal` objects, such as {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainDateTime")}} and {{jsxref("Temporal.ZonedDateTime")}}, conform to this shape and can be used as well. + + - An [ISO 8601](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#iso_8601_format) string containing a date and optionally a calendar. If the calendar is not `iso8601`, a year is required. + - `options` {{optional_inline}} - - : TODO + - : An object containing the following property: + - `overflow` {{optional_inline}} + - : A string specifying the behavior when a date component is out of range. Possible values are: + - `"constrain"` (default) + - : The date component is [clamped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping) to the valid range. + - `"reject"` + - : A {{jsxref("RangeError")}} is thrown if the date component is out of range. ### Return value -TODO +A new `Temporal.PlainMonthDay` object, representing the month and day specified by `info` in the specified `calendar`. -### Exceptions +Each `PlainMonthDay` stores a whole ISO 8601 date internally, which has the same month-day in the target calendar as what's exposed. The reference year is visible when stringifying with {{jsxref("Temporal/PlainMonthDay/toString", "toString()")}}, which outputs an ISO date. The reference year is chosen arbitrarily but consistently (that is, every `(monthCode, day)` pair always maps to the same ISO reference year). It does not use the year provided in the input. Instead, the reference year is chosen by finding the latest date before December 31, 1972 that has the same month-day in the target calendar, or the earliest date after December 31, 1972 if no such date exists. -TODO +For example, for Gregorian-derived calendars, the reference year is 1972. For the Hebrew calendar, the reference year is 1972 in the Gregorian calendar, but if the month is Adar I (`M05L`), which is a leap month, the reference year is 1970 (5730 in Hebrew calendar) instead, because the next leap year is 1973 (5733 in Hebrew calendar), which is after 1972. -## Description +### Exceptions -TODO +- {{jsxref("TypeError")}} + - : Thrown in one of the following cases: + - `info` is not an object or a string. + - `options` is not an object or `undefined`. + - The provided properties are insufficient to unambiguously determine a date. You usually need to provide a `year` (or `era` and `eraYear`), a `month`, and a `day`, or a `monthCode` and a `day`. +- {{jsxref("RangeError")}} + - : Thrown in one of the following cases: + - The provided properties that specify the same component are inconsistent. + - The provided non-numerical properties are not valid, for example, `monthCode` is not a valid month code. + - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`. ## Examples -TODO +### Creating a PlainMonthDay from an object + +```js +// Month code + day +const md = Temporal.PlainMonthDay.from({ monthCode: "M05", day: 2 }); +console.log(md.toString()); // 05-02 + +// Month + day (only for ISO calendar) +const md2 = Temporal.PlainMonthDay.from({ month: 7, day: 1 }); +console.log(md2.toString()); // 07-01 + +// Year + month + day +const md3 = Temporal.PlainMonthDay.from({ year: 2021, month: 7, day: 1 }); +console.log(md3.toString()); // 07-01 + +// Year + month + day in a different calendar (where year is required) +const md4 = Temporal.PlainMonthDay.from({ + year: 2021, + month: 7, + day: 1, + calendar: "hebrew", +}); +console.log(md4.toString()); // 1972-03-16[u-ca=hebrew] + +// Month code + day in a different calendar +const md5 = Temporal.PlainMonthDay.from({ + monthCode: "M05L", + day: 1, + calendar: "hebrew", +}); +console.log(md5.toString()); // 1970-02-07[u-ca=hebrew] +``` + +### Controlling overflow behavior + +By default, out-of-range values are clamped to the valid range. A month-day without an explicit reference year is valid as long as there exists one year in which it is valid, even if it doesn't appear every year. If year, month, and day are all given, then the rules for mapping to a valid month-day could be complex and specific to each calendar, but here's the usual behavior: + +- If the `year`/`month` combination is invalid, the `month` is clamped to obtain a valid `monthCode` in the year. +- If the `year`/`monthCode` combination is invalid, a different year is chosen to keep the `monthCode` as-is. +- The `day` is clamped in the given year-month to obtain a valid month-day. + +This is slightly different from usual [date clamping](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping), which favors the year over the month code. + +```js +// Month always out of range +const md1 = Temporal.PlainMonthDay.from({ month: 13, day: 1 }); +console.log(md1.toString()); // 12-01 + +// Month out of range for the specific year: 5732 is not a Hebrew leap year, +// so month is clamped to 12 to resolve to a valid monthCode +const md2 = Temporal.PlainMonthDay.from({ + year: 5732, + month: 13, + day: 1, + calendar: "hebrew", +}); +console.log(md2.toLocaleString("en-US", { calendar: "hebrew" })); // 1 Elul +const underlyingDate = Temporal.PlainDate.from(md2.toString()); +console.log(underlyingDate.year, underlyingDate.month); // 5732 12 + +// Month code exists but not for the specific year: 5731 is not a Hebrew leap year, +// so a different year is chosen to keep the monthCode as M05L +const md3 = Temporal.PlainMonthDay.from({ + year: 5731, + monthCode: "M05L", + day: 1, + calendar: "hebrew", +}); +console.log(md3.toLocaleString("en-US", { calendar: "hebrew" })); // 1 Adar I +const underlyingDate2 = Temporal.PlainDate.from(md3.toString()); +console.log(underlyingDate2.year, underlyingDate2.monthCode); // 5730 M05L + +// Day always out of range +const md4 = Temporal.PlainMonthDay.from({ month: 2, day: 30 }); +console.log(md4.toString()); // 02-29 + +// Day out of range for the specific year-month +const md5 = Temporal.PlainMonthDay.from({ year: 2021, month: 2, day: 29 }); +console.log(md5.toString()); // 02-28 +``` + +You can change this behavior to throw an error instead: + +```js +Temporal.PlainMonthDay.from( + { year: 2021, month: 13, day: 1 }, + { overflow: "reject" }, +); +// RangeError: date value "month" not in 1..12: 13 +``` ## Specifications @@ -49,4 +175,6 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal/PlainMonthDay/PlainMonthDay", "Temporal.PlainMonthDay()")}} +- {{jsxref("Temporal/PlainMonthDay/with", "Temporal.PlainMonthDay.prototype.with()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/index.md index 50e239a9bdcdacc..c81f1f716924e29 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/index.md @@ -7,33 +7,37 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay {{JSRef}} -The **`Temporal.PlainMonthDay`** object represents the month and day of a calendar date, without a year or time zone; for example, an event on a calendar that recurs every year and happens during the whole day. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The year is used to disambiguate the month-day in some calendar systems. +The **`Temporal.PlainMonthDay`** object represents the month and day of a calendar date, without a year or time zone; for example, an event on a calendar that recurs every year and happens during the whole day. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The year is used to disambiguate the month-day in non-ISO calendar systems. ## Description +A `PlainMonthDay` is essentially the month-day part of a {{jsxref("Temporal.PlainDate")}} object, without the year. Because the meaning of a month-day can change from year to year (for example, whether it exists, or what the month-day of the next day is), this object doesn't provide much functionality on its own, such as comparison, addition, or subtraction. It doesn't even have a {{jsxref("Temporal/PlainDate/month", "month")}} property, because the month index is not meaningful without a year (for example, two months from two years with the same index can have different names in the case of leap months). + ### ISO 8601 format `PlainMonthDay` objects can be serialized and parsed using the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) (with some extensions specified by ECMAScript). The string has the following form (spaces are only for readability and should not be present in the actual string): ```plain -MM-DD [u-ca=calendar_id] +YYYY-MM-DD [u-ca=calendar_id] ``` +- `YYYY` {{optional_inline}} + - : Either a four-digit number, or a six-digit number with a `+` or `-` sign. It is required for non-ISO calendars, and optional otherwise. If omitted, you can either replace `YYYY-` with `--` (so the string looks like `--MM-DD` or `--MMDD`), or omit the `YYYY-` part entirely (so the string looks like `MM-DD` or `MMDD`). Note that the reference year actually stored may be different from the one you provide, but the represented month-day is the same. See {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} for more information. - `MM` - - : A two-digit number from `01` to `12`. It may be prefixed by `--`, indicating that the year is unknown. + - : A two-digit number from `01` to `12`. - `DD` - - : A two-digit number from `01` to `31`. The `MM` and `DD` components can be separated by `-` or nothing. + - : A two-digit number from `01` to `31`. The `YYYY`, `MM`, and `DD` components can be separated by `-` or nothing. - `[u-ca=calendar_id]` {{optional_inline}} - - : Replace `calendar_id` with the calendar to use. May have a _critical flag_ by prefixing the key with `!`: e.g., `[!u-ca=iso8601]`. This flag generally tells other systems that it cannot be ignored if they don't support it. The `Temporal` parser will throw an error if the annotations contain two or more calendar annotations and one of them is critical. Defaults to `[u-ca=iso8601]`. Note that the `MM-DD` is always interpreted in ISO and then converted to the specified calendar. + - : Replace `calendar_id` with the calendar to use. May have a _critical flag_ by prefixing the key with `!`: e.g., `[!u-ca=iso8601]`. This flag generally tells other systems that it cannot be ignored if they don't support it. The `Temporal` parser will throw an error if the annotations contain two or more calendar annotations and one of them is critical. Defaults to `[u-ca=iso8601]`. Note that the `YYYY-MM-DD` is always interpreted in ISO and then converted to the specified calendar. -As an input, you may optionally include the year, time, offset, and time zone identifier, in the same format as [`PlainDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime#iso_8601_format), but they will be ignored. Other annotations in the `[key=value]` format are also ignored, and they must not have the critical flag. +As an input, you may optionally include the time, offset, and time zone identifier, in the same format as [`PlainDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime#iso_8601_format), but they will be ignored. Other annotations in the `[key=value]` format are also ignored, and they must not have the critical flag. When serializing, you can configure whether to display the calendar ID, and whether to add a critical flag for it. ## Constructor - {{jsxref("Temporal/PlainMonthDay/PlainMonthDay", "Temporal.PlainMonthDay()")}} - - : Creates a new `Temporal.PlainMonthDay` object. + - : Creates a new `Temporal.PlainMonthDay` object by directly supplying the underlying data. ## Static methods @@ -45,32 +49,53 @@ When serializing, you can configure whether to display the calendar ID, and whet These properties are defined on `Temporal.PlainMonthDay.prototype` and shared by all `Temporal.PlainMonthDay` instances. - {{jsxref("Temporal/PlainMonthDay/calendarId", "Temporal.PlainMonthDay.prototype.calendarId")}} - - : TODO + - : Returns a string representing the [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars) used to interpret the internal ISO 8601 date. - {{jsxref("Object/constructor", "Temporal.PlainMonthDay.prototype.constructor")}} - : The constructor function that created the instance object. For `Temporal.PlainMonthDay` instances, the initial value is the {{jsxref("Temporal/PlainMonthDay/PlainMonthDay", "Temporal.PlainMonthDay()")}} constructor. - {{jsxref("Temporal/PlainMonthDay/day", "Temporal.PlainMonthDay.prototype.day")}} - - : TODO + - : Returns a positive integer representing the 1-based day index in the month of this date, which is the same day number you would see on a calendar. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - {{jsxref("Temporal/PlainMonthDay/monthCode", "Temporal.PlainMonthDay.prototype.monthCode")}} - - : TODO + - : Returns a calendar-specific string representing the month of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. - `Temporal.PlainMonthDay.prototype[Symbol.toStringTag]` - : The initial value of the [`[Symbol.toStringTag]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property is the string `"Temporal.PlainMonthDay"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods - {{jsxref("Temporal/PlainMonthDay/equals", "Temporal.PlainMonthDay.prototype.equals()")}} - - : TODO + - : Returns `true` if this month-day is equivalent in value to another month-day (in a form convertible by {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}}), and `false` otherwise. They are compared both by their date values and their calendars. - {{jsxref("Temporal/PlainMonthDay/toJSON", "Temporal.PlainMonthDay.prototype.toJSON()")}} - - : TODO + - : Returns a string representing this month-day in the same [ISO 8601 format](#iso_8601_format) as calling {{jsxref("Temporal/PlainMonthDay/toString", "toString()")}}. - {{jsxref("Temporal/PlainMonthDay/toLocaleString", "Temporal.PlainMonthDay.prototype.toLocaleString()")}} - - : TODO + - : Returns a string with a language-sensitive representation of this month-day. - {{jsxref("Temporal/PlainMonthDay/toPlainDate", "Temporal.PlainMonthDay.prototype.toPlainDate()")}} - - : TODO + - : Returns a new {{jsxref("Temporal.PlainDate")}} object representing this month-day and a supplied year in the same calendar system. - {{jsxref("Temporal/PlainMonthDay/toString", "Temporal.PlainMonthDay.prototype.toString()")}} - - : TODO + - : Returns a string representing this month-day in the [ISO 8601 format](#iso_8601_format). - {{jsxref("Temporal/PlainMonthDay/valueOf", "Temporal.PlainMonthDay.prototype.valueOf()")}} - : Throws a {{jsxref("TypeError")}}, which prevents `Temporal.PlainMonthDay` instances from being [implicitly converted to primitives](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) when used in arithmetic or comparison operations. - {{jsxref("Temporal/PlainMonthDay/with", "Temporal.PlainMonthDay.prototype.with()")}} - - : TODO + - : Returns a new `Temporal.PlainMonthDay` object representing this month-day with some fields replaced by new values. + +## Examples + +### Getting the next occurrence of a festival + +```js +// Chinese New Years are on 1/1 in the Chinese calendar +const chineseNewYear = Temporal.PlainMonthDay.from({ + monthCode: "M01", + day: 1, + calendar: "chinese", +}); +const currentYear = Temporal.Now.plainDateISO().withCalendar("chinese").year; +let nextCNY = chineseNewYear.toPlainDate({ year: currentYear }); +if (Temporal.PlainDate.compare(nextCNY, Temporal.Now.plainDateISO()) <= 0) { + nextCNY = nextCNY.add({ years: 1 }); +} +console.log( + `The next Chinese New Year is on ${nextCNY.withCalendar("iso8601").toLocaleString()}`, +); +``` ## Specifications @@ -82,4 +107,5 @@ These properties are defined on `Temporal.PlainMonthDay.prototype` and shared by ## See also -- TODO +- {{jsxref("Temporal")}} +- {{jsxref("Temporal.PlainDate")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/monthcode/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/monthcode/index.md index a3ae06876da9c78..37b4bbb306dffed 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/monthcode/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/monthcode/index.md @@ -7,15 +7,54 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.monthCode {{JSRef}} -The **`monthCode`** accessor property of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`monthCode`** accessor property of {{jsxref("Temporal.PlainMonthDay")}} instances returns a calendar-specific string representing the month of this date. It is [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent. -## Description +Usually it is `M` plus a two-digit month number. For leap months, it is the previous month's code followed by `L` (even if it's conceptually a derivative of the following month; for example, in the Hebrew calendar, Adar I has code `M05L` but Adar II has code `M06`). If the leap month is the first month of the year, the code is `M00L`. -TODO +Because {{jsxref("Temporal/PlainDate/month", "month")}} is an index within a year, but `PlainMonthDay` doesn't have a year, there's no `month` property for `PlainMonthDay`. Therefore, `monthCode` is used to represent the month in a way that is independent of the year. + +The set accessor of `monthCode` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainMonthDay/with", "with()")}} method to create a new `Temporal.PlainMonthDay` object with the desired new value. + +For general information and more examples, see {{jsxref("Temporal/PlainDate/monthCode", "Temporal.PlainDate.prototype.monthCode")}}. ## Examples -TODO +### Using monthCode + +```js +const md = Temporal.PlainMonthDay.from("07-01"); // ISO 8601 calendar +console.log(md.monthCode); // "M07" + +const md2 = Temporal.PlainMonthDay.from("2021-05-01[u-ca=chinese]"); +console.log(md2.monthCode); // "M03" + +const md3 = Temporal.PlainMonthDay.from("2023-04-01[u-ca=chinese]"); +console.log(md3.monthCode); // "M02L" +``` + +### Changing monthCode + +```js +const md = Temporal.PlainMonthDay.from("07-01"); +const newMD = md.with({ monthCode: "M03" }); +console.log(newMD.toString()); // 03-01 +``` + +For other calendars, as long as there exists a year in which the month-day is valid, the month-day is considered valid, and the underlying reference year may therefore change. For example: + +```js +const md = Temporal.PlainMonthDay.from({ + monthCode: "M02", + day: 30, + calendar: "hebrew", +}); +console.log(md.toString()); // 1971-11-18[u-ca=hebrew] +console.log(md.toLocaleString("en-US", { calendar: "hebrew" })); // 30 Heshvan +// 30 Heshvan only exists in 1971, but this year is not a leap year +const newMD = md.with({ monthCode: "M05L" }); +console.log(newMD.toString()); // 1970-03-08[u-ca=hebrew] +console.log(newMD.toLocaleString("en-US", { calendar: "hebrew" })); // 30 Adar I +``` ## Specifications @@ -27,4 +66,6 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal/PlainMonthDay/with", "Temporal.PlainMonthDay.prototype.with()")}} +- {{jsxref("Temporal/PlainMonthDay/day", "Temporal.PlainMonthDay.prototype.day")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md index bc7de4e6da4a688..ce18831d24f617c 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/plainmonthday/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.PlainMonthDay The **`Temporal.PlainMonthDay()`** constructor creates {{jsxref("Temporal.PlainMonthDay")}} objects. -Like all other `Temporal` classes, you should usually construct `Temporal.PlainMonthDay` objects using the {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} static method, which can handle a variety of input types. +This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.PlainMonthDay` objects using the {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} static method, which can handle a variety of input types. ## Syntax @@ -24,29 +24,43 @@ new Temporal.PlainMonthDay(month, day, calendar, referenceYear) ### Parameters - `month` - - : TODO + - : A number, truncated to an integer, representing the month in the ISO calendar system. - `day` - - : TODO + - : A number, truncated to an integer, representing the day of the month in the ISO calendar system. - `calendar` {{optional_inline}} - - : TODO + - : A string representing the [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars) to use. Note that irrespective of the `calendar`, the `referenceYear`, `month`, and `day` must be in the ISO 8601 calendar system. Defaults to `"iso8601"`. - `referenceYear` {{optional_inline}} - - : TODO + - : A number, truncated to an integer, representing the year in the ISO calendar system. Defaults to `1972`. ### Return value -TODO +A new `Temporal.PlainMonthDay` object, representing the month-day of the date specified by `referenceYear`, `month`, `day` (in the ISO calendar), interpreted in the calendar system specified by `calendar`. + +The same ISO month-day can represent different dates in different years with non-ISO calendars. Therefore, you virtually always want to specify a `referenceYear` when using a non-ISO calendar. ### Exceptions -TODO +- {{jsxref("TypeError")}} + - : Thrown if `calendar` is not a string or `undefined`. +- {{jsxref("RangeError")}} + - : Thrown in one of the following cases: + - `month` or `day` is not a finite number, or do not represent a valid date in the ISO calendar system. + - `calendar` is not a valid calendar identifier. -## Description +## Examples -TODO +### Using Temporal.PlainMonthDay() -## Examples +```js +const md = new Temporal.PlainMonthDay(7, 1); +console.log(md.toString()); // 07-01 -TODO +const md2 = new Temporal.PlainMonthDay(7, 1, "chinese"); +console.log(md2.toString()); // 1972-07-01[u-ca=chinese] + +const md3 = new Temporal.PlainMonthDay(7, 1, "chinese", 2021); +console.log(md3.toString()); // 2021-07-01[u-ca=chinese] +``` ## Specifications @@ -58,4 +72,5 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tojson/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tojson/index.md index 019f1b0dc740e44..a206c03616c369d 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tojson/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tojson/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.toJSON {{JSRef}} -The **`toJSON()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`toJSON()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns a string representing this month-day in the same [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay#iso_8601_format) as calling {{jsxref("Temporal/PlainMonthDay/toString", "toString()")}}. ## Syntax @@ -21,19 +21,36 @@ None. ### Return value -TODO - -### Exceptions - -TODO +A string representing the given month-day in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay#iso_8601_format), with the year and calendar annotation included if it is not ISO 8601. ## Description -TODO +The `toJSON()` method is automatically called by {{jsxref("JSON.stringify()")}} when a `Temporal.PlainMonthDay` object is stringified. This method is generally intended to, by default, usefully serialize `Temporal.PlainMonthDay` objects during [JSON](/en-US/docs/Glossary/JSON) serialization, which can then be deserialized using the {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} function as the reviver of {{jsxref("JSON.parse()")}}. ## Examples -TODO +### Using toJSON() + +```js +const md = Temporal.PlainMonthDay.from({ month: 8, day: 1 }); +const mdStr = md.toJSON(); // '08-01' +const md2 = Temporal.PlainMonthDay.from(mdStr); +``` + +### JSON serialization and parsing + +This example shows how `Temporal.PlainMonthDay` can be serialized as JSON without extra effort, and how to parse it back. + +```js +const md = Temporal.PlainMonthDay.from({ month: 8, day: 1 }); +const mdStr = JSON.stringify({ birthday: md }); // '{"birthday":"08-01"}' +const obj = JSON.parse(jsonStr, (key, value) => { + if (key === "birthday") { + return Temporal.PlainMonthDay.from(value); + } + return value; +}); +``` ## Specifications @@ -45,4 +62,6 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal/PlainMonthDay/toString", "Temporal.PlainMonthDay.prototype.toString()")}} +- {{jsxref("Temporal/PlainMonthDay/toLocaleString", "Temporal.PlainMonthDay.prototype.toLocaleString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tolocalestring/index.md index 8cd14048495aba3..e18040796d16bfe 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tolocalestring/index.md @@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.toLocaleString {{JSRef}} -The **`toLocaleString()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`toLocaleString()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns a string with a language-sensitive representation of this month-day. In implementations with [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) support, this method simply calls `Intl.DateTimeFormat`. + +Every time `toLocaleString` is called, it has to perform a search in a big database of localization strings, which is potentially inefficient. When the method is called many times with the same arguments, it is better to create a {{jsxref("Intl.DateTimeFormat")}} object and use its {{jsxref("Intl/DateTimeFormat/format", "format()")}} method, because a `DateTimeFormat` object remembers the arguments passed to it and may decide to cache a slice of the database, so future `format` calls can search for localization strings within a more constrained context. ## Syntax @@ -19,26 +21,69 @@ toLocaleString(locales, options) ### Parameters +The `locales` and `options` parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used. + +In implementations that support the [`Intl.DateTimeFormat` API](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), these parameters correspond exactly to the [`Intl.DateTimeFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) constructor's parameters. Implementations without `Intl.DateTimeFormat` support return the exact same string as {{jsxref("Temporal/PlainMonthDay/toString", "toString()")}}, ignoring both parameters. + - `locales` {{optional_inline}} - - : TODO + - : A string with a BCP 47 language tag, or an array of such strings. Corresponds to the [`locales`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) parameter of the `Intl.DateTimeFormat()` constructor. - `options` {{optional_inline}} - - : TODO + + - : An object adjusting the output format. Corresponds to the [`options`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) parameter of the `Intl.DateTimeFormat()` constructor. The `calendar` option must be provided with the same value as this month-day's calendar. Regarding the [date-time component options](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#date-time_component_options) and the style shortcuts (`dateStyle` and `timeStyle`), the options should follow one of these forms: + + - Provide none of them: `year` and `month` will default to `"numeric"`. + - Provide `dateStyle` only. + - Provide some date-time component options, where at least one of them is `year` or `month`. Only the specified date components will be included in the output. + +See the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) for details on these parameters and how to use them. ### Return value -TODO +A string representing the given month-day according to language-specific conventions. -### Exceptions +In implementations with `Intl.DateTimeFormat`, this is equivalent to `new Intl.DateTimeFormat(locales, options).format(monthDay)`, where `options` has been normalized as described above. -TODO +> [!NOTE] +> Most of the time, the formatting returned by `toLocaleString()` is consistent. However, the output may vary between implementations, even within the same locale — output variations are by design and allowed by the specification. It may also not be what you expect. For example, the string may use non-breaking spaces or be surrounded by bidirectional control characters. You should not compare the results of `toLocaleString()` to hardcoded constants. -## Description +### Exceptions -TODO +- {{jsxref("RangeError")}} + - : Thrown if any of the options is invalid. +- {{jsxref("TypeError")}} + - : Thrown if any of the options is not of the expected type. ## Examples -TODO +### Using toLocaleString() + +Basic use of this method without specifying a `locale` returns a formatted string in the default locale and with default options. + +```js +// Note that just specifying "08-01" defaults to the ISO 8601 calendar, +// which throws an error if the locale's default calendar is not ISO 8601. +const md = Temporal.PlainMonthDay.from("2021-08-01[u-ca=gregory]"); + +console.log(md.toLocaleString()); // 8/1 (assuming en-US locale and Gregorian calendar) +``` + +If the month-day's calendar doesn't match the locale's default calendar, even when its calendar is `iso8601`, an explicit `calendar` option must be provided with the same value. + +```js +const md = Temporal.PlainMonthDay.from("08-01"); +md.toLocaleString("en-US", { calendar: "iso8601" }); // 08-01 +``` + +### Using toLocaleString() with options + +You can customize which parts of the month-day are included in the output by providing the `options` parameter. + +```js +const md = Temporal.PlainMonthDay.from("2021-08-01[u-ca=gregory]"); +md.toLocaleString("en-US", { dateStyle: "full" }); // August 1 +md.toLocaleString("en-US", { month: "long" }); // August +md.toLocaleString("en-US", { day: "numeric" }); // 1 +``` ## Specifications @@ -50,4 +95,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Intl.DateTimeFormat")}} +- {{jsxref("Temporal/PlainMonthDay/toJSON", "Temporal.PlainMonthDay.prototype.toJSON()")}} +- {{jsxref("Temporal/PlainMonthDay/toString", "Temporal.PlainMonthDay.prototype.toString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/toplaindate/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/toplaindate/index.md index cb0804bd431b0a4..7279d4d6a7b0c7b 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/toplaindate/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/toplaindate/index.md @@ -7,34 +7,40 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.toPlainDate {{JSRef}} -The **`toPlainDate()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`toPlainDate()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns a new {{jsxref("Temporal.PlainDate")}} object representing this month-day and a supplied year in the same calendar system. ## Syntax ```js-nolint -toPlainDate(info) +toPlainDate(yearInfo) ``` ### Parameters -- `info` - - : TODO +- `yearInfo` {{optional_inline}} + - : An object representing the year component of the resulting `PlainDate`, containing the following properties (in the order they are retrieved and validated): + - `era` and `eraYear` + - : A string and an integer that correspond to the {{jsxref("Temporal/PlainDate/era", "era")}} and {{jsxref("Temporal/PlainDate/eraYear", "eraYear")}} properties. Are only used if the calendar system has eras. `era` and `eraYear` must be provided simultaneously. If they are not provided, then `year` must be provided. If all of `era`, `eraYear`, and `year` are provided, they must be consistent. + - `year` + - : Corresponds to the {{jsxref("Temporal/PlainDate/year", "year")}} property. ### Return value -TODO +A new `Temporal.PlainDate` object representing the date specified by this month-day and the year in `yearInfo`, interpreted in the calendar system of this date. -### Exceptions - -TODO +## Examples -## Description +### Using toPlainDate() -TODO +```js +const md = Temporal.PlainMonthDay.from("07-01"); +const date = md.toPlainDate({ year: 2021 }); +console.log(date.toString()); // 2021-07-01 -## Examples - -TODO +const md2 = Temporal.PlainMonthDay.from("2021-07-01[u-ca=japanese]"); +const date2 = md2.toPlainDate({ era: "reiwa", eraYear: 1 }); +console.log(date2.toString()); // 2019-07-01[u-ca=japanese] +``` ## Specifications @@ -46,4 +52,6 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal.PlainDate")}} +- {{jsxref("Temporal/PlainDate/toPlainMonthDay", "Temporal.PlainDate.prototype.toPlainMonthDay()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tostring/index.md index 70fd881163a20be..1241779ec4086f1 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/tostring/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.toString {{JSRef}} -The **`toString()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`toString()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns a string representing this month-day in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay#iso_8601_format). ## Syntax @@ -19,23 +19,63 @@ toString(options) ### Parameters - `options` {{optional_inline}} - - : TODO + - : An object containing the following property: + - `calendarName` {{optional_inline}} + - : Whether to show the calendar annotation (`[u-ca=calendar_id]`) in the return value. Possible values are: + - `"auto"` (default) + - : Include the calendar annotation if the calendar is not `"iso8601"`. The reference year is included if the calendar is not `"iso8601"`. + - `"always"` + - : Always include the calendar annotation. The reference year is always included too. + - `"never"` + - : Never include the calendar annotation. This makes the returned string not recoverable to the same {{jsxref("Temporal.PlainMonthDay")}} instance, although the month-day value still remains the same. The reference year is included if the calendar is not `"iso8601"`. + - `"critical"` + - : Always include the calendar annotation, and add a critical flag: `[!u-ca=calendar_id]`. Useful when sending the string to certain systems, but not useful for Temporal itself. The reference year is always included too. ### Return value -TODO +A string in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay#iso_8601_format) representing this month-day. The calendar annotation is included as specified. The reference year is included if a calendar annotation is included or if the calendar is not `"iso8601"`. ### Exceptions -TODO +- {{jsxref("RangeError")}} + - : Thrown if any of the options is invalid. +- {{jsxref("TypeError")}} + - : Thrown if `options` is not an object or `undefined`. -## Description +## Examples -TODO +### Using toString() -## Examples +```js +const md = Temporal.PlainMonthDay.from({ month: 8, day: 1 }); +console.log(md.toString()); // '08-01' -TODO +const md2 = Temporal.PlainMonthDay.from({ + monthCode: "M08", + day: 1, + calendar: "chinese", +}); +console.log(md2.toString()); // '1972-09-08[u-ca=chinese]' +``` + +### Using options + +```js +const isoMD = Temporal.PlainMonthDay.from({ month: 8, day: 1 }); +const md = Temporal.PlainMonthDay.from({ + monthCode: "M08", + day: 1, + calendar: "chinese", +}); +console.log(isoMD.toString({ calendarName: "auto" })); // '08-01' +console.log(md.toString({ calendarName: "auto" })); // '1972-09-08[u-ca=chinese]' +console.log(isoMD.toString({ calendarName: "always" })); // '1972-08-01[u-ca=iso8601]' +console.log(md.toString({ calendarName: "always" })); // '1972-09-08[u-ca=chinese]' +console.log(isoMD.toString({ calendarName: "never" })); // '08-01' +console.log(md.toString({ calendarName: "never" })); // '1972-09-08' +console.log(isoMD.toString({ calendarName: "critical" })); // '1972-08-01[!u-ca=iso8601]' +console.log(md.toString({ calendarName: "critical" })); // '1972-09-08[!u-ca=chinese]' +``` ## Specifications @@ -47,4 +87,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} +- {{jsxref("Temporal/PlainMonthDay/toJSON", "Temporal.PlainMonthDay.prototype.toJSON()")}} +- {{jsxref("Temporal/PlainMonthDay/toLocaleString", "Temporal.PlainMonthDay.prototype.toLocaleString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/with/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/with/index.md index cb27c15bd0b9a4c..5ecf44ee17465c3 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/with/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/with/index.md @@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainMonthDay.with {{JSRef}} -The **`with()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances TODO +The **`with()`** method of {{jsxref("Temporal.PlainMonthDay")}} instances returns a new `Temporal.PlainMonthDay` object representing this month-day with some fields replaced by new values. Because all `Temporal` objects are designed to be immutable, this method essentially functions as the setter for the month-day's fields. + +There's no obvious way to create a new `Temporal.PlainMonthDay` object with a different calendar that represents the same month-day, so to replace its `calendarId` property, you need to convert it to a {{jsxref("Temporal.PlainDate")}} object first using {{jsxref("Temporal/PlainMonthDay/toPlainDate", "toPlainDate()")}}, change the calendar, and then convert it back. ## Syntax @@ -19,25 +21,55 @@ with(info, options) ### Parameters - `info` - - : TODO + - : An object containing the following properties (in the order they are retrieved and validated): + - `calendar` {{optional_inline}} + - : A string that corresponds to the {{jsxref("Temporal/PlainMonthDay/calendarId", "calendarId")}} property. Defaults to `"iso8601"`. All other properties are interpreted in this calendar system (unlike the {{jsxref("Temporal/PlainMonthDay/PlainMonthDay", "Temporal.PlainMonthDay()")}} constructor, which interprets the values in the ISO calendar system). + - `day` + - : An integer that corresponds to the {{jsxref("Temporal/PlainMonthDay/day", "day")}} property. Must be positive regardless of the `overflow` option. + - `era` and `eraYear` {{optional_inline}} + - : A string and an integer that can be used instead of `year`. See {{jsxref("Temporal/PlainDate/era", "era")}} and {{jsxref("Temporal/PlainDate/eraYear", "eraYear")}} of `PlainDate`. Are only used if the calendar system has eras. `era` and `eraYear` must be provided simultaneously. If all of `era`, `eraYear`, and `year` are provided, they must be consistent. + - `month` {{optional_inline}} + - : A positive integer that can be used instead of `monthCode`. See {{jsxref("Temporal/PlainDate/month", "month")}} of `PlainDate`. Must be positive regardless of the `overflow` option. If `month` is provided, and the calendar is not `iso8601`, then `year` (or `era` + `eraYear` as a substitution) must be provided too, because the same `month` may map to multiple possible `monthCode` values in different years. + - `monthCode` + - : Corresponds to the {{jsxref("Temporal/PlainMonthDay/monthCode", "monthCode")}} property. If both `month` and `monthCode` are provided, they must be consistent. + - `year` {{optional_inline}} + - : An integer used to disambiguate `month` if provided, because for some calendars, the same `month` can mean different `monthCode` in different years. See {{jsxref("Temporal/PlainDate/year", "year")}} of `PlainDate`. If a year is provided, then the `overflow` option validates the month-day in the given year, not just any year. - `options` {{optional_inline}} - - : TODO + - : An object containing the following property: + - `overflow` {{optional_inline}} + - : A string specifying the behavior when a date component is out of range. Possible values are: + - `"constrain"` (default) + - : The date component is [clamped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate#invalid_date_clamping) to the valid range. + - `"reject"` + - : A {{jsxref("RangeError")}} is thrown if the date component is out of range. ### Return value -TODO +A new `Temporal.PlainMonthDay` object, where the fields specified in `info` that are not `undefined` are replaced by the corresponding values, and the rest of the fields are copied from the original date. ### Exceptions -TODO +- {{jsxref("TypeError")}} + - : Thrown in one of the following cases: + - `info` is not an object. + - `options` is not an object or `undefined`. +- {{jsxref("RangeError")}} + - : Thrown in one of the following cases: + - The provided properties that specify the same component are inconsistent. + - The provided non-numerical properties are not valid, for example, `monthCode` is not a valid month code. + - The provided numerical properties are out of range, and `options.overflow` is set to `"reject"`. -## Description +## Examples -TODO +### Using with() -## Examples +```js +const md = Temporal.PlainMonthDay.from("07-01"); +const newMd = md.with({ day: 2 }); +console.log(newMd.toString()); // "07-02" +``` -TODO +For more examples, see the documentation for the individual properties that can be set using `with()`. ## Specifications @@ -49,4 +81,5 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainMonthDay")}} +- {{jsxref("Temporal/PlainMonthDay/from", "Temporal.PlainMonthDay.from()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/index.md index 8e5b3c1f55461db..3d03e3766450646 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/index.md @@ -31,7 +31,7 @@ When serializing, you can configure the fractional second digits. ## Constructor - {{jsxref("Temporal/PlainTime/PlainTime", "Temporal.PlainTime()")}} - - : Creates a new `Temporal.PlainTime` object. + - : Creates a new `Temporal.PlainTime` object by directly supplying the underlying data. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md index 005f568af836a62..f753fc70e858707 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/plaintime/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.PlainTime The **`Temporal.PlainTime()`** constructor creates {{jsxref("Temporal.PlainTime")}} objects. -Like all other `Temporal` classes, you should usually construct `Temporal.PlainTime` objects using the {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} static method, which can handle a variety of input types. +This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.PlainTime` objects using the {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} static method, which can handle a variety of input types. ## Syntax diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md index 231ce8568e29c27..24c7bdc08cf3827 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/index.md @@ -33,7 +33,7 @@ When serializing, you can configure whether to display the calendar ID, and whet ## Constructor - {{jsxref("Temporal/PlainYearMonth/PlainYearMonth", "Temporal.PlainYearMonth()")}} - - : Creates a new `Temporal.PlainYearMonth` object. + - : Creates a new `Temporal.PlainYearMonth` object by directly supplying the underlying data. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md index f9a41154b273b74..7f007e3c1ddec00 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/plainyearmonth/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.PlainYearMonth.PlainYearMonth The **`Temporal.PlainYearMonth()`** constructor creates {{jsxref("Temporal.PlainYearMonth")}} objects. -Like all other `Temporal` classes, you should usually construct `Temporal.PlainYearMonth` objects using the {{jsxref("Temporal/PlainYearMonth/from", "Temporal.PlainYearMonth.from()")}} static method, which can handle a variety of input types. +This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.PlainYearMonth` objects using the {{jsxref("Temporal/PlainYearMonth/from", "Temporal.PlainYearMonth.from()")}} static method, which can handle a variety of input types. ## Syntax diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md index 085d8430a849d65..8b62548a7ae775f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/index.md @@ -139,7 +139,7 @@ When constructing a `ZonedDateTime` from an ISO 8601 string or when updating it ## Constructor - {{jsxref("Temporal/ZonedDateTime/ZonedDateTime", "Temporal.ZonedDateTime()")}} - - : Creates a new `Temporal.ZonedDateTime` object. + - : Creates a new `Temporal.ZonedDateTime` object by directly supplying the underlying data. ## Static methods diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md index 7d125c7331ef29c..238008118fb87e0 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/zoneddatetime/index.md @@ -9,7 +9,7 @@ browser-compat: javascript.builtins.Temporal.ZonedDateTime.ZonedDateTime The **`Temporal.ZonedDateTime()`** constructor creates {{jsxref("Temporal.ZonedDateTime")}} objects. -Like all other `Temporal` classes, you should usually construct `Temporal.ZonedDateTime` objects using the {{jsxref("Temporal/ZonedDateTime/from", "Temporal.ZonedDateTime.from()")}} static method, which can handle a variety of input types. +This constructor allows you to create instances by directly supplying the underlying data. Like all other `Temporal` classes, you should usually construct `Temporal.ZonedDateTime` objects using the {{jsxref("Temporal/ZonedDateTime/from", "Temporal.ZonedDateTime.from()")}} static method, which can handle a variety of input types. ## Syntax