Rename conversion methods to toFoo

docs/absolute.md

@@ -206,7 +206,7 @@ Same as `getEpochSeconds()`, but with nanosecond (10<sup>&minus;9</sup> second)
 
 The value returned from this method is suitable to be passed to `new Temporal.Absolute()`.
 
-### absolute.**inTimeZone**(_timeZone_: object | string, _calendar_?: object | string) : Temporal.DateTime
+### absolute.**toDateTime**(_timeZone_: object | string, _calendar_?: object | string) : Temporal.DateTime
 
 **Parameters:**
 - `timeZone` (object or string): A `Temporal.TimeZone` object, or an object implementing the [time zone protocol](./timezone.md#protocol), or a string description of the time zone; either its IANA name or UTC offset.
@@ -227,14 +227,14 @@ Example usage:
 ```js
 // Converting a specific absolute time to a calendar date / wall-clock time
 timestamp = new Temporal.Absolute(1553993100000000000n);
-timestamp.inTimeZone('Europe/Berlin');  // => 2019-03-31T01:45
-timestamp.inTimeZone('UTC');  // => 2019-03-31T00:45
-timestamp.inTimeZone('-08:00');  // => 2019-02-01T16:45
+timestamp.toDateTime('Europe/Berlin');  // => 2019-03-31T01:45
+timestamp.toDateTime('UTC');  // => 2019-03-31T00:45
+timestamp.toDateTime('-08:00');  // => 2019-02-01T16:45
 
 // What time was the Unix epoch (timestamp 0) in Bell Labs (Murray Hill, New Jersey, USA)?
 epoch = new Temporal.Absolute(0n);
 tz = new Temporal.TimeZone('America/New_York');
-epoch.inTimeZone(tz);  // => 1969-12-31T19:00
+epoch.toDateTime(tz);  // => 1969-12-31T19:00
 ```
 
 ### absolute.**plus**(_duration_: object) : Temporal.Absolute
@@ -334,7 +334,7 @@ billion.difference(epoch, { largestUnit: 'days' })  // => P11574DT1H46M40S
 // in years, you can eliminate the ambiguity by choosing your starting
 // point explicitly. For example, using the corresponding UTC date:
 utc = Temporal.TimeZone.from('UTC');
-billion.inTimeZone(utc).difference(epoch.inTimeZone(utc), { largestUnit: 'years' });
+billion.toDateTime(utc).difference(epoch.toDateTime(utc), { largestUnit: 'years' });
   // => P31Y8M8DT1H46M40S
 ```
 

docs/ambiguity.md

@@ -5,7 +5,7 @@
 Converting a [`Temporal.DateTime`](./datetime.md) wall-clock time to a [`Temporal.Absolute`](./absolute.md) is not necessarily a one-to-one conversion.
 Due to DST time changes, there is a possibility that a wall-clock time either does not exist, or has existed twice.
 
-There are two mostly equivalent methods that accomplish this conversion: [`Temporal.DateTime.prototype.inTimeZone`](./datetime.html#inTimeZone) and [`Temporal.TimeZone.prototype.getAbsoluteFor`](./timezone.html#getAbsoluteFor).
+There are two mostly equivalent methods that accomplish this conversion: [`Temporal.DateTime.prototype.toAbsolute`](./datetime.html#toAbsolute) and [`Temporal.TimeZone.prototype.getAbsoluteFor`](./timezone.html#getAbsoluteFor).
 The `disambiguation` option to these methods controls what absolute time to return in the case of ambiguity:
 
 - `'compatible'` (the default): Acts like `'earlier'` for backward transitions and `'later'` for forward transitions.
@@ -46,9 +46,9 @@ tz.getAbsoluteFor(dt, { disambiguation: 'reject' }); // throws
 In this example, the wall-clock time 2:45 doesn't exist, so it is treated as either 1:45 +01:00 or 3:45 +02:00, which can be seen by converting the absolute back to a wall-clock time in the time zone:
 
 ```javascript
-tz.getAbsoluteFor(dt, { disambiguation: 'earlier' }).inTimeZone(tz); // => 2019-03-31T01:45
-tz.getAbsoluteFor(dt, { disambiguation: 'later' }).inTimeZone(tz); // => 2019-03-31T03:45
-tz.getAbsoluteFor(dt, { disambiguation: 'compatible' }).inTimeZone(tz); // => 2019-03-31T03:45
+tz.getAbsoluteFor(dt, { disambiguation: 'earlier' }).toDateTime(tz); // => 2019-03-31T01:45
+tz.getAbsoluteFor(dt, { disambiguation: 'later' }).toDateTime(tz); // => 2019-03-31T03:45
+tz.getAbsoluteFor(dt, { disambiguation: 'compatible' }).toDateTime(tz); // => 2019-03-31T03:45
 ```
 
 Using [`Temporal.TimeZone.prototype.getPossibleAbsolutesFor`](./timezone.html#getPossibleAbsolutesFor) we can show that the wall-clock time doesn't exist:
@@ -66,10 +66,10 @@ In `'compatible'` mode, the same time is returned as `'earlier'` mode, which mat
 ```javascript
 tz = new Temporal.TimeZone('America/Sao_Paulo');
 dt = new Temporal.DateTime(2019, 2, 16, 23, 45);
-dt.inTimeZone(tz, { disambiguation: 'earlier' }); // => 2019-02-17T01:45Z
-dt.inTimeZone(tz, { disambiguation: 'later' }); // => 2019-02-17T02:45Z
-dt.inTimeZone(tz, { disambiguation: 'compatible' }); // => 2019-02-17T01:45Z
-dt.inTimeZone(tz, { disambiguation: 'reject' }); // throws
+dt.toAbsolute(tz, { disambiguation: 'earlier' }); // => 2019-02-17T01:45Z
+dt.toAbsolute(tz, { disambiguation: 'later' }); // => 2019-02-17T02:45Z
+dt.toAbsolute(tz, { disambiguation: 'compatible' }); // => 2019-02-17T01:45Z
+dt.toAbsolute(tz, { disambiguation: 'reject' }); // throws
 ```
 
 In this example, the wall-clock time 23:45 exists twice, which can also be verified with `getPossibleAbsolutesFor`:

docs/cookbook.md

@@ -132,7 +132,7 @@ Here's an example of rounding a time _down_ to the previously occurring whole ho
 ### Preserving local time
 
 Map a zoneless date and time of day into a `Temporal.Absolute` instance at which the local date and time of day in a specified time zone matches it.
-This is easily done with `dateTime.inTimeZone()`, but here is an example of implementing different disambiguation behaviors than the `'compatible'`, `'earlier'`, `'later'`, and `'reject'` ones built in to Temporal.
+This is easily done with `dateTime.toAbsolute()`, but here is an example of implementing different disambiguation behaviors than the `'compatible'`, `'earlier'`, `'later'`, and `'reject'` ones built in to Temporal.
 
 ```javascript
 {{cookbook/getInstantWithLocalTimeInZone.mjs}}

docs/cookbook/adjustDayOfMonth.mjs

@@ -14,6 +14,6 @@ assert.equal(lastOfThisMonth.toString(), '2020-04-30');
 
 // On the 18th of this month at 8 PM:
 
-const thisMonth18thAt8PM = date.with({ day: 18 }).withTime(Temporal.Time.from('20:00'));
+const thisMonth18thAt8PM = date.with({ day: 18 }).toDateTime(Temporal.Time.from('20:00'));
 
 assert.equal(thisMonth18thAt8PM.toString(), '2020-04-18T20:00');

docs/cookbook/birthdayIn2030.mjs

@@ -1,6 +1,6 @@
 const birthday = Temporal.MonthDay.from('12-15');
 
-const birthdayIn2030 = birthday.withYear(2030);
+const birthdayIn2030 = birthday.toDate(2030);
 birthdayIn2030.dayOfWeek; // => 7
 
 assert(birthdayIn2030 instanceof Temporal.Date);

docs/cookbook/bridgePublicHolidays.mjs

@@ -8,7 +8,7 @@
  * @returns {Temporal.Date[]} List of dates to be taken off work
  */
 function bridgePublicHolidays(holiday, year) {
-  const date = holiday.withYear(year);
+  const date = holiday.toDate(year);
   switch (date.dayOfWeek) {
     case 1: // Mon
     case 3: // Wed

docs/cookbook/calculateDailyOccurrence.mjs

@@ -9,7 +9,7 @@
  */
 function* calculateDailyOccurrence(startDate, time, timeZone) {
   for (let date = startDate; ; date = date.plus({ days: 1 })) {
-    yield date.withTime(time).inTimeZone(timeZone);
+    yield date.toDateTime(time).toAbsolute(timeZone);
   }
 }
 

docs/cookbook/getBusinessOpenStateText.mjs

@@ -24,12 +24,12 @@ function getBusinessOpenStateText(now, timeZone, businessHours, soonWindow) {
     return Temporal.Absolute.compare(abs, start) >= 0 && Temporal.Absolute.compare(abs, end) < 0;
   }
 
-  const dateTime = now.inTimeZone(timeZone);
+  const dateTime = now.toDateTime(timeZone);
   const weekday = dateTime.dayOfWeek % 7; // convert to 0-based, for array indexing
 
   // Because of times wrapping around at midnight, we may need to consider
   // yesterday's and tomorrow's hours as well
-  const today = dateTime.getDate();
+  const today = dateTime.toDate();
   const yesterday = today.minus({ days: 1 });
   const tomorrow = today.plus({ days: 1 });
 
@@ -42,8 +42,8 @@ function getBusinessOpenStateText(now, timeZone, businessHours, soonWindow) {
     const { open, close } = yesterdayHours;
     if (Temporal.Time.compare(close, open) < 0) {
       businessHoursOverlappingToday.push({
-        open: yesterday.withTime(open).inTimeZone(timeZone),
-        close: today.withTime(close).inTimeZone(timeZone)
+        open: yesterday.toDateTime(open).toAbsolute(timeZone),
+        close: today.toDateTime(close).toAbsolute(timeZone)
       });
     }
   }
@@ -52,8 +52,8 @@ function getBusinessOpenStateText(now, timeZone, businessHours, soonWindow) {
     const { open, close } = todayHours;
     const todayOrTomorrow = Temporal.Time.compare(close, open) >= 0 ? today : tomorrow;
     businessHoursOverlappingToday.push({
-      open: today.withTime(open).inTimeZone(timeZone),
-      close: todayOrTomorrow.withTime(close).inTimeZone(timeZone)
+      open: today.toDateTime(open).toAbsolute(timeZone),
+      close: todayOrTomorrow.toDateTime(close).toAbsolute(timeZone)
     });
   }
 

docs/cookbook/getFirstTuesdayOfMonth.mjs

@@ -6,7 +6,7 @@
  */
 function getFirstTuesday(queriedMonth) {
   // We first need to convert to a date
-  const firstOfMonth = queriedMonth.withDay(1);
+  const firstOfMonth = queriedMonth.toDate(1);
 
   // We have Monday = 1, Sunday = 7, and we want to add a positive number
   // smaller than 7 to get to the first Tuesday.
@@ -24,12 +24,12 @@ assert.equal(firstTuesdayOfMonth.toString(), '2020-02-04');
 assert.equal(firstTuesdayOfMonth.dayOfWeek, 2);
 
 // Similarly, to get the second Tuesday:
-const secondWeek = myMonth.withDay(8);
+const secondWeek = myMonth.toDate(8);
 const secondTuesday = secondWeek.plus({ days: [1, 0, 6, 5, 4, 3, 2][secondWeek.dayOfWeek - 1] });
 assert.equal(secondTuesday.day, firstTuesdayOfMonth.day + 7);
 
 // And the last Tuesday:
-const lastOfMonth = myMonth.withDay(myMonth.daysInMonth);
+const lastOfMonth = myMonth.toDate(myMonth.daysInMonth);
 const lastTuesday = lastOfMonth.minus({ days: [6, 0, 1, 2, 3, 4, 5][lastOfMonth.dayOfWeek - 1] });
 assert.equal(lastTuesday.toString(), '2020-02-25');
 assert.equal(lastTuesday.dayOfWeek, 2);

docs/cookbook/getInstantWithLocalTimeInZone.mjs

@@ -1,7 +1,7 @@
 /**
  * Get an absolute time corresponding with a calendar date / wall-clock time in
  * a particular time zone, the same as Temporal.TimeZone.getAbsoluteFor() or
- * Temporal.DateTime.inTimeZone(), but with more disambiguation options.
+ * Temporal.DateTime.toAbsolute(), but with more disambiguation options.
  *
  * As well as the default Temporal disambiguation options 'compatible',
  * 'earlier', 'later', and 'reject', there are additional options possible:
@@ -34,13 +34,13 @@ function getInstantWithLocalTimeInZone(dateTime, timeZone, disambiguation = 'ear
   switch (disambiguation) {
     case 'clipEarlier':
       if (possible.length === 0) {
-        const before = dateTime.inTimeZone(timeZone, { disambiguation: 'earlier' });
+        const before = dateTime.toAbsolute(timeZone, { disambiguation: 'earlier' });
         return timeZone.getNextTransition(before).minus({ nanoseconds: 1 });
       }
       return possible[0];
     case 'clipLater':
       if (possible.length === 0) {
-        const before = dateTime.inTimeZone(timeZone, { disambiguation: 'earlier' });
+        const before = dateTime.toAbsolute(timeZone, { disambiguation: 'earlier' });
         return timeZone.getNextTransition(before);
       }
       return possible[possible.length - 1];

docs/cookbook/getLocalizedArrival.mjs

@@ -11,7 +11,7 @@
 function getLocalizedArrival(parseableDeparture, flightTime, destinationTimeZone) {
   const departure = Temporal.Absolute.from(parseableDeparture);
   const arrival = departure.plus(flightTime);
-  return arrival.inTimeZone(destinationTimeZone);
+  return arrival.toDateTime(destinationTimeZone);
 }
 
 const arrival = getLocalizedArrival(

docs/cookbook/getParseableZonedStringWithLocalTimeInOtherZone.mjs

@@ -22,7 +22,7 @@ function getParseableZonedStringWithLocalTimeInOtherZone(
   targetTimeZone,
   sourceDisambiguationPolicy = 'reject'
 ) {
-  let instant = sourceDateTime.inTimeZone(sourceTimeZone, { disambiguation: sourceDisambiguationPolicy });
+  let instant = sourceDateTime.toAbsolute(sourceTimeZone, { disambiguation: sourceDisambiguationPolicy });
   return instant.toString(targetTimeZone);
 }
 

docs/cookbook/getWeeklyDaysInMonth.mjs

@@ -7,7 +7,7 @@
  * @returns {Temporal.Date[]} Array of dates
  */
 function getWeeklyDaysInMonth(yearMonth, dayNumberOfTheWeek) {
-  const firstOfMonth = yearMonth.withDay(1);
+  const firstOfMonth = yearMonth.toDate(1);
   let nextWeekday = firstOfMonth.plus({ days: (7 + dayNumberOfTheWeek - firstOfMonth.dayOfWeek) % 7 });
   const result = [];
   while (nextWeekday.month === yearMonth.month) {

docs/cookbook/localTimeForFutureEvents.mjs

@@ -30,7 +30,7 @@ const tc39meetings = [
 // need to join:
 const localTimeZone = Temporal.TimeZone.from('Asia/Tokyo');
 const localTimes = tc39meetings.map(({ dateTime, timeZone }) => {
-  return Temporal.DateTime.from(dateTime).inTimeZone(timeZone, { disambiguation: 'reject' }).inTimeZone(localTimeZone);
+  return Temporal.DateTime.from(dateTime).toAbsolute(timeZone, { disambiguation: 'reject' }).toDateTime(localTimeZone);
 });
 
 assert.deepEqual(

docs/cookbook/meetingPlanner.js

@@ -9,10 +9,10 @@ const timeZones = [
 ];
 
 // Start the table at midnight local time
-const calendarNow = now.inTimeZone(here);
+const calendarNow = now.toDateTime(here);
 const startTime = calendarNow
   .with(Temporal.Time.from('00:00')) // midnight
-  .inTimeZone(here);
+  .toAbsolute(here);
 
 // Build the table
 const table = document.getElementById('meeting-planner');
@@ -26,7 +26,7 @@ timeZones.forEach(({ name, tz }) => {
   for (let hours = 0; hours < 24; hours++) {
     const cell = document.createElement('td');
 
-    const dt = startTime.plus({ hours }).inTimeZone(tz);
+    const dt = startTime.plus({ hours }).toDateTime(tz);
     cell.className = `time-${dt.hour}`;
 
     // Highlight the current hour in each row

docs/cookbook/nextWeeklyOccurrence.mjs

@@ -10,16 +10,16 @@
  * @returns {Temporal.DateTime} Local date and time of next occurrence
  */
 function nextWeeklyOccurrence(now, localTimeZone, weekday, eventTime, eventTimeZone) {
-  const dateTime = now.inTimeZone(eventTimeZone);
-  const nextDate = dateTime.getDate().plus({ days: (weekday + 7 - dateTime.dayOfWeek) % 7 });
-  let nextOccurrence = nextDate.withTime(eventTime);
+  const dateTime = now.toDateTime(eventTimeZone);
+  const nextDate = dateTime.toDate().plus({ days: (weekday + 7 - dateTime.dayOfWeek) % 7 });
+  let nextOccurrence = nextDate.toDateTime(eventTime);
 
   // Handle the case where the event is today but already happened
   if (Temporal.DateTime.compare(dateTime, nextOccurrence) > 0) {
     nextOccurrence = nextOccurrence.plus({ days: 7 });
   }
 
-  return nextOccurrence.inTimeZone(eventTimeZone).inTimeZone(localTimeZone);
+  return nextOccurrence.toAbsolute(eventTimeZone).toDateTime(localTimeZone);
 }
 
 // "Weekly on Thursdays at 08:45 California time":

docs/cookbook/noonOnDate.mjs

@@ -1,6 +1,6 @@
 const date = Temporal.Date.from('2020-05-14');
 
-const noonOnDate = date.withTime(Temporal.Time.from({ hour: 12 }));
+const noonOnDate = date.toDateTime(Temporal.Time.from({ hour: 12 }));
 
 assert(noonOnDate instanceof Temporal.DateTime);
 assert.equal(noonOnDate.toString(), '2020-05-14T12:00');

docs/cookbook/storageTank.js

@@ -4,7 +4,7 @@
 
 // Show data starting from the most recent midnight in the tank's location (Stockholm)
 const tankTimeZone = Temporal.TimeZone.from('Europe/Stockholm');
-const tankMidnight = Temporal.now.dateTime(tankTimeZone).with(Temporal.Time.from('00:00')).inTimeZone(tankTimeZone);
+const tankMidnight = Temporal.now.dateTime(tankTimeZone).with(Temporal.Time.from('00:00')).toAbsolute(tankTimeZone);
 const atOrAfterMidnight = (x) => Temporal.Absolute.compare(x, tankMidnight) >= 0;
 const dataStartIndex = tankDataX.findIndex(atOrAfterMidnight);
 const labelFormatter = new Intl.DateTimeFormat(undefined, {

docs/date.md

@@ -10,7 +10,7 @@ A `Temporal.Date` represents a calendar date.
 For example, it could be used to represent an event on a calendar which happens during the whole day no matter which time zone it's happening in.
 
 `Temporal.Date` refers to the whole of a specific day; if you need to refer to a specific time on that day, use `Temporal.DateTime`.
-A `Temporal.Date` can be converted into a `Temporal.DateTime` by combining it with a `Temporal.Time` using the `withTime()` method.
+A `Temporal.Date` can be converted into a `Temporal.DateTime` by combining it with a `Temporal.Time` using the `toDateTime()` method.
 
 `Temporal.YearMonth` and `Temporal.MonthDay` carry less information than `Temporal.Date` and should be used when complete information is not required.
 
@@ -32,7 +32,7 @@ Otherwise, `Temporal.Date.from()`, which accepts more kinds of input, allows inp
 All values are given as reckoned in the [ISO 8601 calendar](https://en.wikipedia.org/wiki/ISO_8601#Dates).
 Together, `isoYear`, `isoMonth`, and `isoDay` must represent a valid date in that calendar, even if you are passing a different calendar as the `calendar` parameter.
 
-The range of allowed values for this type is exactly enough that calling [`getDate()`](./datetime.html#getDate) on any valid `Temporal.DateTime` will succeed.
+The range of allowed values for this type is exactly enough that calling [`toDate()`](./datetime.html#toDate) on any valid `Temporal.DateTime` will succeed.
 If `isoYear`, `isoMonth`, and `isoDay` form a date outside of this range, then this function will throw a `RangeError`.
 
 > **NOTE**: The `isoMonth` argument ranges from 1 to 12, which is different from legacy `Date` where months are represented by zero-based indices (0 to 11).
@@ -404,7 +404,7 @@ other.difference(date, { largestUnit: 'years' })  // => throws RangeError
 // point in time from which you want to reckon the difference. For
 // example, using midnight:
 midnight = Temporal.Time.from('00:00');
-date.withTime(midnight).difference(other.withTime(midnight), { largestUnit: 'hours' })
+date.toDateTime(midnight).difference(other.toDateTime(midnight), { largestUnit: 'hours' })
   // => PT109032H
 ```
 
@@ -507,7 +507,7 @@ This method overrides `Object.prototype.valueOf()` and always throws an exceptio
 This is because it's not possible to compare `Temporal.Date` objects with the relational operators `<`, `<=`, `>`, or `>=`.
 Use `Temporal.Date.compare()` for this, or `date.equals()` for equality.
 
-### date.**withTime**(_time_: Temporal.Time) : Temporal.DateTime
+### date.**toDateTime**(_time_: Temporal.Time) : Temporal.DateTime
 
 **Parameters:**
 - `time` (`Temporal.Time`): A time of day on `date`.
@@ -517,31 +517,31 @@ Use `Temporal.Date.compare()` for this, or `date.equals()` for equality.
 This method can be used to convert `Temporal.Date` into a `Temporal.DateTime`, by supplying the time of day to use.
 The converted object carries a copy of all the relevant fields of `date` and `time`.
 
-This is exactly equivalent to [`time.withDate(date)`](./time.html#withDate).
+This is exactly equivalent to [`time.toDateTime(date)`](./time.html#toDateTime).
 
 Usage example:
 ```javascript
 date = Temporal.Date.from('2006-08-24');
 time = Temporal.Time.from('15:23:30.003');
-date.withTime(time)  // => 2006-08-24T15:23:30.003
+date.toDateTime(time)  // => 2006-08-24T15:23:30.003
 ```
 
-### date.**getYearMonth**() : Temporal.YearMonth
+### date.**toYearMonth**() : Temporal.YearMonth
 
 **Returns:** a `Temporal.YearMonth` object that is the same as the year and month of `date`.
 
-### date.**getMonthDay**() : Temporal.MonthDay
+### date.**toMonthDay**() : Temporal.MonthDay
 
 **Returns:** a `Temporal.MonthDay` object that is the same as the month and day of `date`.
 
 The above two methods can be used to convert `Temporal.Date` into a `Temporal.YearMonth` or `Temporal.MonthDay` respectively.
-The converted object carries a copy of all the relevant fields of `date` (for example, in `getYearMonth()`, the `year` and `month` properties are copied.)
+The converted object carries a copy of all the relevant fields of `date` (for example, in `toYearMonth()`, the `year` and `month` properties are copied.)
 
 Usage example:
 ```javascript
 date = Temporal.Date.from('2006-08-24');
-date.getYearMonth()  // => 2006-08
-date.getMonthDay()  // => 08-24
+date.toYearMonth()  // => 2006-08
+date.toMonthDay()  // => 08-24
 ```
 
 ### date.**getFields**() : { year: number, month: number, day: number, calendar: object, [propName: string]: unknown }