Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Normative: allow strings as required param in round and total methods #1875

Merged
merged 1 commit into from
Nov 18, 2021
Merged

Normative: allow strings as required param in round and total methods #1875

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 37 additions & 30 deletions docs/duration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -386,25 +386,28 @@ d = Temporal.Duration.from('-PT8H30M');
d.abs(); // PT8H30M
```

### duration.**round**(_options_: object) : Temporal.Duration
### duration.**round**(_roundTo_: string | object) : Temporal.Duration

**Parameters:**

- `options` (object): An object with properties representing options for the operation.
The following options are recognized:
- `largestUnit` (string): The largest unit of time to allow in the resulting `Temporal.Duration` object.
Valid values are `'auto'`, `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
The default is `'auto'`.
- `smallestUnit` (string): The smallest unit of time to round to in the resulting `Temporal.Duration` object.
Valid values are `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
The default is `'nanosecond'`, i.e. no rounding.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder, if rounding.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.
- `relativeTo` (`Temporal.PlainDateTime`): The starting point to use when converting between years, months, weeks, and days.
It must be a `Temporal.PlainDateTime`, or a value that can be passed to `Temporal.PlainDateTime.from()`.
- `roundTo` (string | object): A required string or object to control the operation.
justingrant marked this conversation as resolved.
Show resolved Hide resolved
- If a string is provided, the resulting `Temporal.Duration` object will be rounded to that unit.
Valid values are `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
A string parameter is treated the same as an object whose `smallestUnit` property value is that string.
- If an object is passed, the following properties are recognized:
- `largestUnit` (string): The largest unit of time to allow in the resulting `Temporal.Duration` object.
Valid values are `'auto'`, `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
The default is `'auto'`.
- `smallestUnit` (string): The smallest unit of time to round to in the resulting `Temporal.Duration` object.
Valid values are `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
The default is `'nanosecond'`, i.e. no rounding.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder, if rounding.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.
- `relativeTo` (`Temporal.PlainDateTime`): The starting point to use when converting between years, months, weeks, and days.
It must be a `Temporal.PlainDateTime`, or a value that can be passed to `Temporal.PlainDateTime.from()`.

**Returns:** a new `Temporal.Duration` object which is `duration`, rounded and/or balanced.

Expand All @@ -418,15 +421,15 @@ This operation is called "balancing."

For usage examples and a more complete explanation of how balancing works, see [Duration balancing](./balancing.md).

A `largestUnit` value of `'auto'`, which is the default if only `smallestUnit` is given, means that `largestUnit` should be the largest nonzero unit in the duration that is larger than `smallestUnit`.
A `largestUnit` value of `'auto'`, which is the default if only `smallestUnit` is given (or if `roundTo` is a string), means that `largestUnit` should be the largest nonzero unit in the duration that is larger than `smallestUnit`.
For example, in a duration of 3 days and 12 hours, `largestUnit: 'auto'` would mean the same as `largestUnit: 'day'`.
This behavior implies that the default balancing behavior of this method to not "grow" the duration beyond its current largest unit unless needed for rounding.

The `smallestUnit` option determines the unit to round to.
The `smallestUnit` option (or the value of `roundTo` if a string parameter is used) determines the unit to round to.
For example, to round to the nearest minute, use `smallestUnit: 'minute'`.
The default, if only `largestUnit` is given, is to do no rounding.
The default, if only `largestUnit` is given, is to do no rounding of smaller units.

At least one of `largestUnit` or `smallestUnit` is required.
If an object parameter is used, at least one of `largestUnit` or `smallestUnit` is required.

Converting between years, months, weeks, and other units requires a reference point.
If `largestUnit` or `smallestUnit` is years, months, or weeks, or the duration has nonzero years, months, or weeks, then the `relativeTo` option is required.
Expand Down Expand Up @@ -516,17 +519,20 @@ quarters = d.months / 3;
quarters; // => 3
```

### duration.**total**(_options_: object) : number
### duration.**total**(_totalOf_: string | object) : number

**Parameters:**

- `options` (object): An object with properties representing options for the operation.
The following options are recognized:
- `unit` (string): The unit of time that will be returned.
Valid values are `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
There is no default; `unit` is required.
- `relativeTo` (`Temporal.PlainDateTime`): The starting point to use when converting between years, months, weeks, and days.
It must be a `Temporal.PlainDateTime`, or a value that can be passed to `Temporal.PlainDateTime.from()`.
- `totalOf` (string | object): A required string or object to control the operation.
- If a string is passed, it represents the unit of time that will be returned.
Valid values are `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
A string parameter is treated the same as an object whose `unit` property value is that string.
- If an object is passed, the following properties are recognized:
- `unit` (string): The unit of time that will be returned.
Valid values are `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
There is no default; `unit` is required.
- `relativeTo` (`Temporal.PlainDateTime` ): The starting point to use when converting between years, months, weeks, and days.
It must be a `Temporal.PlainDateTime`, or a value that can be passed to `Temporal.PlainDateTime.from()`.

**Returns:** a floating-point number representing the number of desired units in the `Temporal.Duration`.

Expand All @@ -535,10 +541,11 @@ If the duration IS NOT evenly divisible by the desired unit, then a fractional r
If the duration IS evenly divisible by the desired unit, then the integer result will be identical to `duration.round({ smallestUnit: unit, largestUnit: unit, relativeTo })[unit]`.

Interpreting years, months, or weeks requires a reference point.
Therefore, `unit` is `'year'`, `'month'`, or `'week'`, or the duration has nonzero 'year', 'month', or 'week', then the `relativeTo` option is required.
Therefore, if `unit` is `'year'`, `'month'`, or `'week'`, or the duration has nonzero 'year', 'month', or 'week', then the `relativeTo` option is required.
For this reason, it's required to use the object (not string) form of `totalOf` in these cases.

The `relativeTo` option gives the starting point used when converting between or rounding to years, months, weeks, or days.
It is a `Temporal.PlainDateTime` instance.
It is a `Temporal.PlainDateTime` or `Temporal.ZonedDateTime` instance.
If any other type is provided, then it will be converted to a `Temporal.PlainDateTime` as if it were passed to `Temporal.PlainDateTime.from(..., { overflow: 'reject' })`.
A `Temporal.PlainDate` or a date string like `2020-01-01` is also accepted because time is optional when creating a `Temporal.PlainDateTime`.

Expand Down
31 changes: 19 additions & 12 deletions docs/instant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -474,25 +474,28 @@ billion = Temporal.Instant.fromEpochSeconds(1e9);
billion.since(epoch); // => PT1000000000S
```

### instant.**round**(_options_: object) : Temporal.Instant
### instant.**round**(_roundTo_: string | object) : Temporal.Instant

**Parameters:**

- `options` (object): An object with properties representing options for the operation.
The following options are recognized:
- `smallestUnit` (required string): The unit to round to.
- `roundTo` (string | object): A required string or object to control the operation.
- If a string is provided, the resulting `Temporal.Instant` object will be rounded to that unit.
Valid values are `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.

**Returns:** a new `Temporal.Instant` object which is `instant` rounded to `roundingIncrement` of `smallestUnit`.
A string parameter is treated the same as an object whose `smallestUnit` property value is that string.
- If an object is passed, the following properties are recognized:
- `smallestUnit` (required string): The unit to round to.
Valid values are `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.

**Returns:** a new `Temporal.Instant` object which is `instant` rounded to `roundTo` (if a string parameter is used) or `roundingIncrement` of `smallestUnit` (if an object parameter is used).

Rounds `instant` to the given unit and increment, and returns the result as a new `Temporal.Instant` object.

The `smallestUnit` option determines the unit to round to.
The `smallestUnit` option (or the value of `roundTo` if a string parameter is used) determines the unit to round to.
For example, to round to the nearest minute, use `smallestUnit: 'minute'`.
This option is required.

Expand All @@ -511,6 +514,10 @@ 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 up, like `ceil`.

As expected for a method named "round", the default rounding mode is `'halfExpand'` to match the behavior of `Math.round`.
Note that this is different than the `'trunc'` default used by `until` and `since` options because rounding up would be an unexpected default for those operations.
Other properties behave identically between these methods.

Example usage:

<!-- prettier-ignore-start -->
Expand Down
31 changes: 19 additions & 12 deletions docs/plaindatetime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -750,25 +750,28 @@ dt2 = Temporal.PlainDateTime.from('2019-01-31T15:30');
dt2.since(dt1); // => P8456DT12H5M29.9999965S
```

### datetime.**round**(_options_: object) : Temporal.PlainDateTime
### datetime.**round**(_roundTo_: string | object) : Temporal.PlainDateTime

**Parameters:**

- `options` (object): An object with properties representing options for the operation.
The following options are recognized:
- `smallestUnit` (required string): The unit to round to.
- `roundTo` (string | object): A required string or object to control the operation.
- If a string is provided, the resulting `Temporal.PlainDateTime` object will be rounded to that unit.
Valid values are `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.

**Returns:** a new `Temporal.PlainDateTime` object which is `datetime` rounded to `roundingIncrement` of `smallestUnit`.
A string parameter is treated the same as an object whose `smallestUnit` property value is that string.
- If an object is passed, the following properties are recognized:
- `smallestUnit` (required string): The unit to round to.
Valid values are `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.

**Returns:** a new `Temporal.PlainDateTime` object which is `datetime` rounded to `roundTo` (if a string parameter is used) or `roundingIncrement` of `smallestUnit` (if an object parameter is used).

Rounds `datetime` to the given unit and increment, and returns the result as a new `Temporal.PlainDateTime` object.

The `smallestUnit` option determines the unit to round to.
The `smallestUnit` option (or the value of `roundTo` if a string parameter is used) determines the unit to round to.
For example, to round to the nearest minute, use `smallestUnit: 'minute'`.
This option is required.

Expand All @@ -790,6 +793,10 @@ 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 up, like `ceil`.

As expected for a method named "round", the default rounding mode is `'halfExpand'` to match the behavior of `Math.round`.
Note that this is different than the `'trunc'` default used by `until` and `since` options because rounding up would be an unexpected default for those operations.
Other properties behave identically between these methods.

Example usage:

<!-- prettier-ignore-start -->
Expand Down
31 changes: 19 additions & 12 deletions docs/plaintime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -374,25 +374,28 @@ time.since(Temporal.PlainTime.from('19:39:09.068346205')); // => PT34M11.9030518
time.since(Temporal.PlainTime.from('22:39:09.068346205')); // => -PT2H25M48.096948106S
```

### time.**round**(_options_: object) : Temporal.PlainTime
### time.**round**(_roundTo_: string | object) : Temporal.PlainTime

**Parameters:**

- `options` (object): An object with properties representing options for the operation.
The following options are recognized:
- `smallestUnit` (required string): The unit to round to.
- `roundTo` (string | object): A required string or object to control the operation.
- If a string is provided, the resulting `Temporal.PlainTime` object will be rounded to that unit.
Valid values are `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.

**Returns:** a new `Temporal.PlainTime` object which is `time` rounded to `roundingIncrement` of `smallestUnit`.
A string parameter is treated the same as an object whose `smallestUnit` property value is that string.
- If an object is passed, the following properties are recognized:
- `smallestUnit` (required string): The unit to round to.
Valid values are `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, and `'nanosecond'`.
- `roundingIncrement` (number): The granularity to round to, of the unit given by `smallestUnit`.
The default is 1.
- `roundingMode` (string): How to handle the remainder.
Valid values are `'halfExpand'`, `'ceil'`, `'trunc'`, and `'floor'`.
The default is `'halfExpand'`.

**Returns:** a new `Temporal.PlainTime` object which is `time` rounded to `roundTo` (if a string parameter is used) or `roundingIncrement` of `smallestUnit` (if an object parameter is used).

Rounds `time` to the given unit and increment, and returns the result as a new `Temporal.PlainTime` object.

The `smallestUnit` option determines the unit to round to.
The `smallestUnit` option (or the value of `roundTo` if a string parameter is used) determines the unit to round to.
For example, to round to the nearest minute, use `smallestUnit: 'minute'`.
This option is required.

Expand All @@ -412,6 +415,10 @@ 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 up, like `ceil`.

As expected for a method named "round", the default rounding mode is `'halfExpand'` to match the behavior of `Math.round`.
Note that this is different than the `'trunc'` default used by `until` and `since` options because rounding up would be an unexpected default for those operations.
Other properties behave identically between these methods.

Example usage:

<!-- prettier-ignore-start -->
Expand Down
Loading