diff --git a/docs/cookbook.md b/docs/cookbook.md index ac40daf41..dae52e0ef 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -522,7 +522,7 @@ Here are some examples of taking an existing date, and adjusting the day of the Likewise, here are some examples of taking an existing date and adjusting the month, but keeping the day and year the same. -Depending on the behavior you want, you will need to pick the right `overflow` option, but the default of `"constrain"` should be correct for most cases. +Depending on the behavior you want, you will need to pick the right `overflow` option, but the default of `'constrain'` should be correct for most cases. ```javascript diff --git a/docs/duration.md b/docs/duration.md index 7739b92c5..0be1749f5 100644 --- a/docs/duration.md +++ b/docs/duration.md @@ -445,21 +445,21 @@ Instead of 60 minutes, use 1 hour. The `roundingMode` option controls how the rounding is performed. -- `halfExpand`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. - When there is a tie, round away from zero like `ceil` for positive durations and like `floor` for negative durations. +- `'halfExpand'`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. + When there is a tie, round away from zero like `'ceil'` for positive durations and like `'floor'` for negative durations. This is the default, and matches how rounding is often taught in school. -- `ceil`: Always round towards positive infinity. +- `'ceil'`: Always round towards positive infinity. For negative durations this option will decrease the absolute value of the duration which may be unexpected. - To round away from zero, use `expand`. -- `expand`: Always round away from zero like `ceil` for positive durations and like `floor` for negative durations. -- `trunc`: Always round towards zero, chopping off the part after the decimal point. -- `floor`: Always round down, towards negative infinity. - This mode acts the same as `trunc` for positive durations but for negative durations it will increase the absolute value of the result which may be unexpected. - For this reason, `trunc` is recommended for most "round down" use cases. -- `halfCeil`: Round to the nearest of the allowed values like `halfExpand`, but when there is a tie, round towards positive infinity like `ceil`. -- `halfFloor`: Round to the nearest of the allowed values like `halfExpand`, but when there is a tie, round towards negative infinity like `floor`. -- `halfTrunc`: Round to the nearest of the allowed values like `halfExpand`, but when there is a tie, round towards zero like `trunc`. -- `halfEven`: Round to the nearest of the allowed values like `halfExpand`, but when there is a tie, round towards the value that is an even multiple of the `roundingIncrement`. + To round away from zero, use `'expand'`. +- `'expand'`: Always round away from zero like `'ceil'` for positive durations and like `'floor'` for negative durations. +- `'trunc'`: Always round towards zero, chopping off the part after the decimal point. +- `'floor'`: Always round down, towards negative infinity. + This mode acts the same as `'trunc'` for positive durations but for negative durations it will increase the absolute value of the result which may be unexpected. + For this reason, `'trunc'` is recommended for most "round down" use cases. +- `'halfCeil'`: Round to the nearest of the allowed values like `'halfExpand'`, but when there is a tie, round towards positive infinity like `'ceil'`. +- `'halfFloor'`: Round to the nearest of the allowed values like `'halfExpand'`, but when there is a tie, round towards negative infinity like `'floor'`. +- `'halfTrunc'`: Round to the nearest of the allowed values like `'halfExpand'`, but when there is a tie, round towards zero like `'trunc'`. +- `'halfEven'`: Round to the nearest of the allowed values like `'halfExpand'`, but when there is a tie, round towards the value that is an even multiple of the `roundingIncrement`. For example, with a `roundingIncrement` of 2, the number 7 would round up to 8 instead of down to 6, because 8 is an even multiple of 2 (2 × 4 = 8, and 4 is even), whereas 6 is an odd multiple (2 × 3 = 6, and 3 is odd). The `relativeTo` option gives the starting point used when converting between or rounding to years, months, weeks, or days. diff --git a/docs/instant.md b/docs/instant.md index d63bd4f49..8e085b8af 100644 --- a/docs/instant.md +++ b/docs/instant.md @@ -502,12 +502,12 @@ The combination of `roundingIncrement` and `smallestUnit` must make an increment The `roundingMode` option controls how the rounding is performed. -- `ceil`, `expand`: Always round up, towards the end of time. -- `floor`, `trunc`: Always round down, towards the beginning of time. -- `halfCeil`, `halfExpand`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. - When there is a tie, round up, like `ceil`. -- `halfFloor`, `halfTrunc`: Round to the nearest of the allowed values, like `halfExpand`, but when there is a tie, round down, like `floor`. -- `halfEven`: Round to the nearest of the allowed values, but when there is a tie, round towards the value that is an even multiple of `roundingIncrement`. +- `'ceil'`, `'expand'`: Always round up, towards the end of time. +- `'floor'`, `'trunc'`: Always round down, towards the beginning of time. +- `'halfCeil'`, `'halfExpand'`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. + When there is a tie, round up, like `'ceil'`. +- `'halfFloor'`, `'halfTrunc'`: Round to the nearest of the allowed values, like `'halfExpand'`, but when there is a tie, round down, like `'floor'`. +- `'halfEven'`: Round to the nearest of the allowed values, but when there is a tie, round towards the value that is an even multiple of `roundingIncrement`. For example, with a `roundingIncrement` of 2, the number 7 would round up to 8 instead of down to 6, because 8 is an even multiple of 2 (2 × 4 = 8, and 4 is even), whereas 6 is an odd multiple (2 × 3 = 6, and 3 is odd). Several pairs of modes behave the same as each other, but are both included for consistency with `Temporal.Duration.round()`, where they are not the same. diff --git a/docs/plaindate.md b/docs/plaindate.md index 09854b97c..53d4d514f 100644 --- a/docs/plaindate.md +++ b/docs/plaindate.md @@ -58,8 +58,8 @@ date = new Temporal.PlainDate(2020, 3, 14); // => 2020-03-14 - `options` (optional object): An object with properties representing options for constructing the date. The following options are recognized: - `overflow` (string): How to deal with out-of-range values if `item` is an object. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDate` object. @@ -81,8 +81,8 @@ If the string isn't valid according to ISO 8601, then a `RangeError` will be thr The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). -- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. +- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). +- In `'reject'` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. @@ -364,8 +364,8 @@ date.with({ year: 2100 }).inLeapYear; // => false - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - `overflow` (string): How to deal with out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDate` object. @@ -414,8 +414,8 @@ date.withCalendar('iso8601'); // => 2006-08-24 - `options` (optional object): An object with properties representing options for the addition. The following options are recognized: - `overflow` (optional string): How to deal with additions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDate` object which is the date indicated by `date` plus `duration`. @@ -431,8 +431,8 @@ Some additions may be ambiguous, because months have different lengths. For example, adding one month to August 31 would result in September 31, which doesn't exist. For these cases, the `overflow` option tells what to do: -- In `constrain` mode (the default), out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. +- In `'constrain'` mode (the default), out-of-range values are clamped to the nearest in-range value. +- In `'reject'` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDate` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`. @@ -457,8 +457,8 @@ date.add({ months: 1 }, { overflow: 'reject' }); // => throws - `options` (optional object): An object with properties representing options for the subtraction. The following options are recognized: - `overflow` (string): How to deal with subtractions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDate` object which is the date indicated by `date` minus `duration`. @@ -474,8 +474,8 @@ Some subtractions may be ambiguous, because months have different lengths. For example, subtracting one month from July 31 would result in June 31, which doesn't exist. For these cases, the `overflow` option tells what to do: -- In `constrain` mode (the default), out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. +- In `'constrain'` mode (the default), out-of-range values are clamped to the nearest in-range value. +- In `'reject'` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDate` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`. @@ -521,8 +521,8 @@ If `other` is not a `Temporal.PlainDate` object, then it will be converted to on The `largestUnit` option controls how the resulting duration is expressed. The returned `Temporal.Duration` object will not have any nonzero fields that are larger than the unit in `largestUnit`. -A difference of two years will become 24 months when `largestUnit` is `"months"`, for example. -However, a difference of two months will still be two months even if `largestUnit` is `"years"`. +A difference of two years will become 24 months when `largestUnit` is `'months'`, for example. +However, a difference of two months will still be two months even if `largestUnit` is `'years'`. A value of `'auto'` means `'day'`, unless `smallestUnit` is `'year'`, `'month'`, or `'week'`, in which case `largestUnit` is equal to `smallestUnit`. By default, the largest unit in the result is days. diff --git a/docs/plaindatetime.md b/docs/plaindatetime.md index 24b9ba4fa..0f6870d88 100644 --- a/docs/plaindatetime.md +++ b/docs/plaindatetime.md @@ -88,8 +88,8 @@ datetime = new Temporal.PlainDateTime(2020, 3, 14, 13, 37); // => 2020-03-14T13: - `options` (optional object): An object with properties representing options for constructing the date and time. The following options are recognized: - `overflow` (string): How to deal with out-of-range values if `item` is an object. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDateTime` object. @@ -112,16 +112,16 @@ If the string isn't valid according to ISO 8601, then a `RangeError` will be thr The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). -- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. +- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). +- In `'reject'` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDateTime` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`. > **NOTE**: Although Temporal does not deal with leap seconds, dates coming from other software may have a `second` value of 60. -> In the default `constrain` mode and when parsing an ISO 8601 string, this will be converted to 59. -> In `reject` mode, this function will throw, so if you have to interoperate with times that may contain leap seconds, don't use `reject`. +> In the default `'constrain'` mode and when parsing an ISO 8601 string, this will be converted to 59. +> In `'reject'` mode, this function will throw, so if you have to interoperate with times that may contain leap seconds, don't use `'reject'`. > **NOTE**: The allowed values for the `item.month` property start at 1, which is different from legacy `Date` where months are represented by zero-based indices (0 to 11). @@ -455,8 +455,8 @@ dt.with({ year: 2100 }).inLeapYear; // => false - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - `overflow` (string): How to deal with out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDateTime` object. @@ -533,8 +533,8 @@ dt.withCalendar('iso8601'); // => 1995-12-07T03:24:30.0000035 - `options` (optional object): An object with properties representing options for the addition. The following options are recognized: - `overflow` (string): How to deal with additions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDateTime` object which is the date and time indicated by `datetime` plus `duration`. @@ -547,8 +547,8 @@ Some additions may be ambiguous, because months have different lengths. For example, adding one month to August 31 would result in September 31, which doesn't exist. For these cases, the `overflow` option tells what to do: -- In `constrain` mode (the default), out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. +- In `'constrain'` mode (the default), out-of-range values are clamped to the nearest in-range value. +- In `'reject'` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDateTime` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`. @@ -573,8 +573,8 @@ dt.add({ months: 1 }, { overflow: 'reject' }); // => throws - `options` (optional object): An object with properties representing options for the subtraction. The following options are recognized: - `overflow` (string): How to deal with subtractions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainDateTime` object which is the time indicated by `datetime` minus `duration`. @@ -587,8 +587,8 @@ Some subtractions may be ambiguous, because months have different lengths. For example, subtracting one month from July 31 would result in June 31, which doesn't exist. For these cases, the `overflow` option tells what to do: -- In `constrain` mode (the default), out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. +- In `'constrain'` mode (the default), out-of-range values are clamped to the nearest in-range value. +- In `'reject'` mode, an addition that would result in an out-of-range value fails, and a `RangeError` is thrown. Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDateTime` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`. @@ -756,12 +756,12 @@ If `smallestUnit` is `'day'`, then 1 is the only allowed value for `roundingIncr The `roundingMode` option controls how the rounding is performed. -- `ceil`, `expand`: Always round up, towards the end of time. -- `floor`, `trunc`: Always round down, towards the beginning of time. -- `halfCeil`, `halfExpand`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. - When there is a tie, round up, like `ceil`. -- `halfFloor`, `halfTrunc`: Round to the nearest of the allowed values, like `halfExpand`, but when there is a tie, round down, like `floor`. -- `halfEven`: Round to the nearest of the allowed values, but when there is a tie, round towards the value that is an even multiple of `roundingIncrement`. +- `'ceil'`, `'expand'`: Always round up, towards the end of time. +- `'floor'`, `'trunc'`: Always round down, towards the beginning of time. +- `'halfCeil'`, `'halfExpand'`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. + When there is a tie, round up, like `'ceil'`. +- `'halfFloor'`, `'halfTrunc'`: Round to the nearest of the allowed values, like `'halfExpand'`, but when there is a tie, round down, like `'floor'`. +- `'halfEven'`: Round to the nearest of the allowed values, but when there is a tie, round towards the value that is an even multiple of `roundingIncrement`. For example, with a `roundingIncrement` of 2, the number 7 would round up to 8 instead of down to 6, because 8 is an even multiple of 2 (2 × 4 = 8, and 4 is even), whereas 6 is an odd multiple (2 × 3 = 6, and 3 is odd). Several pairs of modes behave the same as each other, but are both included for consistency with `Temporal.Duration.round()`, where they are not the same. diff --git a/docs/plainmonthday.md b/docs/plainmonthday.md index bde7b54c7..53cb1dddc 100644 --- a/docs/plainmonthday.md +++ b/docs/plainmonthday.md @@ -59,8 +59,8 @@ md = new Temporal.PlainMonthDay(2, 29); // => 02-29 - `options` (optional object): An object with properties representing options for constructing the date. The following options are recognized: - `overflow` (string): How to deal with out-of-range values if `item` is an object. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainMonthDay` object. @@ -83,8 +83,8 @@ A `RangeError` will also be thrown for strings that contain a `Z` in place of a The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value, with "nearest" defined by the calendar. -- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. +- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value, with "nearest" defined by the calendar. +- In `'reject'` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. If `day`, `month` and `year` are provided, that calendar date must exist in the provided calendar or a `RangeError` will be thrown. The `overflow` option is ignored if `item` is a string. @@ -180,8 +180,8 @@ The `calendarId` read-only property gives the calendar that the `monthCode` and - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - `overflow` (string): How to deal with out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. There are two ways to change the month: providing `monthCode` or `month`. If `month` is used and `calendar` is provided, then `year` must be provided as well because `month` is ambiguous in some calendars without knowing the year. @@ -193,8 +193,8 @@ This method creates a new `Temporal.PlainMonthDay` which is a copy of `monthDay` The `overflow` option tells what should happen when out-of-range values are given or when the result would be an invalid month-day combination, such as "June 31": -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value, so June 31 would become June 30. -- In `reject` mode, the presence of out-of-range values will cause the constructor to throw a `RangeError`. +- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value, so June 31 would become June 30. +- In `'reject'` mode, the presence of out-of-range values will cause the constructor to throw a `RangeError`. > **NOTE:** For the purpose of this method, February is treated as having 29 days, so that it remains possible to construct a `Temporal.PlainMonthDay` for February 29. diff --git a/docs/plaintime.md b/docs/plaintime.md index 2f040ddc6..447a84efb 100644 --- a/docs/plaintime.md +++ b/docs/plaintime.md @@ -48,8 +48,8 @@ time = new Temporal.PlainTime(13, 37); // => 13:37:00 - `options` (optional object): An object with properties representing options for constructing the time. The following options are recognized: - `overflow` (optional string): How to deal with out-of-range values if `item` is an object. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainTime` object. @@ -68,14 +68,14 @@ In unusual cases of needing date or time components of `Z`-terminated timestamp The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value. -- In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. +- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value. +- In `'reject'` mode, the presence of out-of-range values will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. > **NOTE**: Although Temporal does not deal with leap seconds, times coming from other software may have a `second` value of 60. -> In the default `constrain` mode, this will be converted to 59. -> In `reject` mode, the constructor will throw, so if you have to interoperate with times that may contain leap seconds, don't use `reject`. +> In the default `'constrain'` mode, this will be converted to 59. +> In `'reject'` mode, the constructor will throw, so if you have to interoperate with times that may contain leap seconds, don't use `'reject'`. > However, if parsing an ISO 8601 string with a seconds component of `:60`, then it will always result in a `second` value of 59, in accordance with POSIX. Example usage: @@ -209,8 +209,8 @@ time.nanosecond; // => 205 - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - `overflow` (string): How to deal with out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainTime` object. @@ -402,12 +402,12 @@ Instead of 60 minutes, use 1 hour.) The `roundingMode` option controls how the rounding is performed. -- `ceil`, `expand`: Always round up, towards 23:59:59.999999999. -- `floor`, `trunc`: Always round down, towards 00:00. -- `halfCeil`, `halfExpand`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. - When there is a tie, round up, like `ceil`. -- `halfFloor`, `halfTrunc`: Round to the nearest of the allowed values, like `halfExpand`, but when there is a tie, round down, like `floor`. -- `halfEven`: Round to the nearest of the allowed values, but when there is a tie, round towards the value that is an even multiple of `roundingIncrement`. +- `'ceil'`, `'expand'`: Always round up, towards 23:59:59.999999999. +- `'floor'`, `'trunc'`: Always round down, towards 00:00. +- `'halfCeil'`, `'halfExpand'`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. + When there is a tie, round up, like `'ceil'`. +- `'halfFloor'`, `'halfTrunc'`: Round to the nearest of the allowed values, like `'halfExpand'`, but when there is a tie, round down, like `'floor'`. +- `'halfEven'`: Round to the nearest of the allowed values, but when there is a tie, round towards the value that is an even multiple of `roundingIncrement`. For example, with a `roundingIncrement` of 2, the number 7 would round up to 8 instead of down to 6, because 8 is an even multiple of 2 (2 × 4 = 8, and 4 is even), whereas 6 is an odd multiple (2 × 3 = 6, and 3 is odd). Several pairs of modes behave the same as each other, but are both included for consistency with `Temporal.Duration.round()`, where they are not the same. diff --git a/docs/plainyearmonth.md b/docs/plainyearmonth.md index 521f26e39..d4ee3f9c4 100644 --- a/docs/plainyearmonth.md +++ b/docs/plainyearmonth.md @@ -62,8 +62,8 @@ ym = new Temporal.PlainYearMonth(2019, 6); - `options` (optional object): An object with properties representing options for constructing the date. The following options are recognized: - `overflow` (string): How to deal with out-of-range values if `item` is an object. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainYearMonth` object. @@ -83,8 +83,8 @@ A `RangeError` will also be thrown for strings that contain a `Z` in place of a The `overflow` option works as follows, if `item` is an object: -- In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). -- In `reject` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. +- In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`). +- In `'reject'` mode, the presence of out-of-range values (after assuming extension of eras over arbitrary years to substitute `era` and `eraYear` with appropriate values for the `item`) will cause the function to throw a `RangeError`. The `overflow` option is ignored if `item` is a string. @@ -290,8 +290,8 @@ ym.with({ year: 2100 }).inLeapYear; // => false - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - `overflow` (string): How to deal with out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainYearMonth` object. @@ -323,8 +323,8 @@ ym.with({ month: 12 }); // => 2019-12 - `options` (optional object): An object with properties representing options for the addition. The following options are recognized: - `overflow` (string): How to deal with additions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainYearMonth` object which is the month indicated by `yearMonth` plus `duration`. @@ -359,8 +359,8 @@ ym.add({ years: 20, months: 4 }); // => 2039-10 - `options` (optional object): An object with properties representing options for the subtraction. The following options are recognized: - `overflow` (string): How to deal with additions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.PlainYearMonth` object which is the month indicated by `yearMonth` minus `duration`. diff --git a/docs/timezone.md b/docs/timezone.md index e68946195..274fe557a 100644 --- a/docs/timezone.md +++ b/docs/timezone.md @@ -301,7 +301,7 @@ In this case, then the `offset` option to [`Temporal.ZonedDateTime.from`](./zone See the documentation of `with()` for more details about why this option is used. - `'reject'`: Throw a `RangeError` if the offset is not valid for the provided date and time in the provided time zone. -The default is `reject` for [`Temporal.ZonedDateTime.from`](./zoneddatetime.md#from) because there is no obvious default solution. +The default is `'reject'` for [`Temporal.ZonedDateTime.from`](./zoneddatetime.md#from) because there is no obvious default solution. Instead, the developer needs to decide how to fix the now-invalid data. For [`Temporal.ZonedDateTime.with`](./zoneddatetime.md#with) the default is `'prefer'`. diff --git a/docs/zoneddatetime.md b/docs/zoneddatetime.md index 166109814..86f7258b9 100644 --- a/docs/zoneddatetime.md +++ b/docs/zoneddatetime.md @@ -184,7 +184,7 @@ Additionally, if the result is earlier or later than the range of dates that `Te > **NOTE**: Although Temporal does not deal with leap seconds, dates coming from other software may have a `second` value of 60. > In the default `'constrain'` mode and when parsing an ISO 8601 string, this will be converted to 59. -> In `'reject'` mode, this function will throw, so if you have to interoperate with times that may contain leap seconds, don't use `reject`. +> In `'reject'` mode, this function will throw, so if you have to interoperate with times that may contain leap seconds, don't use `'reject'`. If the input contains a time zone offset, in rare cases it's possible for those values to conflict for a particular local date and time. For example, this could happen if the definition of a time zone is changed (e.g. to abolish DST) after storing a `Temporal.ZonedDateTime` as a string representing a far-future event. @@ -873,8 +873,8 @@ zdt.withCalendar('gregory').eraYear; // => 1995 - `duration` (object): A `Temporal.Duration` object or a duration-like object. - `options` (optional object): An object which may have some or all of the following properties: - `overflow` (string): How to deal with additions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.ZonedDateTime` object representing the sum of `zonedDateTime` plus `duration`. @@ -936,8 +936,8 @@ laterHours.since(zdt, { largestUnit: 'hour' }).hours; // => 24 - `duration` (object): A `Temporal.Duration` object or a duration-like object. - `options` (optional object): An object which may have some or all of the following properties: - `overflow` (string): How to deal with additions that result in out-of-range values. - Allowed values are `constrain` and `reject`. - The default is `constrain`. + Allowed values are `'constrain'` and `'reject'`. + The default is `'constrain'`. **Returns:** a new `Temporal.ZonedDateTime` object representing the result of `zonedDateTime` minus `duration`.