Twhitney chrono (#3641)

TylerMSFT · TylerMSFT · web-flow · commit 9d515ffdb7a1 · 2021-06-30T16:35:48.000-07:00
* first draft: year_month_day_last

* fixes

* fix link

* new class: year-month-weekday

* fix link, add index member

* add local_days, sys_days

* acrolinx

* added year_month_weekday_last class

* update description

* fix typos

* update code snippets and add examples for / operator

* fix code snippets

* add cross-linking and update modify dates

* fix metadata

* tech review

* remove qualifier

* resolve conflict

* formatting updates and update f1 keywords

Co-authored-by: TylerMSFT &lt;Tyler.Whitney@microsoft.com&gt;
diff --git a/docs/standard-library/chrono-operators.md b/docs/standard-library/chrono-operators.md
@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: &lt;chrono&gt; operators"
 title: "&lt;chrono&gt; operators"
-ms.date: "6/24/2021"
+ms.date: "6/30/2021"
 f1_keywords: ["chrono/std::operator modulo", "chrono/std::operator+", "chrono/std::chrono::day::operator+", "chrono/std::chrono::duration::operator+", "chrono/std::chrono::month::operator+", "chrono/std::chrono::time_point::operator+", "chrono/std::chrono::weekday::operator+", "chrono/std::chrono::year_month::operator+", "chrono/std::chrono::year::operator+", "chrono/std::chrono::year_month_day::operator+", "chrono/std::chrono::year_month_day_last::operator+", "chrono/std::chrono::year_month_weekday::operator+", "chrono/std::chrono::year_month_weekday_last::operator+", "chrono/std::operator!=", "chrono/std::operator*", "chrono/std::operator/", "chrono/std::operator-", "chrono/std::operator<", "chrono/std::operator<=", "chrono/std::operator<", "chrono/std::operator==", "chrono/std::operator>>", "chrono/std::operator<=>", "chrono/std::chrono::day::operator<=>", "chrono/std::chrono::month::operator<=>", "chrono/std::chrono::year::operator<=>", "chrono/std::chrono::year_month::operator<=>", "chrono/std::chrono::time_point::operator<=>", "chrono/std::chrono::duration::operator<=>", "chrono/std::chrono::month_day_last::operator<=>", "chrono/std::chrono::year_month_day_last::operator<=>", "chrono/std::operator==", "chrono/std::chrono::year::operator<==>", "chrono/std::chrono::day::operator==", "chrono/std::chrono::duration::operator==", "chrono/std::chrono::month::operator==", "chrono/std::chrono::month_day::operator==", "chrono/std::chrono::month_day_last::operator==", "chrono/std::chrono::month_weekday::operator==", "chrono/std::chrono::month_weekday_last::operator==", "chrono/std::chrono::time_point::operator==", "chrono/std::chrono::weekday::operator==", "chrono/std::chrono::year_month::operator==", "chrono/std::chrono::year::operator==", "chrono/std::chrono::year_month_day::operator==", "chrono/std::chrono::year_month_day_last::operator==", "chrono/std::chrono::year_month_weekday_last::operator==", "chrono/std::chrono::year_month_weekday::operator==", "chrono/std::chrono::month_weekday_last::operator==", "chrono/std::chrono::weekday::operator==", "chrono/std::chrono::weekday_last::operator==", "chrono/std::chrono::year_month_weekday_indexed::operator==", "chrono/std::chrono::year_month_weekday_last::operator==", "chrono/std::chrono::year::operator==", "chrono/std::chrono::year_month::operator==",  "chrono/std::chrono::year_month_day::operator==", "chrono/std::chrono::year_month_day_last::operator==", "chrono/std::operator-", "chrono/std::chrono::day::operator-", "chrono/std::chrono::duration::operator-", "chrono/std::chrono::month::operator-", "chrono/std::chrono::time_point::operator-", "chrono/std::chrono::weekday::operator-", "chrono/std::chrono::year_month::operator-", "chrono/std::chrono::year::operator-", "chrono/std::chrono::year_month_day::operator-", "chrono/std::chrono::year_month_day_last::operator-", "chrono/std::chrono::year_month_weekday::operator-", "chrono/std::chrono::year_month_weekday_last::operator-", "chrono/std::chrono::day::operator<<", "chrono/std::chrono::hh_mm_ss::operator<<", "chrono/std::chrono::month_day::operator<<", "chrono/std::chrono::month_day_last::operator<<", "chrono/std::chrono::month_weekday::operator<<", "chrono/std::chrono::month_weekday_last::operator<<", "chrono/std::chrono::weekday::operator<<", "chrono/std::chrono::weekday_indexed::operator<<", "chrono/std::chrono::weekday_last::operator<<", "chrono/std::chrono::year::operator<<", "chrono/std::chrono::year_month_day::operator<<", "chrono/std::chrono::year_month_day_last::operator<<", "chrono/std::chrono::year_month_weekday::operator<<"]
 ---
 # `<chrono>` operators
@@ -80,6 +80,7 @@ constexpr year_month_day_last operator+(const months& dm, const year_month_day_l
 
 12)
 constexpr year_month_day_last operator+(const year_month_day_last& ymdl, const years& dy) noexcept; // C++ 20
+constexpr year_month_day_last operator+(const years& dy, const year_month_day_last& ymdl) noexcept; // C++ 20
 
 13)
 constexpr year_month_weekday operator+(const year_month_weekday& ymwd, const months& dm) noexcept; // C++ 20
@@ -173,8 +174,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 03
 Feb
@@ -363,7 +362,7 @@ int main()
 
     // year_month_day_last
     year_month_day_last ymdl = June / last / 2021;
-    std::cout << ymdl + years{1} + months{1} << '\n'; // 2022/Jul/last
+    std::cout << ymdl - years{1} - months{1} << '\n'; // 2022/Jul/last
 
     // year_month_weekday
     year_month_weekday ymw{ year(1997) / January / Wednesday[1] };
@@ -387,7 +386,7 @@ Dec
 2020
 2021/Apr
 2019/Jun
-2022/Jul/last
+2020/May/last
 1996/Dec/Wed[1]
 1996/Jan/Wed[1]
 1996/Dec/Wed[last]
@@ -396,9 +395,7 @@ Dec
 
 ## <a name="op_unary_negate"></a> Unary `operator-`
 
-Negates the following types:
-
-- [`duration`](duration-class.md)
+Negates a [`duration`](duration-class.md).
 
 ```cpp
 constexpr common_type_t<duration> operator-() const;
@@ -425,15 +422,13 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 -120ms
 ```
 
 ## <a name="op_neq"></a> `operator!=`
 
-Inequality operator for [`duration`](../standard-library/duration-class.md) or [`time_point`](../standard-library/time-point-class.md) objects.
+Inequality operator for [`duration`](duration-class.md) or [`time_point`](time-point-class.md) objects.
 
 ```cpp
 template <class Rep1, class Period1, class Rep2, class Period2>
@@ -555,6 +550,7 @@ Each function returns `!(Right < Left)`.
 ## <a name="op_eq_eq"></a> `operator==`
 
 Determines whether:
+
 1\) [`duration`](duration-class.md) objects represent time intervals that have the same length.\
 2\) [`time_point`](time-point-class.md) objects represent the same point in time.\
 3\) [`day`](day-class.md) objects represent the same day.\
@@ -568,9 +564,10 @@ Determines whether:
 11\) [`weekday_indexed`](weekdayindexed-class.md) represent the same weekday index.\
 12\) [`year`](year-class.md) represent the same year.\
 13\) [`year_month`](year-month-class.md) represent the same year and month.\
-14\) [`year_month_day`](year-month-day-class.md) represent the same year, month, and day.
-15\) [`year_month_day_last`](year-month-day-last-class.md) represent the same last day of the year and month.
-16\) [`year_month_weekday`](year-month-weekday-class.md) represent the same weekday, year, and month.
+14\) [`year_month_day`](year-month-day-class.md) represent the same year, month, and day.\
+15\) [`year_month_day_last`](year-month-day-last-class.md) represent the same last day of the year and month.\
+16\) [`year_month_weekday`](year-month-weekday-class.md) represent the same weekday, year, and month.\
+17\) [`year_month_weekday_last`](year-month-weekday-last-class.md) represent the same last weekday of the month, year, and month.
 
 ```cpp
 // 1) duration<Rep, Period>
@@ -626,6 +623,9 @@ constexpr bool operator==(const year_month_day_last& Left, const year_month_day_
 
 // 16) year_month_weekday
 constexpr bool operator==(const year_month_weekday& Left, const year_month_weekday& Right) noexcept; // C++ 20
+
+// 17)  year_month_weekday_last
+constexpr bool operator==(const year_month_weekday_last& Left, const year_month_weekday_last& Right) noexcept; // C++ 20
 ```
 
 ### Parameters
@@ -640,7 +640,7 @@ The right object to compare.
 
 1\) Returns **`true`** if *`Left`* and *`Right`* represent time intervals that have the same length. Otherwise, the function returns **`false`**.\
 2\) Returns **`true`** if *`Left`* and *`Right`* represent the same point in time. Otherwise, returns **`false`**.\
-3-15\) Returns **`true`** if *`Left`* and *`Right`* have the same value. Otherwise, returns **`false`**.
+3-17\) Returns **`true`** if *`Left`* and *`Right`* have the same value. Otherwise, returns **`false`**.
 
 ## <a name="op_gt"></a> `operator>`
 
@@ -715,12 +715,18 @@ The spaceship operator, in conjunction with `operator==`, synthesizes operators
 ```cpp
 // 1)
 constexpr bool operator<=>(const day& Left, const day& Right) noexcept; // C++ 20
+
 constexpr std::strong_ordering operator<=>(const month& Left, const month& Right) noexcept; // C++ 20
+
 constexpr strong_ordering operator<=>(const month_day& Left, const month_day& Right) noexcept; // C++ 20
+
 constexpr std::strong_ordering operator<=>(const year& Left, const year& Right ) noexcept; // C++ 20
+
 constexpr strong_ordering operator<=>(const year_month& Left, const year_month& Right) noexcept; // C++ 20
+
 template<class Clock, class Duration1, three_­way_­comparable_­with<Duration1> Duration2>
     constexpr auto operator<=>(const time_point<Clock, Duration1>& Left, const time_point<Clock, Duration2>& Right); // C++ 20
+
 template<class Rep1, class Period1, class Rep2, class Period2>
   requires three_­way_­comparable<typename CT::rep>
     constexpr auto operator<=>(const duration<Rep1, Period1>& Left, const duration<Rep2, Period2>& Right);
@@ -739,15 +745,15 @@ The [`day`](day-class.md), [`duration`](duration-class.md), [`month`](month-clas
 
 ### Return value
 
-1\)
+1\)\
 `0` if `Left == Right`\
 `< 0` if `Left < Right`\
 `> 0` if `Left > Right`
 
-2\)
+2\)\
 Equivalent to: `Left.month() <=> Right.month()`
 
-3\)
+3\)\
 Equivalent to:
 
 ```cpp
@@ -788,8 +794,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 d1 < d2
 true true false 
@@ -1374,8 +1378,8 @@ int main()
     month_day_last mdl{ January / last }; // Jan/last
     month_weekday mw{ 11 / Monday[1] }; // Nov/Mon[1]
     month_weekday_last mwl{ January / Monday[last] }; // Jan/Mon[last]
-    weekday wd{ Monday }; // Monday
-    weekday_indexed wdi{ Monday, 1}; // Monday[1]
+    weekday wd{ Monday }; // Mon
+    weekday_indexed wdi{ Monday, 1 }; // Mon[1]
     year_month ym{ 2021y / April }; // 2021/Apr
     year_month_day ymd{ January / 1d / 2021y }; // 2021-01-01
     year_month_day ymd2{ 2021y / 5 / 7 }; // 2021-05-07
@@ -1385,12 +1389,13 @@ int main()
     int yearValue{ 2021 / 4 / 4 }; // 126
 
     std::cout << m << '\n' << md << '\n' << md2 << '\n' << mdl << '\n' << mw
-              << '\n' << mwl << '\n' << wd << '\n' << wdi << '\n'         
-              << ym << '\n' << ymd2 << '\n' << ymdl
-              << '\n' << ymw << '\n' << ymwl << '\n' << yearValue;
+        << '\n' << mwl << '\n' << wd << '\n' << wdi << '\n'
+        << ym << '\n' << ymd << '\n' << ymd2 << '\n' << ymdl
+        << '\n' << ymw << '\n' << ymwl << '\n' << yearValue;
 
     return 0;
 }
+```
 
 ```output
 Jul
@@ -1402,6 +1407,7 @@ Jan/Mon[last]
 Mon
 Mon[1]
 2021/Apr
+2021-01-01
 2021-05-07
 1975/Apr/last
 1997/Jan/Wed[1]
diff --git a/docs/standard-library/day-class.md b/docs/standard-library/day-class.md
@@ -139,8 +139,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 01 02
 02 02
@@ -183,8 +181,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 05 04
 04 04
@@ -260,7 +256,6 @@ int main()
 }
 ```
 
-Output:
 ```Output
 14
 ```
diff --git a/docs/standard-library/weekday-class.md b/docs/standard-library/weekday-class.md
@@ -299,8 +299,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 2021-01-11
 2021-01-26
diff --git a/docs/standard-library/weekdayindexed-class.md b/docs/standard-library/weekdayindexed-class.md
@@ -120,8 +120,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 Mon[1]
 ```
diff --git a/docs/standard-library/year-class.md b/docs/standard-library/year-class.md
@@ -175,8 +175,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 -0001
 ```
@@ -255,8 +253,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 -1977
 ```
diff --git a/docs/standard-library/year-month-day-class.md b/docs/standard-library/year-month-day-class.md
@@ -2,17 +2,18 @@
 description: "Learn more about: year_month_day class"
 title: "year_month_day class"
 ms.date: "06/28/2021"
-f1_keywords: ["chrono/std::chrono::year_month_day", "chrono/std::chrono::year::operator+=", "chrono/std::chrono::year::operator-=", "chrono/std::chrono::year::ok"]
+f1_keywords: ["chrono/std::chrono::year_month_day", "chrono/std::chrono::year::operator+=", "chrono/std::chrono::year::operator-=", "chrono/std::chrono::year::sysdays", "chrono/std::chrono::year::localdays", "chrono/std::chrono::year::ok"]
 helpviewer_keywords: ["std::chrono [C++], year_month_day"]
 ---
+
 # `year_month_day` class  
 
 Represents a month, year, and day.
 
 ## Syntax
 
 ```cpp
-class year_month_day; // C++20
+class year_month_day; // C++ 20
 ```
 
 ## Members
@@ -42,7 +43,7 @@ class year_month_day; // C++20
 
 ## Requirements
 
-**Header:** `<chrono>` (since C++20)
+**Header:** `<chrono>` (since C++ 20)
 
 **Namespace:** `std::chrono`
 
diff --git a/docs/standard-library/year-month-day-last-class.md b/docs/standard-library/year-month-day-last-class.md
@@ -2,7 +2,7 @@
 description: "Learn more about: year_month_day_last class"
 title: "year_month_day_last class"
 ms.date: "06/28/2021"
-f1_keywords: ["chrono/std::chrono::year_month_day_last", "chrono/std::chrono::year_month_day_last::operator+=", "chrono/std::chrono::year_month_day_last::operator-=", "chrono/std::chrono::year_month_day_last::day", "chrono/std::chrono::year_month_day_last::year", "chrono/std::chrono::year_month_day_last::ok"]
+f1_keywords: ["chrono/std::chrono::year_month_day_last", "chrono/std::chrono::year_month_day_last::operator+=", "chrono/std::chrono::year_month_day_last::operator-=", "chrono/std::chrono::year_month_day_last::sysdays", "chrono/std::chrono::year_month_day_last::localdays", "chrono/std::chrono::year_month_day_last::day", "chrono/std::chrono::year_month_day_last::year", "chrono/std::chrono::year_month_day_last::ok"]
 helpviewer_keywords: ["std::chrono [C++], year_month_day_last"]
 ---
 # `year_month_day_last` class  
@@ -157,11 +157,15 @@ The [`month`](month-class.md) value.
 
 Gets the `month_day_last` value stored in this `year_month_day_last`.
 
+```cpp
+constexpr month_day_last month_day_last() const noexcept;
+```
+
 ### Return value
 
 The [`month_day_last`](month-day-last-class.md) value stored in this `year_month_day_last`.
 
-## <a name="sys_days"></a> `month_day_last::operator sys_days`
+## <a name="sys_days"></a> `operator sys_days`
 
 Get the month, day, and year in this `year_month_day_last` as a count of days from the epoch for the system clock.
 
diff --git a/docs/standard-library/year-month-weekday-class.md b/docs/standard-library/year-month-weekday-class.md
@@ -1,8 +1,8 @@
 ---
 description: "Learn more about: year_month_weekday class"
 title: "year_month_weekday class"
-ms.date: "06/28/2021"
-f1_keywords: ["chrono/std::chrono::year_month_weekday", "chrono/std::chrono::year_month_weekday::weekday", "chrono/std::chrono::year_month_weekday::month", "chrono/std::chrono::year_month_weekday::index", "chrono/std::chrono::year_month_weekday::year", "chrono/std::chrono::year_month_weekday::weekday_indexed", "chrono/std::chrono::year_month_weekday::operatorsys_days", "chrono/std::chrono::year_month_weekday::local_days", "chrono/std::chrono::year_month_weekday::ok", "chrono/std::chrono::year_month_weekday::operator+=", "chrono/std::chrono::year_month_weekday::operator-="]
+ms.date: "06/30/2021"
+f1_keywords: ["chrono/std::chrono::year_month_weekday", "chrono/std::chrono::year_month_weekday::weekday", "chrono/std::chrono::year_month_weekday::month", "chrono/std::chrono::year_month_weekday::index", "chrono/std::chrono::year_month_weekday::year", "chrono/std::chrono::year_month_weekday::weekday_indexed", "chrono/std::chrono::year_month_weekday::sys_days", "chrono/std::chrono::year_month_weekday::local_days", "chrono/std::chrono::year_month_weekday::ok", "chrono/std::chrono::year_month_weekday::operator+=", "chrono/std::chrono::year_month_weekday::operator-="]
 helpviewer_keywords: ["std::chrono [C++], year_month_weekday"]
 ---
 
@@ -78,22 +78,24 @@ constexpr year_month_weekday(const sys_days& dp) noexcept;
 *`m`*\
 The [`month`](month-class.md) value.
 
-*`dp`*
+*`dp`*\
 A [`sys_days`](chrono.md#alias-declarations) or [`local_days`](chrono.md#alias-declarations)
 
 *`wdi`*\
 The [`weekday`](weekday-class.md) value.
 
 *`y`*\
-The [`year`] value.
+The [`year`](year-class.md) value.
 
 ### Remarks: Constructor
 
 1\) The default constructor doesn't initialize any of the fields.
 
+2\) Constructs a `year_month_weekday` that corresponds to the specified `year`, `month`, and `weekday_indexed`.
+
 3\) Constructs a `year_month_weekday` that corresponds to the date represented by `sys_days{dp.time_since_epoch()}`.
 
-4\) Constructs a `year_month_weekday` that corresponds to the date represented by *`dp`*.  For any `year_month_weekday` for which `ok()` is `true`, `year_month_weekday{sys_days{ymdl}}` is `true`.
+4\) Constructs a `year_month_weekday` that corresponds to the date represented by *`dp`*.  For any `year_month_weekday` (ymdl) for which `ok()` is `true`, comparison with `operator==` to `year_month_weekday{sys_days{ymdl}}` will be `true`.
 
 For information about C++ 20 syntax used to specify dates, see [`operator/`](chrono-operators.md#op_/)
 
@@ -162,7 +164,7 @@ Add months or years to this `year_month_weekday`.
 
 ```cpp
 1) constexpr year_month_weekday& operator+=(const months& m) noexcept;
-2) year_month_weekday& operator+=(const years& y) noexcept;
+2) constexpr year_month_weekday& operator+=(const years& y) noexcept;
 ```
 
 ### Parameters
@@ -226,7 +228,7 @@ The number of years to subtract.
 
 `*this` which reflects the result of the subtraction.
 
-### Example: `operator -=`
+### Example: `operator-=`
 
 ```cpp
 // compile using: /std:c++latest
diff --git a/docs/standard-library/year-month-weekday-last-class.md b/docs/standard-library/year-month-weekday-last-class.md

Original file line number	Diff line number	Diff line change
`@@ -139,8 +139,6 @@ int main()`
`139`	`139`	`}`
`140`	`140`	```
`141`	`141`
`142`		`-Output:`
`143`		`-`
`144`	`142`	```output
`145`	`143`	`01 02`
`146`	`144`	`02 02`
`@@ -183,8 +181,6 @@ int main()`
`183`	`181`	`}`
`184`	`182`	```
`185`	`183`
`186`		`-Output:`
`187`		`-`
`188`	`184`	```output
`189`	`185`	`05 04`
`190`	`186`	`04 04`
`@@ -260,7 +256,6 @@ int main()`
`260`	`256`	`}`
`261`	`257`	```
`262`	`258`
`263`		`-Output:`
`264`	`259`	```Output
`265`	`260`	`14`
`266`	`261`	```
Original file line number	Diff line number	Diff line change
`@@ -299,8 +299,6 @@ int main()`
`299`	`299`	`}`
`300`	`300`	```
`301`	`301`
`302`		`-Output:`
`303`		`-`
`304`	`302`	```output
`305`	`303`	`2021-01-11`
`306`	`304`	`2021-01-26`
Original file line number	Diff line number	Diff line change
`@@ -120,8 +120,6 @@ int main()`
`120`	`120`	`}`
`121`	`121`	```
`122`	`122`
`123`		`-Output:`
`124`		`-`
`125`	`123`	```output
`126`	`124`	`Mon[1]`
`127`	`125`	```