Add more examples of with() to the cookbook

Use cases from #561 suggested by @justingrant

Closes: #561
See also: #240

docs/cookbook.md

@@ -64,6 +64,24 @@ Here is an example using an HTML `<input type="date">` element with any day beyo
 {{cookbook/calendarInput.js}}
 ```
 
+## Converting between types
+
+### Noon on a particular date
+
+An example of combining a calendar date (`Temporal.Date`) and a wall-clock time (`Temporal.Time`) into a `Temporal.DateTime`.
+
+```javascript
+{{cookbook/noonOnDate.mjs}}
+```
+
+### Birthday in 2030
+
+An example of combining a day on the calendar (`Temporal.MonthDay`) and a year into a `Temporal.Date`.
+
+```javascript
+{{cookbook/birthdayIn2030.mjs}}
+```
+
 ## Serialization
 
 ### Zoned instant from instant and time zone
@@ -98,6 +116,17 @@ Sort a list of ISO 8601 date/time strings, for example to place log entries in o
 {{cookbook/sortAbsoluteInstants.mjs}}
 ```
 
+## Rounding
+
+### Round a time down to whole hours
+
+Use the `with()` method of each Temporal type if you want to round or balance the fields.
+Here's an example of rounding a time _down_ to the previously occurring whole hour:
+
+```javascript
+{{cookbook/roundDownToWholeHours.mjs}}
+```
+
 ## Time zone conversion
 
 ### Preserving absolute instant
@@ -353,6 +382,24 @@ Given a `Temporal.Date` instance, return the count of preceding days in its mont
 {{cookbook/countPrecedingWeeklyDaysInMonth.mjs}}
 ```
 
+### Manipulating the day of the month
+
+Here are some examples of taking an existing date, and adjusting the day of the month.
+
+```javascript
+{{cookbook/adjustDayOfMonth.mjs}}
+```
+
+### Same date in another month
+
+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 behaviour you want, you will need to pick the right `disambiguation` option, but the default of `"constrain"` should be correct for most cases.
+
+```javascript
+{{cookbook/adjustMonth.mjs}}
+```
+
 ### Next weekly occurrence
 
 From a `Temporal.Absolute` instance and a local `Temporal.TimeZone`, get a `Temporal.DateTime` representing the next occurrence of a weekly event that is scheduled on a particular weekday and time in a particular time zone. (For example, "weekly on Thursdays at 08:45 California time").

docs/cookbook/adjustDayOfMonth.mjs

@@ -0,0 +1,21 @@
+const date = Temporal.Date.from('2020-04-14');
+
+// Third day of next month:
+
+const thirdOfNextMonth = date.plus({ months: 1 }).with({ day: 3 });
+
+assert.equal(thirdOfNextMonth.toString(), '2020-05-03');
+
+// Last day of this month:
+
+const lastOfThisMonth = date.with({ day: 31 });
+// Note that { disambigution: 'constrain' } is the default, so this
+// works even for months with fewer than 31 days.
+
+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'));
+
+assert.equal(thisMonth18thAt8PM.toString(), '2020-04-18T20:00');

docs/cookbook/adjustMonth.mjs

@@ -0,0 +1,15 @@
+const date = Temporal.Date.from('2020-05-31');
+
+// Same date and time, but in February
+// (and use the last day if the date doesn't exist in February):
+
+const feb = date.with({ month: 2 });
+
+assert.equal(feb.toString(), '2020-02-29');
+
+// Same date and time, but in April
+// (and throw an exception if the date doesn't exist in April):
+
+assert.throws(() => {
+  date.with({ month: 4 }, { disambiguation: 'reject' });
+});

docs/cookbook/all.mjs

@@ -1,4 +1,7 @@
 import './absoluteFromLegacyDate.mjs';
+import './adjustDayOfMonth.mjs';
+import './adjustMonth.mjs';
+import './birthdayIn2030.mjs';
 import './bridgePublicHolidays.mjs';
 import './calculateDailyOccurrence.mjs';
 import './countPrecedingWeeklyDaysInMonth.mjs';
@@ -23,5 +26,7 @@ import './getWeeklyDaysInMonth.mjs';
 import './legacyDateFromDateTime.mjs';
 import './localTimeForFutureEvents.mjs';
 import './nextWeeklyOccurrence.mjs';
+import './noonOnDate.mjs';
 import './plusAndRoundToMonthStart.mjs';
+import './roundDownToWholeHours.mjs';
 import './sortAbsoluteInstants.mjs';

docs/cookbook/birthdayIn2030.mjs

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

docs/cookbook/noonOnDate.mjs

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

docs/cookbook/roundDownToWholeHours.mjs

@@ -0,0 +1,9 @@
+const time = Temporal.Time.from('12:38:28.138818731');
+
+// explicitly:
+let wholeHour = time.with({ minute: 0, second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 });
+assert.equal(wholeHour.toString(), '12:00');
+
+// or, taking advantage of 0 being the default for time fields:
+wholeHour = Temporal.Time.from({ hour: time.hour });
+assert.equal(wholeHour.toString(), '12:00');