Skip to content

Commit

Permalink
Remove time calendars
Browse files Browse the repository at this point in the history 
- Remove Calendar.timeFromFields(), Calendar.timeAdd(),
  Calendar.timeUntil(), Calendar.hour(), ..., Calendar.nanosecond().
- Remove PlainTime.withCalendar().
- Remove now.plainTime().
- Remove the calendar argument from PlainTime constructor.
- Remove the calendarName option from PlainTime.toString().
- Throw if there's a non-ISO calendar passed to PlainTime.from().
- The value of PlainTime.calendar is always the ISO calendar.
- Leave the names of the slots, the properties returned from
  PlainTime.getFields() and PlainTime.getISOFields().

See: #522
  • Loading branch information
@ptomato
ptomato committed Nov 16, 2020
1 parent 4589e83 commit 12fd8ed
Show file tree
Hide file tree
Showing 32 changed files with 334 additions and 1,087 deletions.
128 changes: 4 additions & 124 deletions docs/calendar.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -179,44 +179,8 @@ date.daysInYear; // => 355
date.calendar.daysInYear(date); // same result, but calling the method directly
```

### calendar.**hour**(_time_: Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime | object | string) : number

### calendar.**minute**(_time_: Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime | object | string) : number

### calendar.**second**(_time_: Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime | object | string) : number

### calendar.**millisecond**(_time_: Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime | object | string) : number

### calendar.**microsecond**(_time_: Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime | object | string) : number

### calendar.**nanosecond**(_time_: Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime | object | string) : number

The above methods are all similar.
They provide a way to query properties of a particular time in the calendar's time reckoning.

**Parameters:**

- `time` (`Temporal.PlainTime`, or value convertible to one): A time.

**Returns:** some piece of data (hour, minute, second, etc., depending on the method) associated with `time`, in `calendar`'s calendar system.

If `time` is not one of the appropriate Temporal objects, then it will be converted to a `Temporal.PlainTime` as if it were passed to `Temporal.PlainTime.from()`.

None of the above methods need to be called directly except in specialized code.
They are called indirectly when reading the various properties of `Temporal.ZonedDateTime`, `Temporal.PlainDateTime`, `Temporal.PlainTime`.

For example:

```javascript
const time = Temporal.PlainTime.from('03:20:00').withCalendar('ethiopic');
time.hour; // => 9
time.calendar.hour(time); // same result, but calling the method directly
```

### calendar.**dateFromFields**(_fields_: object, _options_: object, _constructor_: function) : Temporal.PlainDate

### calendar.**timeFromFields**(_fields_: object, _options_: object, _constructor_: function) : Temporal.PlainTime

### calendar.**yearMonthFromFields**(_fields_: object, _options_: object, _constructor_: function) : Temporal.PlainYearMonth

### calendar.**monthDayFromFields**(_fields_: object, _options_: object, _constructor_: function) : Temporal.PlainMonthDay
Expand All @@ -226,7 +190,7 @@ They provide a way to construct other Temporal objects from values in the calend

**Parameters:**

- `fields` (object): An object with properties similar to what is passed to `Temporal.PlainDate.from()`, `Temporal.PlainTime.from()`, `Temporal.PlainYearMonth.from()`, or `Temporal.PlainMonthDay.from()`, respectively.
- `fields` (object): An object with properties similar to what is passed to `Temporal.PlainDate.from()`, `Temporal.PlainYearMonth.from()`, or `Temporal.PlainMonthDay.from()`, respectively.
- `options`: (object): An object with properties representing options for constructing the Temporal object.
The following options are recognized:
- `overflow` (string): How to deal with out-of-range values in `fields`.
Expand All @@ -238,7 +202,7 @@ They provide a way to construct other Temporal objects from values in the calend
**Returns:** a new object of the type of `constructor`.

None of the above methods need to be called directly except in specialized code.
They are called indirectly when using `Temporal.PlainDate.from()`, `Temporal.PlainTime.from()`, `Temporal.PlainDateTime.from()`, `Temporal.PlainYearMonth.from()`, and `Temporal.PlainMonthDay.from()`.
They are called indirectly when using `Temporal.PlainDate.from()`, `Temporal.PlainDateTime.from()`, `Temporal.PlainYearMonth.from()`, and `Temporal.PlainMonthDay.from()`.

For example:

Expand Down Expand Up @@ -309,54 +273,6 @@ date.day; // => 7
date.toString(); // => 2020-06-28[c=islamic]
```

### calendar.**timeAdd**(_time_: Temporal.PlainTime | object | string, _duration_: Temporal.Duration | object | string, _options_: object, _constructor_: function) : Temporal.PlainDate

This method provides a way to do time arithmetic in the calendar's time reckoning.

**Parameters:**

- `time` (`Temporal.PlainTime`, or value convertible to one): A time.
- `duration` (`Temporal.Duration`, or value convertible to one): A duration to add to `time`.
For subtraction, add a negative duration.
- `options` (object): An object with properties representing options for performing the addition or subtraction.
The following options are recognized:
- `overflow` (string): How to deal with out-of-range values in the result of the addition or subtraction.
Allowed values are `constrain` and `reject`.
The default is `constrain`.
- `constructor` (function): The constructor function of the Temporal type to construct.
This is used when subclassing Temporal objects.

**Returns:** a new object of the type of `constructor`.

If `time` is not a `Temporal.PlainTime` object, or `duration` not a `Temporal.Duration` object, then they will be converted to one as if they were passed to `Temporal.PlainTime.from()` or `Temporal.Duration.from()`, respectively.

This method does not need to be called directly except in specialized code.
It is called indirectly when using `add()` and `subtract()` of `Temporal.PlainDateTime`, and `Temporal.PlainTime`.

For example:

```javascript
time = Temporal.PlainTime.from('03:20:00')
.withCalendar('ethiopic')
.add(Temporal.Duration.from({ minutes: 1 }), { overflow: 'reject' });
time.hour; // => 9
time.minute; // => 21
time.second; // => 0
time.toString(); // => 03:21:00[c=ethiopic]

// same result, but calling the method directly:
time = Temporal.Calendar.from('ethiopic').timeAdd(
Temporal.PlainTime.from('03:20:00'),
Temporal.Duration.from({ minutes: 1 }),
{ overflow: 'reject' },
Temporal.PlainTime
);
time.hour; // => 9
time.minute; // => 21
time.second; // => 0
time.toString(); // => 03:20:00[c=ethiopic]
```

### calendar.**dateUntil**(_one_: Temporal.PlainDate | object | string, _two_: Temporal.PlainDate | object | string, _options_: object) : Temporal.Duration

**Parameters:**
Expand Down Expand Up @@ -395,42 +311,6 @@ Temporal.Calendar.from('chinese').dateUntil(
); // => P1M2D
```

### calendar.**timeUntil**(_one_: Temporal.PlainTime | object | string, _two_: Temporal.PlainTime | object | string, _options_: object) : Temporal.Duration

**Parameters:**

- `one` (`Temporal.PlainTime`, or value convertible to one): A time.
- `two` (`Temporal.PlainTime`, or value convertible to one): Another time.
- `options` (object): An object with properties representing options for the operation.
The following options are recognized:
- `largestUnit` (optional string): The largest unit of time to allow in the resulting `Temporal.Duration` object.
Valid values are `'auto'`, `'hours'`, `'minutes'`, `'seconds'`, `'milliseconds'`, `microseconds'` and `'nanoseconds'`.
The default is `'auto'`.

**Returns:** a `Temporal.Duration` representing the time elapsed after `one` and until `two`.

If either of `one` or `two` are not `Temporal.PlainTime` objects, then they will be converted to one as if they were passed to `Temporal.PlainTime.from()`.

This method does not need to be called directly except in specialized code.
It is called indirectly when using the `until()` and `since()` methods of `Temporal.PlainDateTime`, and `Temporal.PlainTime`.

If `one` is later than `two`, then the resulting duration should be negative.

The default `largestUnit` value of `'auto'` is the same as `'hours'`.

For example:

```javascript
t1 = Temporal.PlainTime.from('03:10:00').withCalendar('ethiopic');
t2 = Temporal.PlainTime.from('03:30:00').withCalendar('ethiopic');
t1.until(t2, { largestUnit: 'minutes' }); // => PT20M

// same result, but calling the method directly:
Temporal.Calendar.from('ethiopic').timeUntil(Temporal.PlainTime.from('03:10:00'), Temporal.PlainTime.from('03:30:00'), {
largestUnit: 'minutes'
}); // => PT20M
```

### calendar.**fields**(fields: array<string>) : array<string>

**Parameters:**
Expand All @@ -440,9 +320,9 @@ Temporal.Calendar.from('ethiopic').timeUntil(Temporal.PlainTime.from('03:10:00')
**Returns:** a new list of field names.

This method does not need to be called directly except in specialized code.
It is called indirectly when using the `from()` static methods and `with()` methods of `Temporal.PlainDateTime`, `Temporal.PlainDate`, `Temporal.PlainTime`, and `Temporal.PlainYearMonth`.
It is called indirectly when using the `from()` static methods and `with()` methods of `Temporal.PlainDateTime`, `Temporal.PlainDate`, and `Temporal.PlainYearMonth`.

Custom calendars should override this method if they require more fields with which to denote the date than the standard `year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`, `microsecond`, and `nanosecond` (for example, `era`).
Custom calendars should override this method if they require more fields with which to denote the date than the standard `year`, `month`, and `day` (for example, `era`).
The input array contains the field names that are necessary for a particular operation (for example, `'month'` and `'day'` for `Temporal.PlainMonthDay.prototype.with()`), and the method should make a copy of the array and add whichever extra fields are necessary.

When subclassing `Temporal.Calendar`, this method doesn't need to be overridden, unless your calendar requires extra fields, because the default implementation returns a copy of `fields`.
Expand Down
72 changes: 14 additions & 58 deletions docs/plaintime.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ It can also be combined with a `Temporal.PlainDate` to yield a "zoneless" `Tempo

## Constructor

### **new Temporal.PlainTime**(_isoHour_: number = 0, _isoMinute_: number = 0, _isoSecond_: number = 0, _isoMillisecond_: number = 0, _isoMicrosecond_: number = 0, _isoNanosecond_: number = 0, _calendar_?: object) : Temporal.PlainTime
### **new Temporal.PlainTime**(_isoHour_: number = 0, _isoMinute_: number = 0, _isoSecond_: number = 0, _isoMillisecond_: number = 0, _isoMicrosecond_: number = 0, _isoNanosecond_: number = 0) : Temporal.PlainTime

**Parameters:**

Expand All @@ -25,15 +25,13 @@ It can also be combined with a `Temporal.PlainDate` to yield a "zoneless" `Tempo
- `isoMillisecond` (optional number): A number of milliseconds, ranging between 0 and 999 inclusive.
- `isoMicrosecond` (optional number): A number of microseconds, ranging between 0 and 999 inclusive.
- `isoNanosecond` (optional number): A number of nanoseconds, ranging between 0 and 999 inclusive.
- `calendar` (optional `Temporal.Calendar` or plain object): A calendar to project the time into.

**Returns:** a new `Temporal.PlainTime` object.

Use this constructor if you have the correct parameters for the time already as individual number values in the ISO 8601 calendar.
Otherwise, `Temporal.PlainTime.from()`, which accepts more kinds of input, allows inputting times in different calendar reckonings, and allows controlling the overflow behaviour, is probably more convenient.
Otherwise, `Temporal.PlainTime.from()`, which accepts more kinds of input and allows controlling the overflow behaviour, is probably more convenient.

All values are given as reckoned in the [ISO 8601 calendar](https://en.wikipedia.org/wiki/ISO_8601#Dates).
Together, `isoHour`, `isoMinute`, `isoSecond`, `isoMillisecond`, `isoMicrosecond`, and `isoNanosecond` must represent a valid date in that calendar, even if you are passing a different calendar as the `calendar` parameter.

Usage examples:

Expand All @@ -59,10 +57,10 @@ time = new Temporal.PlainTime(13, 37); // => 13:37

This static method creates a new `Temporal.PlainTime` object from another value.
If the value is another `Temporal.PlainTime` object, a new object representing the same time is returned.
If the value is any other object, a `Temporal.PlainTime` will be constructed from the values of any `hour`, `minute`, `second`, `millisecond`, `microsecond`, `nanosecond`, and `calendar` properties that are present.
Any missing ones except `calendar` will be assumed to be 0.
If the value is any other object, a `Temporal.PlainTime` will be constructed from the values of any `hour`, `minute`, `second`, `millisecond`, `microsecond`, and `nanosecond` properties that are present.
Any missing ones will be assumed to be 0.

If the `calendar` property is not present, it will be assumed to be `Temporal.Calendar.from('iso8601')`, the [ISO 8601 calendar](https://en.wikipedia.org/wiki/ISO_8601#Dates).
If the `calendar` property is present, it must be the string `'iso8601'` or the [ISO 8601 calendar](https://en.wikipedia.org/wiki/ISO_8601#Dates), for future compatibility.

Any non-object value will be converted to a string, which is expected to be in ISO 8601 format.
If the string designates a date or a time zone, they will be ignored.
Expand Down Expand Up @@ -171,9 +169,9 @@ time.nanosecond; // => 205
```
<!-- prettier-ignore-end -->

### time.**calendar**: object
### time.**calendar**: Temporal.Calendar

The `calendar` read-only property gives the calendar that the `hour`, `minute`, `second`, `millisecond`, `microsecond`, and `nanosecond` properties are interpreted in.
The value of the `calendar` read-only property is always the ISO 8601 calendar, for future compatibility.

## Methods

Expand All @@ -195,7 +193,7 @@ This method creates a new `Temporal.PlainTime` which is a copy of `time`, but an
Since `Temporal.PlainTime` objects are immutable, use this method instead of modifying one.

> **NOTE**: `calendar` and `timeZone` properties are not allowed on `timeLike`.
> See the `withCalendar` and `toZonedDateTime` methods instead.
> See the `toPlainDateTime` and `toZonedDateTime` methods instead.
Usage example:

Expand All @@ -211,21 +209,6 @@ time.add({ hours: 1 }).with({
}); // => 20:00
```

### time.**withCalendar**(_calendar_: object | string) : Temporal.PlainTime

**Parameters:**

- `calendar` (`Temporal.Calendar` or plain object or string): The calendar into which to project `time`.

**Returns:** a new `Temporal.PlainTime` object which is the time indicated by `time`, projected into `calendar`.

Usage example:

```javascript
time = Temporal.PlainTime.from('03:20:00[c=ethiopic]');
time.withCalendar('iso8601'); // => 03:20:00
```

### time.**add**(_duration_: Temporal.Duration | object | string, _options_?: object) : Temporal.PlainTime

**Parameters:**
Expand Down Expand Up @@ -464,9 +447,6 @@ time.equals(time); // => true

- `options` (optional object): An object with properties representing options for the operation.
The following options are recognized:
- `calendarName` (string): Whether to show the calendar annotation in the return value.
Valid values are `'auto'`, `'always'`, and `'never'`.
The default is `'auto'`.
- `fractionalSecondDigits` (number or string): How many digits to print after the decimal point in the output string.
Valid values are `'auto'`, 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9.
The default is `'auto'`.
Expand All @@ -488,10 +468,6 @@ If no options are given, the default is `fractionalSecondDigits: 'auto'`, which
The value is truncated to fit the requested precision, unless a different rounding mode is given with the `roundingMode` option, as in `Temporal.PlainDateTime.round()`.
Note that rounding may change the value of other units as well.

Normally, a calendar annotation is shown when `time`'s calendar is not the ISO 8601 calendar.
By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively.
For more information on the calendar annotation, see [ISO string extensions](./iso-string-ext.md#calendar-systems).

Example usage:

<!-- prettier-ignore-start -->
Expand Down Expand Up @@ -639,14 +615,14 @@ date = Temporal.PlainDate.from('2006-08-24');
time.toPlainDateTime(date); // => 2006-08-24T15:23:30.003
```

### time.**getFields**() : { hour: number, minute: number, second: number, millisecond: number, microsecond: number, nanosecond: number }
### time.**getFields**() : { hour: number, minute: number, second: number, millisecond: number, microsecond: number, nanosecond: number, calendar: Temporal.Calendar }

**Returns:** a plain object with properties equal to the fields of `time`.

This method can be used to convert a `Temporal.PlainTime` into a record-like data structure.
It returns a new plain JavaScript object, with all the fields as enumerable, writable, own data properties.

Note that if using a different calendar from ISO 8601, these will be the calendar-specific values and may include extra properties.
A `calendar` property is included and is always set to the ISO 8601 calendar.

Usage example:

Expand All @@ -656,37 +632,17 @@ Object.assign({}, time).minute; // => undefined
Object.assign({}, time.getFields()).minute; // => 23
```

### time.**getISOFields**(): { isoHour: number, isoMinute: number, isoSecond: number, isoMillisecond: number, isoMicrosecond: number, isoNanosecond: number, calendar: object }
### time.**getISOFields**(): { isoHour: number, isoMinute: number, isoSecond: number, isoMillisecond: number, isoMicrosecond: number, isoNanosecond: number, calendar: Temporal.Calendar }

**Returns:** a plain object with properties expressing `time` in the ISO 8601 calendar, as well as the value of `time.calendar`.
**Returns:** a plain object with properties expressing `time` in the ISO 8601 calendar.

This method is mainly useful if you are implementing a custom calendar.
Most code will not need to use it.
Use `time.getFields()` instead, or `time.withCalendar('iso8601').getFields()`.
This method is present for forward compatibility with custom calendars.
Use `time.getFields()` instead.

Usage example:

```javascript
time = Temporal.PlainTime.from('03:20:00');
f = time.getISOFields();
f.isoHour; // => 3
// Fields correspond exactly to constructor arguments:
time2 = new Temporal.PlainTime(
f.isoHour,
f.isoMinute,
f.isoSecond,
f.isoMillisecond,
f.isoMicrosecond,
f.isoNanosecond,
f.calendar
);
time.equals(time2); // => true

// Time in other calendar
time = time.withCalendar('ethiopic');
time.getFields().hour; // => 9
time.getISOFields().isoHour; // => 3

// Most likely what you need is this:
time.withCalendar('iso8601').hour; // => 3
```
Loading

0 comments on commit 12fd8ed

Please sign in to comment.