first draft: year_month_day_last (MicrosoftDocs#3627)

TylerMSFT · TylerMSFT · web-flow · commit 04fae7690e50 · 2021-06-25T16:08:31.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

Co-authored-by: TylerMSFT &lt;Tyler.Whitney@microsoft.com&gt;
diff --git a/docs/standard-library/chrono-functions.md b/docs/standard-library/chrono-functions.md
@@ -2,7 +2,7 @@
 description: "Learn more about: &lt;chrono&gt; functions"
 title: "&lt;chrono&gt; functions"
 ms.date: 6/16/2021
-f1_keywords: ["chrono/std::duration_cast", "chrono/std::time_point_cast", "chrono/std::from_stream", "chrono/std::chrono::duration_cast", "chrono/std::chrono::time_point_cast", "chrono/std::chrono::from_stream", "chrono/std::chrono::floor", "chrono/std::chrono::ceil", "chrono/std::chrono::round", "chrono/std::chrono::is_am", "chrono/std::chrono::is_pm", "chrono/std::chrono::make12", "chrono/std::chrono::make24", "chrono/std::chrono::get_leap_second_info", "chrono/std::chrono::get_tzdb", "chrono/std::chrono::get_tzdb_list", "chrono/std::chrono::locate_zone", "chrono/std::chrono::current_zone", "chrono/std::chrono::reload_tzdb", "chrono/std::chrono::remote_version"]
+f1_keywords: ["chrono/std::duration_cast", "chrono/std::time_point_cast", "chrono/std::chrono::duration_cast", "chrono/std::chrono::time_point_cast", "chrono/std::chrono::from_stream", "chrono/std::chrono::floor", "chrono/std::chrono::ceil", "chrono/std::chrono::round", "chrono/std::chrono::is_am", "chrono/std::chrono::is_pm", "chrono/std::chrono::make12", "chrono/std::chrono::make24", "chrono/std::chrono::get_leap_second_info", "chrono/std::chrono::get_tzdb", "chrono/std::chrono::get_tzdb_list", "chrono/std::chrono::locate_zone", "chrono/std::chrono::current_zone", "chrono/std::chrono::reload_tzdb", "chrono/std::chrono::remote_version"]
 helpviewer_keywords: ["std::duration_cast function", "std::time_point_cast function", "std::chrono::duration_cast function", "std::chrono::time_point_cast function", "std::chrono::from_stream function", "std::chrono::floor function", "std::chrono::ceil function", "std::chrono::round function", "std::chrono::is_am function", "std::chrono::is_pm function", "std::chrono::make12 function", "std::chrono::make24 function", "std::chrono::get_leap_second_info function", "std::chrono::get_tzdb function", "std::chrono::get_tzdb_list function", "std::chrono::locate_zone function", "std::chrono::current_zone function", "std::chrono::reload_tzdb function", "std::chrono::remote_version function"]
 ---
 
diff --git a/docs/standard-library/chrono-operators.md b/docs/standard-library/chrono-operators.md
diff --git a/docs/standard-library/chrono.md b/docs/standard-library/chrono.md
@@ -39,6 +39,9 @@ Beginning in Visual Studio 2015, the implementation of `steady_clock` has change
 | [`year` class](../standard-library/year-class.md) | A year in the [Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar).|
 | [`year_month` class](../standard-library/year-month-class.md) | A year and month. The day isn't specified.|
 | [`year_month_day` class](../standard-library/year-month-day-class.md) | A year, month, and day.|
+| [`year_month_day_last` class](../standard-library/year-month-day-last-class.md) | The last day of a specific month and year. |
+| [`year_month_weekday` class](../standard-library/year-month-weekday-class.md) | A specific year, month, and nth weekday of the month. |
+| [`year_month_weekday_last` class](../standard-library/year-month-weekday-last-class.md) |  A specific year, month, and last weekday of the month. |
 
 ### Structs
 
diff --git a/docs/standard-library/month-class.md b/docs/standard-library/month-class.md
@@ -107,7 +107,7 @@ using namespace std::chrono;
 
 int main()
 {
-    month m{1};
+    month m{January};
 
     std::cout << m << " " << ++m << "\n"; // constexpr month& operator++() noexcept
     std::cout << m << " " << m++ << "\n"; // constexpr month operator++(int) noexcept
@@ -153,7 +153,7 @@ using namespace std::chrono;
 
 int main()
 {
-    std::chrono::month m{5};
+    month m{May};
 
     cout << m << " " << --m << "\n"; // constexpr month& operator++() noexcept
     cout << m << " " << m-- << "\n"; // constexpr month operator++(int) noexcept
diff --git a/docs/standard-library/month-day-class.md b/docs/standard-library/month-day-class.md
@@ -75,19 +75,17 @@ using namespace std::chrono;
 
 int main()
 {
-    month m(7);
-    day d(30);
-    month_day md(m, d);
+    month_day md(30d/July);
+    month_day md2 = July/30; // another way to construct a month_day
 
-    month_day md2 = July/30; // a convenient way to construct a month_day
-
-    std::cout << md << ' ' << md2;
+    std::cout << md << '\n' << md2;
     return 0;
 }
 ```
 
 ```output
-Jul/30 Jul/30
+Jul/30
+Jul/30
 ```
 
 ## <a name="day"></a> `day`
diff --git a/docs/standard-library/month-day-last-class.md b/docs/standard-library/month-day-last-class.md
@@ -63,13 +63,17 @@ using namespace std::chrono;
 
 int main()
 {
-   month_day_last mdl = month_day_last(month(10));
-   
-   // a convenient way to create a month_day_last
-   month_day_last mdl2 {October / last };
+    month_day_last mdl{ October / last };
+    std::cout << mdl;
+
+    return 0;
 }
 ```
 
+```output
+Oct/last
+```
+
 ## <a name="month"></a> `month`
 
  Return the month value.
diff --git a/docs/standard-library/month-weekday-class.md b/docs/standard-library/month-weekday-class.md
@@ -72,14 +72,13 @@ using namespace std::chrono;
 
 int main()
 {
-    constexpr auto wdi = weekday_indexed(Monday, 1);
-    constexpr auto month = July;
-    month_weekday mw(month, wdi);
+    month_weekday mw{ July/Monday[1] };
     std::cout << mw << '\n';
 
-    // A convenient way to create a month_weekday
+    // Another way to create a month_weekday
     month_weekday mw2 = February / Tuesday[3];
     std::cout << mw2;
+
     return 0;
 }
 ```
diff --git a/docs/standard-library/month-weekday-last-class.md b/docs/standard-library/month-weekday-last-class.md
@@ -71,7 +71,7 @@ using namespace std::chrono;
 
 int main()
 {
-    constexpr auto mwdl = January/Monday[last]; // wdl is the last Monday of January of an unspecified year
+    constexpr auto mwdl{ January / Monday[last] }; // wdl is the last Monday of January of an unspecified year
     std::cout << mwdl << "\n";
 
     const auto theMonth = August;
diff --git a/docs/standard-library/toc.yml b/docs/standard-library/toc.yml
@@ -194,6 +194,12 @@
           href: year-month-class.md
         - name: year_month_day class
           href: year-month-day-class.md
+        - name: year_month_day_last class
+          href: year-month-day-last-class.md
+        - name: year_month_weekday class
+          href: year-month-weekday-class.md
+        - name: year_month_weekday_last class
+          href: year-month-weekday-last-class.md
     - name: <cinttypes>
       href: ../standard-library/cinttypes.md
     - name: <ciso646>
diff --git a/docs/standard-library/weekday-class.md b/docs/standard-library/weekday-class.md
@@ -78,6 +78,30 @@ Construct a `weekday` with value *`wd`*.
 3\) Computes what day of the week corresponds to the `std::chrono::sys_days` value `dp`, and constructs a `weekday` using that day.\
 4\) Computes the day of the week that corresponds to the `std::chrono::local_days` value `dp`, and constructs a `weekday` using that day. It behaves as if you created the `weekday` using `weekday(std::chrono::sys_days(dp.time_since_epoch()))`.
 
+### Example: Create a `weekday`
+
+```cpp
+// compile using: /std:c++latest
+#include <iostream>
+#include <chrono>
+
+using namespace std::chrono;
+
+int main()
+{
+    weekday wd{ Wednesday };
+    weekday wd2{ 3 };
+    std::cout << wd << '\n' << wd2;
+    
+    return 0;
+}
+```
+
+```output
+Wednesday
+Wednesday
+```
+
 ## <a name="c_encoding"></a> `c_encoding`
 
 ```cpp
@@ -138,17 +162,16 @@ using namespace std::chrono;
 
 int main()
 {
-    std::chrono::weekday y{4};
+    std::chrono::weekday wd{Thursday};
 
-    std::cout << y << " " << ++y << "\n"; // constexpr weekday& operator++() noexcept
-    std::cout << y << " " << y++ << "\n"; // constexpr weekday operator++(int) noexcept
-    std::cout << y << "\n";
+    std::cout << wd << " " << ++wd << "\n"; // constexpr weekday& operator++() noexcept
+    std::cout << wd << " " << wd++ << "\n"; // constexpr weekday operator++(int) noexcept
+    std::cout << wd << "\n";
 
     return 0;
 }
 ```
 
-Output:
 ```output
 Thu Fri
 Fri Fri
@@ -185,7 +208,7 @@ using namespace std::chrono;
 
 int main()
 {
-    weekday y = weekday{4};
+    weekday y = weekday{Thursday};
 
     cout << y << " " << --y << "\n"; // constexpr weekday& operator--() noexcept
     cout << y << " " << y-- << "\n"; // constexpr weekday operator--(int) noexcept
@@ -195,8 +218,6 @@ int main()
 }
 ```
 
-Output:
-
 ```output
 Thu Wed
 Wed Wed
@@ -267,7 +288,7 @@ using namespace std::chrono;
 
 int main()
 {
-     constexpr auto firstMondayInJanuary =
+    constexpr auto firstMondayInJanuary =
         year_month_day{ Monday[2] / January / 2021y };
 
     std::cout << firstMondayInJanuary << "\n";
diff --git a/docs/standard-library/weekdayindexed-class.md b/docs/standard-library/weekdayindexed-class.md
@@ -69,7 +69,7 @@ using namespace std::chrono;
 
 int main()
 {
-   constexpr auto wdi = weekday_indexed(Monday, 1);
+   constexpr auto wdi = weekday_indexed{Monday, 1};
 
     std::cout << wdi;
     return 0;
@@ -113,7 +113,7 @@ The weekday value.
 
 int main()
 {
-    constexpr auto wdi = weekday_indexed(Monday, 1);
+    constexpr auto wdi = weekday_indexed{ Monday, 1 };
 	std::cout << wdi << "\n";
 
     return 0;
diff --git a/docs/standard-library/weekdaylast-class.md b/docs/standard-library/weekdaylast-class.md
@@ -103,17 +103,15 @@ using namespace std::chrono;
 
 int main()
 {
-    constexpr auto wdl = Monday[last]; // lastWeekday is the last Monday of an unspecified month
+    constexpr auto wdl{ Monday[last] }; // wdl is the last Monday of an unspecified month
 	std::cout << wdl.weekday() << "\n";
 
     return 0;
 }
 ```
 
-Output:
-
 ```output
-Monday
+Mon
 ```
 
 ## See also
diff --git a/docs/standard-library/year-class.md b/docs/standard-library/year-class.md
@@ -78,6 +78,7 @@ Construct a `year` with value *`y`*.
 ### Example: Create a `year`
 
 ```cpp
+// compile using: /std:c++latest
 #include <iostream>
 #include <chrono>
 
@@ -160,6 +161,7 @@ Returns `*this`
 ### Example: unary `operator+`
 
 ```cpp
+// compile using: /std:c++latest
 #include <iostream>
 #include <chrono>
 
@@ -196,6 +198,7 @@ Add 1 to the year value.
 ### Example: `operator++`
 
 ```cpp
+// compile using: /std:c++latest
 #include <iostream>
 #include <chrono>
 
@@ -237,6 +240,7 @@ Returns a negated copy of the `year`.
 ### Example: unary `operator-`
 
 ```cpp
+// compile using: /std:c++latest
 #include <iostream>
 #include <chrono>
 
@@ -274,6 +278,7 @@ Subtract 1 from the year value.
 ### Example: `operator--`
 
 ```cpp
+// compile using: /std:c++latest
 #include <iostream>
 #include <chrono>
 
@@ -335,7 +340,6 @@ The number of years to subtract.
 
 `*this`. If the decremented result is less than -32768, it's set to 32767.
 
-
 ## <a name="op_int"></a> `operator int`
 
 Get the `year` value.
@@ -351,7 +355,9 @@ The value of the `year`
 ### Example: `operator int()`
 
 ```cpp
-#include <iostream>
+// compile using: /std:c++latest
+
+ #include <iostream>
 #include <chrono>
 
 using namespace std::chrono;
diff --git a/docs/standard-library/year-month-class.md b/docs/standard-library/year-month-class.md
@@ -78,8 +78,7 @@ using namespace std::chrono;
 
 int main()
 {
-    const year theYear{2021};
-    year_month ym{theYear, June};
+    year_month ym{2021y / June};
 
     std::cout << ym;
     return 0;
@@ -141,7 +140,7 @@ Add months or years to this `year_month`.
 The number of months to add.
 
 *`dy`*\
-The numbers of years to add
+The number of years to add.
 
 ### Return value
 
@@ -158,10 +157,9 @@ using namespace std::chrono;
 
 int main()
 {
-    const year theYear{2021};
-    year_month ym{theYear, June};
+    year_month ym{2021y / June};
 
-    std::cout << ym << `\n`;
+    std::cout << ym << '\n';
 
     ym += months{2};
     ym += years{1};
@@ -192,7 +190,7 @@ Subtract months or years from this `year_month`.
 The number of months to subtract.
 
 *`dy`*\
-The numbers of years to subtract
+The number of years to subtract.
 
 ### Return value
 
@@ -209,10 +207,9 @@ using namespace std::chrono;
 
 int main()
 {
-    const year theYear{2021};
-    year_month ym{theYear, June};
+    year_month ym{2021y / June};
 
-    std::cout << ym << `\n`;
+    std::cout << ym << '\n';
 
     ym -= months{2};
     ym -= years{1};
diff --git a/docs/standard-library/year-month-day-class.md b/docs/standard-library/year-month-day-class.md
diff --git a/docs/standard-library/year-month-day-last-class.md b/docs/standard-library/year-month-day-last-class.md
diff --git a/docs/standard-library/year-month-weekday-class.md b/docs/standard-library/year-month-weekday-class.md
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
`@@ -107,7 +107,7 @@ using namespace std::chrono;`
`107`	`107`
`108`	`108`	`int main()`
`109`	`109`	`{`
`110`		`- month m{1};`
	`110`	`+ month m{January};`
`111`	`111`
`112`	`112`	`std::cout << m << " " << ++m << "\n"; // constexpr month& operator++() noexcept`
`113`	`113`	`std::cout << m << " " << m++ << "\n"; // constexpr month operator++(int) noexcept`
`@@ -153,7 +153,7 @@ using namespace std::chrono;`
`153`	`153`
`154`	`154`	`int main()`
`155`	`155`	`{`
`156`		`- std::chrono::month m{5};`
	`156`	`+ month m{May};`
`157`	`157`
`158`	`158`	`cout << m << " " << --m << "\n"; // constexpr month& operator++() noexcept`
`159`	`159`	`cout << m << " " << m-- << "\n"; // constexpr month operator++(int) noexcept`
Original file line number	Diff line number	Diff line change
`@@ -71,7 +71,7 @@ using namespace std::chrono;`
`71`	`71`
`72`	`72`	`int main()`
`73`	`73`	`{`
`74`		`- constexpr auto mwdl = January/Monday[last]; // wdl is the last Monday of January of an unspecified year`
	`74`	`+ constexpr auto mwdl{ January / Monday[last] }; // wdl is the last Monday of January of an unspecified year`
`75`	`75`	`std::cout << mwdl << "\n";`
`76`	`76`
`77`	`77`	`const auto theMonth = August;`