Next part of removals

docs/cookbook.md

@@ -428,13 +428,13 @@ Take the difference between two `Temporal.Instant` instances as a `Temporal.Dura
 ```
 <!-- prettier-ignore-end -->
 
-### Nearest offset transition in a time zone
+### Next offset transition in a time zone
 
-Map a `Temporal.Instant` instance and a `Temporal.TimeZone` object into a `Temporal.Instant` instance representing the nearest following exact time at which there is an offset transition in the time zone (e.g., for setting reminders).
+Map a `Temporal.ZonedDateTime` instance into another `Temporal.ZonedDateTime` instance representing the nearest following exact time at which there is an offset transition in the time zone (e.g., for setting reminders).
 
 <!-- prettier-ignore-start -->
 ```javascript
-{{cookbook/getInstantOfNearestOffsetTransitionToInstant.mjs}}
+{{cookbook/getNextOffsetTransitionFromExactTime.mjs}}
 ```
 <!-- prettier-ignore-end -->
 

docs/cookbook/all.mjs

@@ -11,9 +11,9 @@ import './getCurrentDate.mjs';
 import './getElapsedDurationSinceInstant.mjs';
 import './getFirstTuesdayOfMonth.mjs';
 import './getInstantBeforeOldRecord.mjs';
-import './getInstantOfNearestOffsetTransitionToInstant.mjs';
 import './getInstantWithLocalTimeInZone.mjs';
 import './getLocalizedArrival.mjs';
+import './getNextOffsetTransitionFromExactTime.mjs';
 import './getParseableZonedStringAtInstant.mjs';
 import './getSortedLocalDateTimes.mjs';
 import './getTimeStamp.mjs';

docs/cookbook/getInstantWithLocalTimeInZone.mjs

@@ -23,27 +23,26 @@
 function getInstantWithLocalTimeInZone(dateTime, timeZone, disambiguation = 'earlier') {
   // Handle the built-in modes first
   if (['compatible', 'earlier', 'later', 'reject'].includes(disambiguation)) {
-    return timeZone.getInstantFor(dateTime, { disambiguation });
+    return dateTime.toZonedDateTime(timeZone, { disambiguation }).toInstant();
   }
 
-  const possible = timeZone.getPossibleInstantsFor(dateTime);
+  const zdts = ['earlier', 'later'].map((disambiguation) => dateTime.toZonedDateTime(timeZone, { disambiguation }));
+  const instants = zdts.map((zdt) => zdt.toInstant()).reduce((a, b) => (a.equals(b) ? [a] : [a, b]));
 
   // Return only possibility if no disambiguation needed
-  if (possible.length === 1) return possible[0];
+  if (instants.length === 1) return instants[0];
 
   switch (disambiguation) {
     case 'clipEarlier':
-      if (possible.length === 0) {
-        const before = timeZone.getInstantFor(dateTime, { disambiguation: 'earlier' });
-        return timeZone.getNextTransition(before).subtract({ nanoseconds: 1 });
+      if (zdts[0].toPlainDateTime().equals(dateTime)) {
+        return instants[0];
       }
-      return possible[0];
+      return zdts[0].getTimeZoneTransition('next').subtract({ nanoseconds: 1 }).toInstant();
     case 'clipLater':
-      if (possible.length === 0) {
-        const before = timeZone.getInstantFor(dateTime, { disambiguation: 'earlier' });
-        return timeZone.getNextTransition(before);
+      if (zdts[1].toPlainDateTime().equals(dateTime)) {
+        return instants[1];
       }
-      return possible[possible.length - 1];
+      return zdts[0].getTimeZoneTransition('next').toInstant();
   }
   throw new RangeError(`invalid disambiguation ${disambiguation}`);
 }

docs/cookbook/getNextOffsetTransitionFromExactTime.mjs

@@ -0,0 +1,33 @@
+/**
+ * Get the nearest following exact time that the given time zone transitions
+ * to another UTC offset, inclusive or exclusive.
+ *
+ * @param {Temporal.ZonedDateTime} zonedDateTime - Starting exact time and time
+ *   zone to consider
+ * @param {boolean} inclusive - Include the start time, or not
+ * @returns {(Temporal.ZonedDateTime|null)} - Next UTC offset transition, or
+ *   null if none known at this time
+ */
+function getNextOffsetTransitionFromExactTime(zonedDateTime, inclusive) {
+  let nearest;
+  if (inclusive) {
+    // In case instant itself is the exact time of a transition:
+    nearest = zonedDateTime.subtract({ nanoseconds: 1 }).getTimeZoneTransition('next');
+  } else {
+    nearest = zonedDateTime.getTimeZoneTransition('next');
+  }
+  return nearest;
+}
+
+const nycTime = Temporal.ZonedDateTime.from('2019-04-16T21:01Z[America/New_York]');
+
+const nextTransition = getNextOffsetTransitionFromExactTime(nycTime, false);
+assert.equal(nextTransition.toString(), '2019-11-03T01:00:00-05:00[America/New_York]');
+
+// Inclusive
+const sameTransition = getNextOffsetTransitionFromExactTime(nextTransition, true);
+assert.equal(sameTransition.toString(), nextTransition.toString());
+
+// No known future DST transitions in a time zone
+const reginaTime = Temporal.ZonedDateTime.from('2019-04-16T21:01Z[America/Regina]');
+assert.equal(getNextOffsetTransitionFromExactTime(reginaTime), null);

docs/plaindate.md

@@ -813,13 +813,6 @@ date.toPlainYearMonth(); // => 2006-08
 date.toPlainMonthDay(); // => 08-24
 ```
 
-### date.**getCalendar**(): object
-
-**Returns:** a `Temporal.Calendar` instance or plain object representing the calendar in which `date` is reckoned.
-
-This method is mainly useful if you need an object on which to call calendar methods.
-Most code will not need to use it.
-
 ### date.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, calendar: string | object }
 
 **Returns:** a plain object with properties expressing `date` in the ISO 8601 calendar, as well as the calendar (usually a string, but may be an object) in which `date` is reckoned.

docs/plaindatetime.md

@@ -1005,13 +1005,6 @@ dt.toPlainDate().toPlainYearMonth(); // => 1995-12
 dt.toPlainDate().toPlainMonthDay(); // => 12-07
 ```
 
-### datetime.**getCalendar**(): object
-
-**Returns:** a `Temporal.Calendar` instance or plain object representing the calendar in which `datetime` is reckoned.
-
-This method is mainly useful if you need an object on which to call calendar methods.
-Most code will not need to use it.
-
 ### datetime.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, isoHour: number, isoMinute: number, isoSecond: number, isoMillisecond: number, isoMicrosecond: number, isoNanosecond: number, calendar: string | object }
 
 **Returns:** a plain object with properties expressing `datetime` in the ISO 8601 calendar, as well as the calendar (usually a string, but may be an object) in which `datetime` is reckoned.

docs/plainmonthday.md

@@ -390,13 +390,6 @@ md = Temporal.PlainMonthDay.from({
 date = md.toPlainDate({ era: 'reiwa', eraYear: 2 }); // => 2020-01-01[u-ca=japanese]
 ```
 
-### monthDay.**getCalendar**(): object
-
-**Returns:** a `Temporal.Calendar` instance or plain object representing the calendar in which `monthDay` is reckoned.
-
-This method is mainly useful if you need an object on which to call calendar methods.
-Most code will not need to use it.
-
 ### monthDay.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, calendar: string | object }
 
 **Returns:** a plain object with properties expressing `monthDay` in the ISO 8601 calendar, as well as the calendar (usually a string, but may be an object) in which `monthDay` is reckoned.

docs/plainyearmonth.md

@@ -642,13 +642,6 @@ ym = Temporal.PlainYearMonth.from('2019-06');
 ym.toPlainDate({ day: 24 }); // => 2019-06-24
 ```
 
-### yearMonth.**getCalendar**(): object
-
-**Returns:** a `Temporal.Calendar` instance or plain object representing the calendar in which `yearMonth` is reckoned.
-
-This method is mainly useful if you need an object on which to call calendar methods.
-Most code will not need to use it.
-
 ### yearMonth.**getISOFields**(): { isoYear: number, isoMonth: number, isoDay: number, calendar: string | object }
 
 **Returns:** a plain object with properties expressing `yearMonth` in the ISO 8601 calendar, as well as the calendar (usually a string, but may be an object) that `yearMonth` is reckoned in.

docs/timezone.md

@@ -219,74 +219,6 @@ When overriding `id`, `toString()` and `toJSON()` should also be overridden.
 
 ## Methods
 
-### timeZone.**equals**(_other_: Temporal.TimeZone | object | string) : boolean
-
-**Parameters:**
-
-- `other` (`Temporal.TimeZone` object, object implementing the `Temporal.TimeZone` protocol, or a string time zone identifier): Another time zone to compare.
-
-**Returns:** `true` if `timeZone` and `other` are equivalent, or `false` if not.
-
-Compares two time zones for equivalence.
-Equality is determined by the following algorithm:
-
-- If `timeZone === other`, then the time zones are equivalent.
-- Otherwise, `timeZone.id` is compared to `other` (or `other.id` if `other` is an object).
-  If any of the following conditions are true, then the time zones are equivalent:
-  - Both string identifiers are Zone or Link names in the [IANA Time Zone Database](https://www.iana.org/time-zones), and they resolve to the same Zone name.
-    This resolution is case-insensitive.
-  - Both string identifiers are custom time zone identifiers that are equal according to `===`.
-    This comparison is case-sensitive and does not normalize different Unicode characters.
-  - Both identifiers are numeric offset time zone identifiers like "+05:30", and they represent the same offset.
-- Otherwise, the time zones are not equivalent.
-
-Note that "resolve to the same Zone name" noted above is behavior that can vary between ECMAScript and other consumers of the IANA Time Zone Database.
-ECMAScript implementations generally do not allow identifiers to be equivalent if they represent different <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1 Alpha-2</a> country codes.
-However, non-ECMAScript platforms may merge Zone names across country boundaries.
-See [above](#variation-between-ecmascript-and-other-consumers-of-the-iana-time-zone-database) to learn more about this variation.
-
-Time zones that resolve to different Zones in the IANA Time Zone Database are not equivalent, even if those Zones always use the same offsets.
-Offset time zones and IANA time zones are also never equivalent.
-
-Example usage:
-
-<!-- prettier-ignore-start -->
-```javascript
-kolkata = Temporal.TimeZone.from('Asia/Kolkata');
-kolkata.id; // => "Asia/Kolkata"
-calcutta = Temporal.TimeZone.from('Asia/Calcutta');
-calcutta.id; // => "Asia/Calcutta"
-kolkata.equals(calcutta); // => true
-kolkata.equals('Asia/Calcutta'); // => true
-kolkata.equals('Asia/Colombo'); // => false
-
-// IANA Time Zone Database identifiers are case insensitive
-kolkata.equals('asia/calcutta'); // => true
-
-// Offset time zones are never equivalent to named time zones
-kolkata.equals('+05:30'); // => false
-zeroOffset = Temporal.TimeZone.from('+00:00');
-zeroOffset.equals('UTC'); // false
-
-// For offset time zones, any valid format is accepted
-zeroOffset.equals('+00:00'); // => true
-zeroOffset.equals('+0000'); // => true
-zeroOffset.equals('+00'); // => true
-
-// Custom time zone identifiers are compared case-sensitively
-class Custom1 extends Temporal.TimeZone {
-  constructor() { super('UTC'); }
-  get id() { return 'Moon/Cheese'; }
-}
-class Custom2 extends Temporal.TimeZone {
-  constructor() { super('UTC'); }
-  get id() { return 'Moon/CHEESE'; }
-}
-new Custom1().equals(new Custom1()); // => true
-new Custom1().equals(new Custom2()); // => false
-```
-<!-- prettier-ignore-end -->
-
 ### timeZone.**getOffsetNanosecondsFor**(_instant_: Temporal.Instant | string) : number
 
 **Parameters:**
@@ -446,72 +378,6 @@ See [Resolving ambiguity](./ambiguity.md) for usage examples and a more complete
 Although this method is useful for implementing a custom time zone or custom disambiguation behavior, but otherwise `getInstantFor()` should be used instead, because it is more convenient, because it's compatible with the behavior of other methods and libraries, and because it always returns a single value.
 For example, during "skipped" clock time like the hour after DST starts in the spring, `getPossibleInstantsFor()` returns an empty array while `getInstantFor()` returns a `Temporal.Instant`.
 
-### timeZone.**getNextTransition**(_startingPoint_: Temporal.Instant | string) : Temporal.Instant
-
-**Parameters:**
-
-- `startingPoint` (`Temporal.Instant` or value convertible to one): Time after which to find the next UTC offset transition.
-
-**Returns:** A `Temporal.Instant` object representing the next UTC offset transition in this time zone, or `null` if no transitions later than `startingPoint` could be found.
-
-This method is used to calculate a possible future UTC offset transition after `startingPoint` for this time zone.
-A "transition" is a point in time where the UTC offset of a time zone changes, for example when Daylight Saving Time starts or stops.
-Transitions can also be caused by other political changes like a country permanently changing the UTC offset of its time zone.
-
-The returned `Temporal.Instant` will represent the first nanosecond where the new UTC offset is used, not the last nanosecond where the previous UTC offset is used.
-
-When no more transitions are expected, this method will return `null`.
-Some time zones (e.g., `Etc/GMT+5` or `-05:00`) have no offset transitions and will return `null` for all values of `startingPoint`.
-
-If `instant` is not a `Temporal.Instant` object, then it will be converted to one as if it were passed to `Temporal.Instant.from()`.
-
-When subclassing `Temporal.TimeZone`, this method should be overridden if the time zone changes offsets.
-Single-offset time zones can use the default implementation which returns `null`.
-
-Example usage:
-
-```javascript
-// How long until the next offset change from now, in the current location?
-tz = Temporal.Now.timeZone();
-now = Temporal.Now.instant();
-nextTransition = tz.getNextTransition(now);
-duration = nextTransition.since(now);
-duration.toLocaleString(); // output will vary
-```
-
-### timeZone.**getPreviousTransition**(_startingPoint_: Temporal.Instant | string) : Temporal.Instant
-
-**Parameters:**
-
-- `startingPoint` (`Temporal.Instant` or value convertible to one): Time before which to find the previous UTC offset transition.
-
-**Returns:** A `Temporal.Instant` object representing the previous UTC offset transition in this time zone, or `null` if no transitions earlier than `startingPoint` could be found.
-
-This method is used to calculate a possible past UTC offset transition before `startingPoint` for this time zone.
-A "transition" is a point in time where the UTC offset of a time zone changes, for example when Daylight Saving Time starts or stops.
-Transitions can also be caused by other political changes like a country permanently changing the UTC offset of its time zone.
-
-The returned `Temporal.Instant` will represent the first nanosecond where the new UTC offset is used, not the last nanosecond where the previous UTC offset is used.
-
-When no previous transitions exist, this method will return `null`.
-Some time zones (e.g., `Etc/GMT+5` or `-05:00`) have no offset transitions and will return `null` for all values of `startingPoint`.
-
-If `instant` is not a `Temporal.Instant` object, then it will be converted to one as if it were passed to `Temporal.Instant.from()`.
-
-When subclassing `Temporal.TimeZone`, this method should be overridden if the time zone changes offsets.
-Single-offset time zones can use the default implementation which returns `null`.
-
-Example usage:
-
-```javascript
-// How long until the previous offset change from now, in the current location?
-tz = Temporal.Now.timeZone();
-now = Temporal.Now.instant();
-previousTransition = tz.getPreviousTransition(now);
-duration = now.since(previousTransition);
-duration.toLocaleString(); // output will vary
-```
-
 ### timeZone.**toString**() : string
 
 **Returns:** The string given by `timeZone.id`.