From f4342cf705f57525fe95c1d00ffc54b719e6cbe0 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Tue, 31 Dec 2024 02:31:39 -0500 Subject: [PATCH] PlainTime docs --- .../temporal/instant/equals/index.md | 2 +- .../global_objects/temporal/instant/index.md | 2 +- .../temporal/plaindate/subtract/index.md | 2 +- .../temporal/plaindatetime/hour/index.md | 19 +++- .../temporal/plaindatetime/index.md | 12 +- .../plaindatetime/microsecond/index.md | 22 +++- .../plaindatetime/millisecond/index.md | 22 +++- .../temporal/plaindatetime/minute/index.md | 19 +++- .../plaindatetime/nanosecond/index.md | 22 +++- .../temporal/plaindatetime/second/index.md | 22 +++- .../temporal/plaintime/add/index.md | 39 +++++-- .../temporal/plaintime/compare/index.md | 34 ++++-- .../temporal/plaintime/equals/index.md | 26 +++-- .../temporal/plaintime/from/index.md | 107 ++++++++++++++++-- .../temporal/plaintime/hour/index.md | 34 +++++- .../temporal/plaintime/index.md | 40 ++++--- .../temporal/plaintime/microsecond/index.md | 40 ++++++- .../temporal/plaintime/millisecond/index.md | 40 ++++++- .../temporal/plaintime/minute/index.md | 34 +++++- .../temporal/plaintime/nanosecond/index.md | 40 ++++++- .../temporal/plaintime/plaintime/index.md | 31 ++--- .../temporal/plaintime/round/index.md | 38 +++++-- .../temporal/plaintime/second/index.md | 37 +++++- .../temporal/plaintime/since/index.md | 65 +++++++++-- .../temporal/plaintime/subtract/index.md | 30 +++-- .../temporal/plaintime/tojson/index.md | 38 +++++-- .../plaintime/tolocalestring/index.md | 58 ++++++++-- .../temporal/plaintime/tostring/index.md | 47 ++++++-- .../temporal/plaintime/until/index.md | 33 ++++-- .../temporal/plaintime/with/index.md | 49 ++++++-- .../plainyearmonth/daysinmonth/index.md | 1 - .../plainyearmonth/daysinyear/index.md | 1 - .../temporal/plainyearmonth/subtract/index.md | 2 +- .../temporal/plainyearmonth/year/index.md | 1 - 34 files changed, 779 insertions(+), 230 deletions(-) diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/instant/equals/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/instant/equals/index.md index 5f6befce80359bd..3b05fc2bc8374b2 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/instant/equals/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/instant/equals/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.Instant.equals {{JSRef}} -The **`equals()`** method of {{jsxref("Temporal.Instant")}} instances returns `true` if this instant is equal to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. Equivalent to `Temporal.Instant.compare(this, other) === 0`. +The **`equals()`** method of {{jsxref("Temporal.Instant")}} instances returns `true` if this instant is equivalent in value to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. They are compared by their epoch nanoseconds. Equivalent to `Temporal.Instant.compare(this, other) === 0`. ## Syntax 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 a67d018fb12d2d4..cd564e6fe433ebc 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 @@ -78,7 +78,7 @@ These properties are defined on `Temporal.Instant.prototype` and shared by all ` - {{jsxref("Temporal/Instant/add", "Temporal.Instant.prototype.add()")}} - : Returns a new `Temporal.Instant` object representing this instant moved forward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}). - {{jsxref("Temporal/Instant/equals", "Temporal.Instant.prototype.equals()")}} - - : Returns `true` if this instant is equal to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. Equivalent to `Temporal.Instant.compare(this, other) === 0`. + - : Returns `true` if this instant is equivalent in value to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. They are compared by their epoch nanoseconds. Equivalent to `Temporal.Instant.compare(this, other) === 0`. - {{jsxref("Temporal/Instant/round", "Temporal.Instant.prototype.round()")}} - : Returns a new `Temporal.Instant` object representing this instant rounded to the given unit. - {{jsxref("Temporal/Instant/since", "Temporal.Instant.prototype.since()")}} 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 e02992045553793..5e1b7703f9455e6 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 @@ -33,7 +33,7 @@ subtract(duration, options) ### Return value -A new `Temporal.PlainDate` object representing the date specified by the original date, minus the duration. +A new `Temporal.PlainDate` object representing the date specified by the original `PlainDate`, minus the duration. ## Description diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/hour/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/hour/index.md index 34b5a6445daf561..c18c41dd0beedbc 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/hour/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/hour/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.hour {{JSRef}} -The **`hour`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`hour`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 23 representing the hour component of this time. -## Description +The set accessor of `hour` 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/PlainTime/hour", "Temporal.PlainTime.prototype.hour")}}. ## Examples -TODO +### Using hour + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789"); +console.log(dt.hour); // 12 +``` ## Specifications @@ -27,4 +32,8 @@ 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/PlainTime/hour", "Temporal.PlainTime.prototype.hour")}} 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 92239c936cfb7e7..65ac5bd19548d9b 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 @@ -79,15 +79,15 @@ These properties are defined on `Temporal.PlainDateTime.prototype` and shared by - {{jsxref("Temporal/PlainDateTime/eraYear", "Temporal.PlainDateTime.prototype.eraYear")}} - : 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 + - : Returns a integer from 0 to 23 representing the hour component of this time. - {{jsxref("Temporal/PlainDateTime/inLeapYear", "Temporal.PlainDateTime.prototype.inLeapYear")}} - : 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 + - : Returns a integer from 0 to 999 representing the microsecond (10-6 second) component of this time. - {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}} - - : TODO + - : Returns a integer from 0 to 999 representing the millisecond (10-3 second) component of this time. - {{jsxref("Temporal/PlainDateTime/minute", "Temporal.PlainDateTime.prototype.minute")}} - - : TODO + - : Returns a integer from 0 to 59 representing the minute component of this time. - {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}} - : 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")}} @@ -95,9 +95,9 @@ These properties are defined on `Temporal.PlainDateTime.prototype` and shared by - {{jsxref("Temporal/PlainDateTime/monthsInYear", "Temporal.PlainDateTime.prototype.monthsInYear")}} - : 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 + - : Returns a integer from 0 to 999 representing the nanosecond (10-9 second) component of this time. - {{jsxref("Temporal/PlainDateTime/second", "Temporal.PlainDateTime.prototype.second")}} - - : TODO + - : Returns a integer from 0 to 59 representing the second component of this time. - {{jsxref("Temporal/PlainDateTime/weekOfYear", "Temporal.PlainDateTime.prototype.weekOfYear")}} - : 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")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/microsecond/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/microsecond/index.md index 1ab3c9477b0a7d6..efe9fc104cf0cf7 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/microsecond/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/microsecond/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.microsecond {{JSRef}} -The **`microsecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`microsecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 999 representing the microsecond (10-6 second) component of this time. -## Description +The set accessor of `microsecond` 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/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}}. ## Examples -TODO +### Using microsecond + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789"); +console.log(dt.microsecond); // 456 +``` ## Specifications @@ -27,4 +32,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/second", "Temporal.PlainDateTime.prototype.second")}} +- {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}} +- {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}} +- {{jsxref("Temporal/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/millisecond/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/millisecond/index.md index 9783567575b1783..48d8166b4757eff 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/millisecond/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/millisecond/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.millisecond {{JSRef}} -The **`millisecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`millisecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 999 representing the millisecond (10-3 second) component of this time. -## Description +The set accessor of `millisecond` 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/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}}. ## Examples -TODO +### Using millisecond + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789"); +console.log(dt.millisecond); // 123 +``` ## Specifications @@ -27,4 +32,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/second", "Temporal.PlainDateTime.prototype.second")}} +- {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}} +- {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}} +- {{jsxref("Temporal/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/minute/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/minute/index.md index 5d2337066a8913d..dcef6df794c3ce9 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/minute/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/minute/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.minute {{JSRef}} -The **`minute`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`minute`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 59 representing the minute component of this time. -## Description +The set accessor of `minute` 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/PlainTime/minute", "Temporal.PlainTime.prototype.minute")}}. ## Examples -TODO +### Using minute + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789"); +console.log(dt.minute); // 34 +``` ## Specifications @@ -27,4 +32,8 @@ 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/PlainTime/minute", "Temporal.PlainDateTime.prototype.minute")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/nanosecond/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/nanosecond/index.md index 9e6d532e67727db..7286cd76aa6236f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/nanosecond/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/nanosecond/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.nanosecond {{JSRef}} -The **`nanosecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`nanosecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 999 representing the nanosecond (10-9 second) component of this time. -## Description +The set accessor of `nanosecond` 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/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}}. ## Examples -TODO +### Using nanosecond + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789"); +console.log(dt.nanosecond); // 789 +``` ## Specifications @@ -27,4 +32,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/second", "Temporal.PlainDateTime.prototype.second")}} +- {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}} +- {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}} +- {{jsxref("Temporal/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/second/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/second/index.md index 4f6256a5e4ddba7..9690f2b0522368f 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/second/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/second/index.md @@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.second {{JSRef}} -The **`second`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO +The **`second`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 59 representing the second component of this time. -## Description +The set accessor of `second` 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/PlainTime/second", "Temporal.PlainTime.prototype.second")}}. ## Examples -TODO +### Using second + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789"); +console.log(dt.second); // 56 +``` ## Specifications @@ -27,4 +32,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/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}} +- {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}} +- {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}} +- {{jsxref("Temporal/PlainTime/second", "Temporal.PlainTime.prototype.second")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/add/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/add/index.md index b56937f78ecea97..c44b46b5a6cbf26 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/add/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/add/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.add {{JSRef}} -The **`add()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`add()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a new `Temporal.PlainTime` object representing this time moved forward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}), wrapping around the clock if necessary. ## Syntax @@ -18,23 +18,40 @@ add(duration) ### Parameters - `duration` - - : TODO + - : A string, an object, or a {{jsxref("Temporal.Duration")}} instance representing a duration to add to this time. It is converted to a `Temporal.Duration` object using the same algorithm as {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}. ### Return value -TODO +A new `Temporal.PlainTime` object representing the time specified by the original `PlainTime`, plus the duration. Any units above `hours` are ignored, and if the time goes past midnight, it wraps around to the next day. -### Exceptions +Adding a duration is equivalent to [subtracting](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/subtract) its [negation](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/negated). -TODO +## Examples -## Description +### Adding a duration -TODO +```js +const start = Temporal.PlainTime.from("12:34:56"); +const end = start.add({ hours: 1, minutes: 30 }); +console.log(end.toString()); // 14:04:56 -## Examples +const end2 = start.add({ hours: -1, minutes: -30 }); +console.log(end2.toString()); // 11:04:56 + +const distance = Temporal.PlainTime.from("00:00:00").until("01:23:45"); // 1h 23m 45s +const end3 = start.add(distance); +console.log(end3.toString()); // 13:58:41 +``` -TODO +### Time wrapping + +If the time goes past midnight, it wraps around to the next day: + +```js +const start = Temporal.PlainTime.from("12:34:56"); +const end = start.add({ hours: 12 }); +console.log(end.toString()); // 00:34:56 +``` ## Specifications @@ -46,4 +63,6 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal.Duration")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/compare/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/compare/index.md index 753c07eb3eb8c62..72cdb630334d9a5 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/compare/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/compare/index.md @@ -18,25 +18,38 @@ Temporal.PlainTime.compare(time1, time2) ### Parameters - `time1` - - : TODO + - : A string, an object, or a {{jsxref("Temporal.PlainTime")}} instance representing the first time to compare. It is converted to a `Temporal.PlainTime` object using the same algorithm as {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}. - `time2` - - : TODO + - : Same as `time1`. ### Return value -TODO +Returns `-1` if `time1` comes before `time2`, `0` if they are the same, and `1` if `time2` comes after. -### Exceptions +## Examples -TODO +### Using Temporal.PlainTime.compare() -## Description +```js +const time1 = Temporal.PlainTime.from("12:34:56"); +const time2 = Temporal.PlainTime.from("12:34:57"); +console.log(Temporal.PlainTime.compare(time1, time2)); // -1 -TODO +const time3 = Temporal.PlainTime.from("11:34:56"); +console.log(Temporal.PlainTime.compare(time1, time3)); // 1 +``` -## Examples +### Sorting an array of times -TODO +The purpose of this `compare()` function is to act as a comparator to be passed to {{jsxref("Array.prototype.sort()")}} and related functions. + +```js +const times = ["12:34:56", "11:34:56", "12:34:57"]; + +times.sort(Temporal.PlainTime.compare); +console.log(times); +// [ "11:34:56", "12:34:56", "12:34:57" ] +``` ## Specifications @@ -48,4 +61,5 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/equals", "Temporal.PlainTime.prototype.equals()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/equals/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/equals/index.md index 373822cdaa96bfa..e5adefbf8f1abb3 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/equals/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/equals/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.equals {{JSRef}} -The **`equals()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`equals()`** method of {{jsxref("Temporal.PlainTime")}} instances returns `true` if this time is equivalent in value to another time (in a form convertible by {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}), and `false` otherwise. They are compared by their time values. Equivalent to `Temporal.PlainTime.compare(this, other) === 0`. ## Syntax @@ -18,23 +18,24 @@ equals(other) ### Parameters - `other` - - : TODO + - : A string, an object, or a {{jsxref("Temporal.PlainTime")}} instance representing the other time to compare. It is converted to a `Temporal.PlainTime` object using the same algorithm as {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}. ### Return value -TODO +`true` if this time is equal to `other` both in their time value and their calendar, `false` otherwise. -### Exceptions - -TODO +## Examples -## Description +### Using equals() -TODO +```js +const time1 = Temporal.PlainTime.from("12:34:56"); +const time2 = Temporal.PlainTime.from({ hour: 12, minute: 34, second: 56 }); +console.log(time1.equals(time2)); // true -## Examples - -TODO +const time3 = Temporal.PlainTime.from("00:34:56"); +console.log(time1.equals(time3)); // false +``` ## Specifications @@ -46,4 +47,5 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/compare", "Temporal.PlainTime.compare()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/from/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/from/index.md index 83304845552daf6..1df736d411122f1 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/from/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/from/index.md @@ -19,25 +19,112 @@ Temporal.PlainTime.from(info, options) ### Parameters - `info` - - : TODO + + - : One of the following: + + - A {{jsxref("Temporal.PlainTime")}} instance, which creates a copy of the instance. + - A {{jsxref("Temporal.PlainDateTime")}} instance, which provides the time in the same fashion as {{jsxref("Temporal/PlainDateTime/toPlainDate", "Temporal.PlainDateTime.prototype.toPlainTime()")}}. + - A {{jsxref("Temporal.ZonedDateTime")}} instance, which provides the time in the same fashion as {{jsxref("Temporal/ZonedDateTime/toPlainDate", "Temporal.ZonedDateTime.prototype.toPlainTime()")}}. + - An object containing at least one of the following properties (in the order they are retrieved and validated): + + - {{jsxref("Temporal/PlainTime/hour", "hour")}} + - {{jsxref("Temporal/PlainTime/microsecond", "microsecond")}} + - {{jsxref("Temporal/PlainTime/millisecond", "millisecond")}} + - {{jsxref("Temporal/PlainTime/minute", "minute")}} + - {{jsxref("Temporal/PlainTime/nanosecond", "nanosecond")}} + - {{jsxref("Temporal/PlainTime/second", "second")}} + + They are truncated to be integers. Out-of-range values are handled by the `overflow` option. + + - An [ISO 8601](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime#iso_8601_format) string containing a time. + - `options` {{optional_inline}} - - : TODO + - : An object containing the following property: + - `overflow` {{optional_inline}} + - : A string specifying the behavior when a time component is out of range. Possible values are: + - `"constrain"` (default) + - : The time component is clamped to the valid range. + - `"reject"` + - : A {{jsxref("RangeError")}} is thrown if the time component is out of range. ### Return value -TODO +A new `Temporal.PlainTime` object, representing the time specified by `info`. ### Exceptions -TODO +- {{jsxref("TypeError")}} + - : Thrown in one of the following cases: + - `info` is not an object with at least one recognized property or a string. + - `options` is not an object or `undefined`. +- {{jsxref("RangeError")}} + - : Thrown if the provided numerical properties are out of range, and `options.overflow` is set to `"reject"`. -## Description +## Examples -TODO +### Creating a PlainTime from an object -## Examples +```js +const t1 = Temporal.PlainTime.from({ hour: 0 }); +console.log(t1.toString()); // "00:00:00" + +const t2 = Temporal.PlainTime.from({ hour: 12, minute: 34, second: 56 }); +console.log(t2.toString()); // "12:34:56" + +const t3 = Temporal.PlainTime.from({ + hour: 12, + minute: 34, + second: 56, + millisecond: 123, + microsecond: 456, + nanosecond: 789, +}); +console.log(t3.toString()); // "12:34:56.123456789" +``` + +### Controlling overflow behavior + +By default, out-of-range values are clamped to the valid range: -TODO +```js +const t1 = Temporal.PlainTime.from({ hour: 25 }); +console.log(t1.toString()); // "23:00:00" + +const t2 = Temporal.PlainTime.from({ hour: 25, minute: 60 }); +console.log(t2.toString()); // "23:59:00" +``` + +You can change this behavior to throw an error instead: + +```js +Temporal.PlainTime.from({ hour: 25 }, { overflow: "reject" }); +// RangeError: time value "hour" not in 0..23: 25 +``` + +### Creating a PlainTime from a string + +```js +const t1 = Temporal.PlainTime.from("12:34:56.123456789"); +console.log(t1.toLocaleString("en-US", { timeStyle: "full" })); +// 12:34:56 PM +``` + +### Creating a PlainTime from another Temporal instance + +```js +const dt = Temporal.PlainDateTime.from("2021-07-01T12:00"); +const t = Temporal.PlainTime.from(dt); +console.log(t.toString()); // "12:00:00" + +const zdt = Temporal.ZonedDateTime.from( + "2021-07-01T00:00+08:00[Asia/Shanghai]", +); +const t2 = Temporal.PlainTime.from(zdt); +console.log(t2.toString()); // "00:00:00" + +const t3 = Temporal.PlainTime.from(t); +console.log(t3.toString()); // "12:00:00" +``` ## Specifications @@ -49,4 +136,6 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/PlainTime", "Temporal.PlainTime()")}} +- {{jsxref("Temporal/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/hour/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/hour/index.md index 4c9a3fbd076bb25..273d9b00586411c 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/hour/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/hour/index.md @@ -7,15 +7,34 @@ browser-compat: javascript.builtins.Temporal.PlainTime.hour {{JSRef}} -The **`hour`** accessor property of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`hour`** accessor property of {{jsxref("Temporal.PlainTime")}} instances returns a integer from 0 to 23 representing the hour component of this time. -## Description - -TODO +The set accessor of `hour` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainTime/with", "with()")}} method to create a new `Temporal.PlainTime` object with the desired new value. ## Examples -TODO +### Using hour + +```js +const time = Temporal.PlainTime.from("12:34:56"); +console.log(time.hour); // 12 +``` + +### Changing hour + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.with({ hour: 15 }); +console.log(newTime.toString()); // 15:34:56 +``` + +You can also use {{jsxref("Temporal/PlainTime/add", "add()")}} or {{jsxref("Temporal/PlainTime/subtract", "subtract()")}} to move a certain number of hours from the current time. + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.add({ hours: 3 }); +console.log(newTime.toString()); // 15:34:56 +``` ## Specifications @@ -27,4 +46,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} 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 3d03e3766450646..7a7a527632816dd 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 @@ -9,6 +9,10 @@ browser-compat: javascript.builtins.Temporal.PlainTime The **`Temporal.PlainTime`** object 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. +## Description + +A `PlainTime` is essentially the time part of a {{jsxref("Temporal.PlainDateTime")}} object, with the date information removed. Because the date and time information don't have much interaction, all general information about time properties is documented here. + ### ISO 8601 format `PlainTime` 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): @@ -47,44 +51,44 @@ These properties are defined on `Temporal.PlainTime.prototype` and shared by all - {{jsxref("Object/constructor", "Temporal.PlainTime.prototype.constructor")}} - : The constructor function that created the instance object. For `Temporal.PlainTime` instances, the initial value is the {{jsxref("Temporal/PlainTime/PlainTime", "Temporal.PlainTime()")}} constructor. - {{jsxref("Temporal/PlainTime/hour", "Temporal.PlainTime.prototype.hour")}} - - : TODO + - : Returns a integer from 0 to 23 representing the hour component of this time. - {{jsxref("Temporal/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}} - - : TODO + - : Returns a integer from 0 to 999 representing the microsecond (10-6 second) component of this time. - {{jsxref("Temporal/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}} - - : TODO + - : Returns a integer from 0 to 999 representing the millisecond (10-3 second) component of this time. - {{jsxref("Temporal/PlainTime/minute", "Temporal.PlainTime.prototype.minute")}} - - : TODO + - : Returns a integer from 0 to 59 representing the minute component of this time. - {{jsxref("Temporal/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}} - - : TODO + - : Returns a integer from 0 to 999 representing the nanosecond (10-9 second) component of this time. - {{jsxref("Temporal/PlainTime/second", "Temporal.PlainTime.prototype.second")}} - - : TODO + - : Returns a integer from 0 to 59 representing the second component of this time. - `Temporal.PlainTime.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.PlainTime"`. This property is used in {{jsxref("Object.prototype.toString()")}}. ## Instance methods - {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} - - : TODO + - : Returns a new `Temporal.PlainTime` object representing this time moved forward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}), wrapping around the clock if necessary. - {{jsxref("Temporal/PlainTime/equals", "Temporal.PlainTime.prototype.equals()")}} - - : TODO + - : Returns `true` if this time is equivalent in value to another time (in a form convertible by {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}), and `false` otherwise. They are compared by their time values. Equivalent to `Temporal.PlainTime.compare(this, other) === 0`. - {{jsxref("Temporal/PlainTime/round", "Temporal.PlainTime.prototype.round()")}} - - : TODO + - : Returns a new `Temporal.PlainTime` object representing this time rounded to the given unit. - {{jsxref("Temporal/PlainTime/since", "Temporal.PlainTime.prototype.since()")}} - - : TODO + - : Returns a new {{jsxref("Temporal.Duration")}} object representing the duration from another time (in a form convertible by {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}) to this time. The duration is positive if the other time is before this time, and negative if after. - {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} - - : TODO + - : Returns a new `Temporal.PlainTime` object representing this time moved backward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}), wrapping around the clock if necessary. - {{jsxref("Temporal/PlainTime/toJSON", "Temporal.PlainTime.prototype.toJSON()")}} - - : TODO + - : Returns a string representing this time in the same [ISO 8601 format](#iso_8601_format) as calling {{jsxref("Temporal/PlainTime/toString", "toString()")}}. - {{jsxref("Temporal/PlainTime/toLocaleString", "Temporal.PlainTime.prototype.toLocaleString()")}} - - : TODO + - : Returns a string with a language-sensitive representation of this time. - {{jsxref("Temporal/PlainTime/toString", "Temporal.PlainTime.prototype.toString()")}} - - : TODO + - : Returns a string representing this time in the [ISO 8601 format](#iso_8601_format). - {{jsxref("Temporal/PlainTime/until", "Temporal.PlainTime.prototype.until()")}} - - : TODO + - : Returns a new {{jsxref("Temporal.Duration")}} object representing the duration from this time to another time (in a form convertible by {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}). The duration is positive if the other time is after this time, and negative if before. - {{jsxref("Temporal/PlainTime/valueOf", "Temporal.PlainTime.prototype.valueOf()")}} - : Throws a {{jsxref("TypeError")}}, which prevents `Temporal.PlainTime` 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/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} - - : TODO + - : Returns a new `Temporal.PlainTime` object representing this time with some fields replaced by new values. ## Specifications @@ -96,4 +100,6 @@ These properties are defined on `Temporal.PlainTime.prototype` and shared by all ## See also -- TODO +- {{jsxref("Temporal")}} +- {{jsxref("Temporal.Duration")}} +- {{jsxref("Temporal.PlainDateTime")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/microsecond/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/microsecond/index.md index b68e5aae6deb284..3ba22401deaf81e 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/microsecond/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/microsecond/index.md @@ -7,15 +7,37 @@ browser-compat: javascript.builtins.Temporal.PlainTime.microsecond {{JSRef}} -The **`microsecond`** accessor property of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`microsecond`** accessor property of {{jsxref("Temporal.PlainTime")}} instances returns a integer from 0 to 999 representing the microsecond (10-6 second) component of this time. -## Description - -TODO +The set accessor of `microsecond` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainTime/with", "with()")}} method to create a new `Temporal.PlainTime` object with the desired new value. ## Examples -TODO +### Using microsecond + +```js +const time = Temporal.PlainTime.from("12:34:56"); +console.log(time.microsecond); // 0 + +const time2 = Temporal.PlainTime.from("12:34:56.123456789"); +console.log(time2.microsecond); // 456 +``` + +### Changing microsecond + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.with({ microsecond: 100 }); +console.log(newTime.toString()); // 12:34:56.0001 +``` + +You can also use {{jsxref("Temporal/PlainTime/add", "add()")}} or {{jsxref("Temporal/PlainTime/subtract", "subtract()")}} to move a certain number of microseconds from the current time. + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.add({ microseconds: 100 }); +console.log(newTime.toString()); // 12:34:56.0001 +``` ## Specifications @@ -27,4 +49,10 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainTime/second", "Temporal.PlainTime.prototype.second")}} +- {{jsxref("Temporal/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}} +- {{jsxref("Temporal/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/millisecond/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/millisecond/index.md index 69148304b306331..1a485a3a27f7804 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/millisecond/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/millisecond/index.md @@ -7,15 +7,37 @@ browser-compat: javascript.builtins.Temporal.PlainTime.millisecond {{JSRef}} -The **`millisecond`** accessor property of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`millisecond`** accessor property of {{jsxref("Temporal.PlainTime")}} instances returns a integer from 0 to 999 representing the millisecond (10-3 second) component of this time. -## Description - -TODO +The set accessor of `millisecond` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainTime/with", "with()")}} method to create a new `Temporal.PlainTime` object with the desired new value. ## Examples -TODO +### Using millisecond + +```js +const time = Temporal.PlainTime.from("12:34:56"); +console.log(time.millisecond); // 0 + +const time2 = Temporal.PlainTime.from("12:34:56.123456789"); +console.log(time2.millisecond); // 123 +``` + +### Changing millisecond + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.with({ millisecond: 100 }); +console.log(newTime.toString()); // 12:34:56.1 +``` + +You can also use {{jsxref("Temporal/PlainTime/add", "add()")}} or {{jsxref("Temporal/PlainTime/subtract", "subtract()")}} to move a certain number of milliseconds from the current time. + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.add({ milliseconds: 100 }); +console.log(newTime.toString()); // 12:34:56.1 +``` ## Specifications @@ -27,4 +49,10 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainTime/second", "Temporal.PlainTime.prototype.second")}} +- {{jsxref("Temporal/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}} +- {{jsxref("Temporal/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/minute/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/minute/index.md index 4cd1ea345457160..d8b631f7f295737 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/minute/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/minute/index.md @@ -7,15 +7,34 @@ browser-compat: javascript.builtins.Temporal.PlainTime.minute {{JSRef}} -The **`minute`** accessor property of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`minute`** accessor property of {{jsxref("Temporal.PlainTime")}} instances returns a integer from 0 to 59 representing the minute component of this time. -## Description - -TODO +The set accessor of `minute` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainTime/with", "with()")}} method to create a new `Temporal.PlainTime` object with the desired new value. ## Examples -TODO +### Using minute + +```js +const time = Temporal.PlainTime.from("12:34:56"); +console.log(time.minute); // 34 +``` + +### Changing minute + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.with({ minute: 58 }); +console.log(newTime.toString()); // 12:58:56 +``` + +You can also use {{jsxref("Temporal/PlainTime/add", "add()")}} or {{jsxref("Temporal/PlainTime/subtract", "subtract()")}} to move a certain number of minutes from the current time. + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.add({ minutes: 24 }); +console.log(newTime.toString()); // 12:58:56 +``` ## Specifications @@ -27,4 +46,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/nanosecond/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/nanosecond/index.md index 58b330accd9bc22..269928544054524 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/nanosecond/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/nanosecond/index.md @@ -7,15 +7,37 @@ browser-compat: javascript.builtins.Temporal.PlainTime.nanosecond {{JSRef}} -The **`nanosecond`** accessor property of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`nanosecond`** accessor property of {{jsxref("Temporal.PlainTime")}} instances returns a integer from 0 to 999 representing the nanosecond (10-9 second) component of this time. -## Description - -TODO +The set accessor of `nanosecond` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainTime/with", "with()")}} method to create a new `Temporal.PlainTime` object with the desired new value. ## Examples -TODO +### Using nanosecond + +```js +const time = Temporal.PlainTime.from("12:34:56"); +console.log(time.nanosecond); // 0 + +const time2 = Temporal.PlainTime.from("12:34:56.123456789"); +console.log(time2.nanosecond); // 789 +``` + +### Changing nanosecond + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.with({ nanosecond: 100 }); +console.log(newTime.toString()); // 12:34:56.0000001 +``` + +You can also use {{jsxref("Temporal/PlainTime/add", "add()")}} or {{jsxref("Temporal/PlainTime/subtract", "subtract()")}} to move a certain number of nanoseconds from the current time. + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.add({ nanoseconds: 100 }); +console.log(newTime.toString()); // 12:34:56.0000001 +``` ## Specifications @@ -27,4 +49,10 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainTime/second", "Temporal.PlainTime.prototype.second")}} +- {{jsxref("Temporal/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}} +- {{jsxref("Temporal/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}} 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 f753fc70e858707..1835c6bc2851c83 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 @@ -28,33 +28,35 @@ new Temporal.PlainTime(hour, minute, second, millisecond, microsecond, nanosecon ### Parameters - `hour` {{optional_inline}} - - : TODO + - : A number, truncated to an integer, representing the hour component. - `minute` {{optional_inline}} - - : TODO + - : A number, truncated to an integer, representing the minute component. - `second` {{optional_inline}} - - : TODO + - : A number, truncated to an integer, representing the second component. - `millisecond` {{optional_inline}} - - : TODO + - : A number, truncated to an integer, representing the millisecond component. - `microsecond` {{optional_inline}} - - : TODO + - : A number, truncated to an integer, representing the microsecond component. - `nanosecond` {{optional_inline}} - - : TODO + - : A number, truncated to an integer, representing the nanosecond component. ### Return value -TODO +A new `Temporal.PlainTime` object, representing the time specified by the parameters. ### Exceptions -TODO - -## Description - -TODO +- {{jsxref("RangeError")}} + - : Thrown if any of the components is not a finite number, or they don't represent a valid time. ## Examples -TODO +### Using Temporal.PlainTime() + +```js +const time = new Temporal.PlainTime(12, 34, 56, 123, 456, 789); +console.log(time.toString()); // 12:34:56.123456789 +``` ## Specifications @@ -66,4 +68,5 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/round/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/round/index.md index a4544bae8be2bf9..f37852bd2577eda 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/round/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/round/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.round {{JSRef}} -The **`round()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`round()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a new `Temporal.PlainTime` object representing this time rounded to the given unit. ## Syntax @@ -19,25 +19,43 @@ round(options) ### Parameters - `smallestUnit` - - : TODO + - : A string representing the [`smallestUnit`](#smallestunit_2) option. This is a convenience overload, so `round(smallestUnit)` is equivalent to `round({ smallestUnit })`, where `smallestUnit` is a string. - `options` - - : TODO + - : An object containing some or all of the following properties (in the order they are retrieved and validated): + - `roundingIncrement` {{optional_inline}} + - : A number (truncated to an integer) representing the rounding increment in the given `smallestUnit`. Defaults to `1`. Must be in the inclusive range of 1 to 1e9. The increment must be a divisor of the maximum value of `smallestUnit`; for example, if the unit is hours, the increment must be a divisor of 24 and must not be 24 itself, which means it can be 1, 2, 3, 4, 6, 8, or 12. + - `roundingMode` {{optional_inline}} + - : A string specifying how to round off the fractional part of `smallestUnit`. See [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode). Defaults to `"halfExpand"`. + - `smallestUnit` + - : A string representing the smallest unit to include in the output. The value must be one of the following: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. For units larger than `"nanosecond"`, fractional parts of the `smallestUnit` will be rounded according to the `roundingIncrement` and `roundingMode` settings. ### Return value -TODO +A new {{jsxref("Temporal.PlainTime")}} object representing this time rounded to the given unit, where all units smaller than `smallestUnit` are zeroed out. ### Exceptions -TODO +- {{jsxref("RangeError")}} + - : Thrown if any of the options is invalid. -## Description +## Examples -TODO +### Rounding off small units -## Examples +```js +const time = Temporal.PlainTime.from("12:34:56.123456789"); +const nearestMillisecond = time.round("millisecond"); +console.log(nearestMillisecond.toString()); // 12:34:56.123 -TODO +const nearestHalfHour = time.round({ + smallestUnit: "minute", + roundingIncrement: 30, +}); +console.log(nearestHalfHour.toString()); // 12:30:00 + +const nextHour = time.round({ smallestUnit: "hour", roundingMode: "ceil" }); +console.log(nextHour.toString()); // 13:00:00 +``` ## Specifications @@ -49,4 +67,4 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/second/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/second/index.md index d39f975bc2cafdd..3ce98ace07bb614 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/second/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/second/index.md @@ -7,15 +7,34 @@ browser-compat: javascript.builtins.Temporal.PlainTime.second {{JSRef}} -The **`second`** accessor property of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`second`** accessor property of {{jsxref("Temporal.PlainTime")}} instances returns a integer from 0 to 59 representing the second component of this time. -## Description - -TODO +The set accessor of `second` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainTime/with", "with()")}} method to create a new `Temporal.PlainTime` object with the desired new value. ## Examples -TODO +### Using second + +```js +const time = Temporal.PlainTime.from("12:34:56"); +console.log(time.second); // 56 +``` + +### Changing second + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.with({ second: 15 }); +console.log(newTime.toString()); // 12:34:15 +``` + +You can also use {{jsxref("Temporal/PlainTime/add", "add()")}} or {{jsxref("Temporal/PlainTime/subtract", "subtract()")}} to move a certain number of seconds from the current time. + +```js +const time = Temporal.PlainTime.from("12:34:56"); +const newTime = time.subtract({ seconds: 41 }); +console.log(newTime.toString()); // 12:34:15 +``` ## Specifications @@ -27,4 +46,10 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/with", "Temporal.PlainTime.prototype.with()")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}} +- {{jsxref("Temporal/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}} +- {{jsxref("Temporal/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/since/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/since/index.md index e462fe03838d29e..bc4650273e7e12b 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/since/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/since/index.md @@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainTime.since {{JSRef}} -The **`since()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`since()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a new {{jsxref("Temporal.Duration")}} object representing the duration from another time (in a form convertible by {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}) to this time. The duration is positive if the other time is before this time, and negative if after. + +This method does `this - other`. To do `other - this`, use the {{jsxref("Temporal/PlainTime/until", "until()")}} method. ## Syntax @@ -19,25 +21,64 @@ since(other, options) ### Parameters - `other` - - : TODO + - : A string, an object, or a {{jsxref("Temporal.PlainTime")}} instance representing a time to subtract from this time. It is converted to a `Temporal.PlainTime` object using the same algorithm as {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}. - `options` {{optional_inline}} - - : TODO + - : An object containing some or all of the following properties (in the order they are retrieved and validated): + - `largestUnit` {{optional_inline}} + - : A string representing the largest unit to include in the output. The value must be one of the following: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms, or the value `"auto"` which means `"hour"`. Defaults to `"auto"`. The result will not contain units larger than this; for example, if the largest unit is `"minute"`, then "1 hour 30 minutes" will become "90 minutes". + - `roundingIncrement` {{optional_inline}} + - : A number (truncated to an integer) representing the rounding increment in the given `smallestUnit`. Defaults to `1`. Must be in the inclusive range of 1 to 1e9. + - `roundingMode` {{optional_inline}} + - : A string specifying how to round off the fractional part of `smallestUnit`. See [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode). Defaults to `"trunc"`. + - `smallestUnit` {{optional_inline}} + - : A string representing the smallest unit to include in the output. The value must be one of the following: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"`, or their plural forms. Defaults to `"nanosecond"`. For units larger than `"nanosecond"`, fractional parts of the `smallestUnit` will be [rounded](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/round) according to the `roundingIncrement` and `roundingMode` settings. Must be smaller or equal to `largestUnit`. ### Return value -TODO +A new {{jsxref("Temporal.Duration")}} object representing the duration _since_ `other` to this time. The duration is positive if `other` is before this time, and negative if after. ### Exceptions -TODO +- {{jsxref("RangeError")}} + - : Thrown if any of the options is invalid. + +## Examples -## Description +### Using since() + +```js +const lunchTime = Temporal.PlainTime.from("12:30:00"); +const now = Temporal.Now.plainTimeISO(); +const duration = now.since(lunchTime); +console.log(`You had lunch ${duration.toLocaleString("en-US")} ago`); +// Example output: "You had lunch 3 hr, 42 min, 21 sec, 343 ms, 131 μs, 718 ns ago" + +const duration2 = now.since(lunchTime, { smallestUnit: "minute" }); +console.log(`You had lunch ${duration2.toLocaleString("en-US")} ago`); +// Example output: "You had lunch 3 hr, 42 min ago" + +const duration3 = now.since(lunchTime, { + largestUnit: "minute", + smallestUnit: "minute", +}); +console.log(`You had lunch ${duration3.toLocaleString("en-US")} ago`); +// Example output: "You had lunch 222 min ago" +``` -TODO +### Rounding the result -## Examples +By default the fractional part of the `smallestUnit` is truncated. You can round it up using the `roundingIncrement` and `roundingMode` options. -TODO +```js +const time1 = Temporal.PlainTime.from("12:30:00"); +const time2 = Temporal.PlainTime.from("12:30:01"); +const duration = time2.since(time1, { + smallestUnit: "second", + roundingIncrement: 15, + roundingMode: "ceil", +}); +console.log(duration.toString()); // "PT15S" +``` ## Specifications @@ -49,4 +90,8 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal.Duration")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainTime/until", "Temporal.PlainTime.prototype.until()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/subtract/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/subtract/index.md index 7e583473f712e40..5c880f9b28c3edf 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/subtract/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/subtract/index.md @@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainTime.subtract {{JSRef}} -The **`subtract()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`subtract()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a new `Temporal.PlainTime` object representing this time moved backward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}), wrapping around the clock if necessary. + +If you want to subtract two times and get a duration, use {{jsxref("Temporal/PlainTime/since", "since()")}} or {{jsxref("Temporal/PlainTime/until", "until()")}} instead. ## Syntax @@ -18,23 +20,25 @@ subtract(duration) ### Parameters - `duration` - - : TODO + - : A string, an object, or a {{jsxref("Temporal.Duration")}} instance representing a duration to subtract from this time. It is converted to a `Temporal.Duration` object using the same algorithm as {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}. ### Return value -TODO - -### Exceptions +A new `Temporal.PlainTime` object representing the time specified by the original `PlainTime`, minus the duration. -TODO +Subtracting a duration is equivalent to [adding](Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/add) its [negation](Web/JavaScript/Reference/Global_Objects/Temporal/Duration/negated), so all the same considerations apply. -## Description +## Examples -TODO +### Subtracting a duration -## Examples +```js +const start = Temporal.PlainTime.from("12:34:56"); +const end = start.subtract({ hours: 1, minutes: 30 }); +console.log(end.toString()); // 11:04:56 +``` -TODO +For more examples, see {{jsxref("Temporal/PlainTime/add", "add()")}}. ## Specifications @@ -46,4 +50,8 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal.Duration")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/since", "Temporal.PlainTime.prototype.since()")}} +- {{jsxref("Temporal/PlainTime/until", "Temporal.PlainTime.prototype.until()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tojson/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tojson/index.md index 72cd4b043cbabcf..d2018e57d47dcf7 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tojson/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tojson/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.toJSON {{JSRef}} -The **`toJSON()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`toJSON()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a string representing this time in the same [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime#iso_8601_format) as calling {{jsxref("Temporal/PlainTime/toString", "toString()")}}. ## Syntax @@ -21,19 +21,36 @@ None. ### Return value -TODO - -### Exceptions - -TODO +A string representing the given time in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime#iso_8601_format). ## Description -TODO +The `toJSON()` method is automatically called by {{jsxref("JSON.stringify()")}} when a `Temporal.PlainTime` object is stringified. This method is generally intended to, by default, usefully serialize `Temporal.PlainTime` objects during [JSON](/en-US/docs/Glossary/JSON) serialization, which can then be deserialized using the {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} function as the reviver of {{jsxref("JSON.parse()")}}. ## Examples -TODO +### Using toJSON() + +```js +const time = Temporal.PlainTime.from({ hour: 12, minute: 34, second: 56 }); +const timeStr = time.toJSON(); // '12:34:56' +const t2 = Temporal.PlainTime.from(timeStr); +``` + +### JSON serialization and parsing + +This example shows how `Temporal.PlainTime` can be serialized as JSON without extra effort, and how to parse it back. + +```js +const time = Temporal.PlainTime.from({ hour: 12, minute: 34, second: 56 }); +const jsonStr = JSON.stringify({ time }); // '{"time":"12:34:56"}' +const obj = JSON.parse(jsonStr, (key, value) => { + if (key === "time") { + return Temporal.PlainTime.from(value); + } + return value; +}); +``` ## Specifications @@ -45,4 +62,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} +- {{jsxref("Temporal/PlainTime/toString", "Temporal.PlainTime.prototype.toString()")}} +- {{jsxref("Temporal/PlainTime/toLocaleString", "Temporal.PlainTime.prototype.toLocaleString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tolocalestring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tolocalestring/index.md index 295653bbe88431e..01e6a04ee28869e 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tolocalestring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tolocalestring/index.md @@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainTime.toLocaleString {{JSRef}} -The **`toLocaleString()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`toLocaleString()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a string with a language-sensitive representation of this time. 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,59 @@ 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/PlainTime/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. 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: `hour`, `minute`, and `second` will default to `"numeric"`. + - Provide `timeStyle` only. + - Provide some date-time component options, where at least one of them is a time option (`dayPeriod`, `hour`, `minute`, `second`, `fractionalSecondDigits`). Only the specified time 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 time according to language-specific conventions. -### Exceptions +In implementations with `Intl.DateTimeFormat`, this is equivalent to `new Intl.DateTimeFormat(locales, options).format(time)`, 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 +const time = Temporal.PlainTime.from("12:34:56"); + +console.log(time.toLocaleString()); // 12:34:56 PM (assuming en-US locale) +``` + +### Using toLocaleString() with options + +You can customize which parts of the time are included in the output by providing the `options` parameter. + +```js +const time = Temporal.PlainTime.from("12:34:56"); +time.toLocaleString("en-US", { timeStyle: "short" }); // 12:34 PM +time.toLocaleString("en-US", { hour: "2-digit" }); // 12 PM +``` ## Specifications @@ -50,4 +85,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Intl.DateTimeFormat")}} +- {{jsxref("Temporal/PlainTime/toJSON", "Temporal.PlainTime.prototype.toJSON()")}} +- {{jsxref("Temporal/PlainTime/toString", "Temporal.PlainTime.prototype.toString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tostring/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tostring/index.md index 2d4bb2ad0bdf0f4..6e0e3081ed6d02b 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tostring/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/tostring/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.toString {{JSRef}} -The **`toString()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`toString()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a string representing this time in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime#iso_8601_format). ## Syntax @@ -19,23 +19,49 @@ toString(options) ### Parameters - `options` {{optional_inline}} - - : TODO + - : An object containing some or all of the following properties (in the order they are retrieved and validated): + - `fractionalSecondDigits` {{optional_inline}} + - : Either an integer from 0 to 9, or the string `"auto"`. The default is `"auto"`. If `"auto"`, then trailing zeros are removed from the fractional seconds. Otherwise, the fractional part of the second component contains this many digits, padded with zeros or rounded as necessary. + - `roundingMode` {{optional_inline}} + - : A string specifying how to round off fractional second digits beyond `fractionalSecondDigits`. See [`Intl.NumberFormat()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode). Defaults to `"trunc"`. + - `smallestUnit` {{optional_inline}} + - : A string specifying the smallest unit to include in the output. Possible values are `"minute"`, `"second"`, `"millisecond"`, `"microsecond"`, and `"nanosecond"`, or their plural forms, which (except `"minute"`) are equivalent to `fractionalSecondDigits` values of `0`, `3`, `6`, `9`, respectively. If specified, then `fractionalSecondDigits` is ignored. ### Return value -TODO +A string in the [ISO 8601 format](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime#iso_8601_format) representing this time. ### 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 time = Temporal.PlainTime.from("12:34:56"); +console.log(time.toString()); // '12:34:56' +``` -TODO +### Using options + +```js +const time1 = Temporal.PlainTime.from("12:00:00"); +console.log(time1.toString()); // '12:00:00' +console.log(time1.toString({ fractionalSecondDigits: 1 })); // '12:00:00.0' +console.log(time1.toString({ smallestUnit: "minute" })); // '12:00' +console.log(time1.toString({ smallestUnit: "nanosecond" })); // '12:00:00.000000000' + +const time2 = Temporal.PlainTime.from("12:34:56.123456789"); +console.log(time2.toString({ fractionalSecondDigits: 4 })); // '12:34:56.1234' +console.log( + time2.toString({ fractionalSecondDigits: 4, roundingMode: "halfExpand" }), +); // '12:34:56.1235' +``` ## Specifications @@ -47,4 +73,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} +- {{jsxref("Temporal/PlainTime/toJSON", "Temporal.PlainTime.prototype.toJSON()")}} +- {{jsxref("Temporal/PlainTime/toLocaleString", "Temporal.PlainTime.prototype.toLocaleString()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/until/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/until/index.md index 38b4ad7ff06be42..a7fd20f704dc425 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/until/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/until/index.md @@ -7,7 +7,9 @@ browser-compat: javascript.builtins.Temporal.PlainTime.until {{JSRef}} -The **`until()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`until()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a new {{jsxref("Temporal.Duration")}} object representing the duration from this time to another time (in a form convertible by {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}). The duration is positive if the other time is after this time, and negative if before. + +This method does `other - this`. To do `this - other`, use the {{jsxref("Temporal/PlainTime/since", "since()")}} method. ## Syntax @@ -19,25 +21,32 @@ until(other, options) ### Parameters - `other` - - : TODO + - : A string, an object, or a {{jsxref("Temporal.PlainTime")}} instance representing a time to subtract this time from. It is converted to a `Temporal.PlainTime` object using the same algorithm as {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}}. It must have the same calendar as `this`. - `options` {{optional_inline}} - - : TODO + - : The same options as [`since()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/since#options). ### Return value -TODO +A new {{jsxref("Temporal.Duration")}} object representing the duration from this time _until_ `other`. The duration is positive if `other` is after this time, and negative if before. ### Exceptions -TODO +- {{jsxref("RangeError")}} + - : Thrown if any of the options is invalid. -## Description +## Examples -TODO +### Using until() -## Examples +```js +const lunchTime = Temporal.PlainTime.from("12:30:00"); +const now = Temporal.Now.plainTimeISO(); +const duration = now.until(lunchTime); +console.log(`It will be ${duration.toLocaleString("en-US")} until lunch`); +// Example output: "It will be 3 hr, 42 min, 21 sec, 343 ms, 131 μs, 718 ns until lunch" +``` -TODO +For more examples, see [`since()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/since). ## Specifications @@ -49,4 +58,8 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal.Duration")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} +- {{jsxref("Temporal/PlainTime/since", "Temporal.PlainTime.prototype.since()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/with/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/with/index.md index 064142ce5059f2a..d4359361fce584d 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/with/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plaintime/with/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.with {{JSRef}} -The **`with()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO +The **`with()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a new `Temporal.PlainTime` object representing this time 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 time's fields. ## Syntax @@ -19,25 +19,51 @@ with(info, options) ### Parameters - `info` - - : TODO + + - : An object containing at least one of the following properties (in the order they are retrieved and validated): + + - {{jsxref("Temporal/PlainTime/hour", "hour")}} + - {{jsxref("Temporal/PlainTime/microsecond", "microsecond")}} + - {{jsxref("Temporal/PlainTime/millisecond", "millisecond")}} + - {{jsxref("Temporal/PlainTime/minute", "minute")}} + - {{jsxref("Temporal/PlainTime/nanosecond", "nanosecond")}} + - {{jsxref("Temporal/PlainTime/second", "second")}} + + They are truncated to be integers. Out-of-range values are handled by the `overflow` option. + - `options` {{optional_inline}} - - : TODO + - : An object containing the following property: + - `overflow` {{optional_inline}} + - : A string specifying the behavior when a time component is out of range. Possible values are: + - `"constrain"` (default) + - : The time component is clamped to the valid range. + - `"reject"` + - : A {{jsxref("RangeError")}} is thrown if the time component is out of range. ### Return value -TODO +A new `Temporal.PlainTime` 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 time. ### Exceptions -TODO +- {{jsxref("TypeError")}} + - : Thrown in one of the following cases: + - `info` is not an object with at least one recognized property or a string. + - `options` is not an object or `undefined`. +- {{jsxref("RangeError")}} + - : Thrown if the provided numerical properties are out of range, and `options.overflow` is set to `"reject"`. -## Description +## Examples -TODO +### Using with() -## Examples +```js +const time = Temporal.PlainTime.from("12:34:56.123456789"); +const newTime = time.with({ hour: 23 }); +console.log(newTime.toString()); // '23:34:56.123456789' +``` -TODO +For more examples, see the documentation for the individual properties that can be set using `with()`. ## Specifications @@ -49,4 +75,7 @@ TODO ## See also -- TODO +- {{jsxref("Temporal.PlainTime")}} +- {{jsxref("Temporal/PlainTime/from", "Temporal.PlainTime.from()")}} +- {{jsxref("Temporal/PlainTime/add", "Temporal.PlainTime.prototype.add()")}} +- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinmonth/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinmonth/index.md index 8adbc35b6228ea5..2e63593d47cdc8a 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinmonth/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinmonth/index.md @@ -38,6 +38,5 @@ console.log(ym.daysInMonth); // 31 - {{jsxref("Temporal/PlainYearMonth/subtract", "Temporal.PlainYearMonth.prototype.subtract()")}} - {{jsxref("Temporal/PlainYearMonth/year", "Temporal.PlainYearMonth.prototype.year")}} - {{jsxref("Temporal/PlainYearMonth/month", "Temporal.PlainYearMonth.prototype.month")}} -- {{jsxref("Temporal/PlainYearMonth/daysInWeek", "Temporal.PlainYearMonth.prototype.daysInWeek")}} - {{jsxref("Temporal/PlainYearMonth/daysInYear", "Temporal.PlainYearMonth.prototype.daysInYear")}} - {{jsxref("Temporal/PlainDate/daysInMonth", "Temporal.PlainDate.prototype.daysInMonth")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinyear/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinyear/index.md index e55357a949de06c..33fbf0a05c6ed14 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinyear/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/daysinyear/index.md @@ -38,5 +38,4 @@ console.log(ym.daysInYear); // 365 - {{jsxref("Temporal/PlainYearMonth/subtract", "Temporal.PlainYearMonth.prototype.subtract()")}} - {{jsxref("Temporal/PlainYearMonth/year", "Temporal.PlainYearMonth.prototype.year")}} - {{jsxref("Temporal/PlainYearMonth/daysInMonth", "Temporal.PlainYearMonth.prototype.daysInMonth")}} -- {{jsxref("Temporal/PlainYearMonth/daysInWeek", "Temporal.PlainYearMonth.prototype.daysInWeek")}} - {{jsxref("Temporal/PlainDate/daysInYear", "Temporal.PlainDate.prototype.daysInYear")}} diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/subtract/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/subtract/index.md index 188402d62c5033b..2d7bed7a15f61bf 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/subtract/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/subtract/index.md @@ -33,7 +33,7 @@ subtract(duration, options) ### Return value -A new `Temporal.PlainDate` object representing the date specified by the original date, minus the duration. +A new `Temporal.PlainYearMonth` object representing the year-month specified by the original `PlainYearMonth`, minus the duration. ## Description diff --git a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/year/index.md b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/year/index.md index 2e4bd4b856b5bc3..b0398caff678334 100644 --- a/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/year/index.md +++ b/files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/year/index.md @@ -38,6 +38,5 @@ console.log(ym.year); // 2021 - {{jsxref("Temporal/PlainYearMonth/subtract", "Temporal.PlainYearMonth.prototype.subtract()")}} - {{jsxref("Temporal/PlainYearMonth/era", "Temporal.PlainYearMonth.prototype.era")}} - {{jsxref("Temporal/PlainYearMonth/eraYear", "Temporal.PlainYearMonth.prototype.eraYear")}} -- {{jsxref("Temporal/PlainYearMonth/yearOfWeek", "Temporal.PlainYearMonth.prototype.yearOfWeek")}} - {{jsxref("Temporal/PlainYearMonth/month", "Temporal.PlainYearMonth.prototype.month")}} - {{jsxref("Temporal/PlainDate/year", "Temporal.PlainDate.prototype.year")}}