[time.cal.ymd] - C++17 → C++20

Files changed (1) hide show

tmp/tmp1p1n5zk3/{from.md → to.md} +299 -0

tmp/tmp1p1n5zk3/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,299 @@

+### Class `year_month_day` <a id="time.cal.ymd">[[time.cal.ymd]]</a>
+#### Overview <a id="time.cal.ymd.overview">[[time.cal.ymd.overview]]</a>
+``` cpp
+namespace std::chrono {
+  class year_month_day {
+    chrono::year  y_;           // exposition only
+    chrono::month m_;           // exposition only
+    chrono::day   d_;           // exposition only
+  public:
+    year_month_day() = default;
+    constexpr year_month_day(const chrono::year& y, const chrono::month& m,
+                             const chrono::day& d) noexcept;
+    constexpr year_month_day(const year_month_day_last& ymdl) noexcept;
+    constexpr year_month_day(const sys_days& dp) noexcept;
+    constexpr explicit year_month_day(const local_days& dp) noexcept;
+    constexpr year_month_day& operator+=(const months& m) noexcept;
+    constexpr year_month_day& operator-=(const months& m) noexcept;
+    constexpr year_month_day& operator+=(const years& y)  noexcept;
+    constexpr year_month_day& operator-=(const years& y)  noexcept;
+    constexpr chrono::year  year()  const noexcept;
+    constexpr chrono::month month() const noexcept;
+    constexpr chrono::day   day()   const noexcept;
+    constexpr          operator sys_days()   const noexcept;
+    constexpr explicit operator local_days() const noexcept;
+    constexpr bool ok() const noexcept;
+  };
+}
+```
+`year_month_day` represents a specific year, month, and day.
+`year_month_day` is a field-based time point with a resolution of
+`days`.
+[*Note 1*: `year_month_day` supports `years`- and `months`-oriented
+arithmetic, but not `days`-oriented arithmetic. For the latter, there is
+a conversion to `sys_days`, which efficiently supports `days`-oriented
+arithmetic. — *end note*]
+`year_month_day` meets the *Cpp17EqualityComparable* (
+[[cpp17.equalitycomparable]]) and *Cpp17LessThanComparable* (
+[[cpp17.lessthancomparable]]) requirements.
+`year_month_day` is a trivially copyable and standard-layout class type.
+#### Member functions <a id="time.cal.ymd.members">[[time.cal.ymd.members]]</a>
+``` cpp
+constexpr year_month_day(const chrono::year& y, const chrono::month& m,
+                         const chrono::day& d) noexcept;
+```
+*Effects:* Initializes `y_` with `y`, `m_` with `m`, and `d_` with `d`.
+``` cpp
+constexpr year_month_day(const year_month_day_last& ymdl) noexcept;
+```
+*Effects:* Initializes `y_` with `ymdl.year()`, `m_` with
+`ymdl.month()`, and `d_` with `ymdl.day()`.
+[*Note 1*: This conversion from `year_month_day_last` to
+`year_month_day` may be more efficient than converting a
+`year_month_day_last` to a `sys_days`, and then converting that
+`sys_days` to a `year_month_day`. — *end note*]
+``` cpp
+constexpr year_month_day(const sys_days& dp) noexcept;
+```
+*Effects:* Constructs an object of type `year_month_day` that
+corresponds to the date represented by `dp`.
+*Remarks:* For any value `ymd` of type `year_month_day` for which
+`ymd.ok()` is `true`, `ymd == year_month_day{sys_days{ymd}}` is `true`.
+``` cpp
+constexpr explicit year_month_day(const local_days& dp) noexcept;
+```
+*Effects:* Equivalent to constructing with
+`sys_days{dp.time_since_epoch()}`.
+``` cpp
+constexpr year_month_day& operator+=(const months& m) noexcept;
+```
+*Constraints:* If the argument supplied by the caller for the `months`
+parameter is convertible to `years`, its implicit conversion sequence to
+`years` is worse than its implicit conversion sequence to `months`
+[[over.ics.rank]].
+*Effects:* `*this = *this + m`.
+*Returns:* `*this`.
+``` cpp
+constexpr year_month_day& operator-=(const months& m) noexcept;
+```
+*Constraints:* If the argument supplied by the caller for the `months`
+parameter is convertible to `years`, its implicit conversion sequence to
+`years` is worse than its implicit conversion sequence to `months`
+[[over.ics.rank]].
+*Effects:* `*this = *this - m`.
+*Returns:* `*this`.
+``` cpp
+constexpr year_month_day& year_month_day::operator+=(const years& y) noexcept;
+```
+*Effects:* `*this = *this + y`.
+*Returns:* `*this`.
+``` cpp
+constexpr year_month_day& year_month_day::operator-=(const years& y) noexcept;
+```
+*Effects:* `*this = *this - y`.
+*Returns:* `*this`.
+``` cpp
+constexpr chrono::year year() const noexcept;
+```
+*Returns:* `y_`.
+``` cpp
+constexpr chrono::month month() const noexcept;
+```
+*Returns:* `m_`.
+``` cpp
+constexpr chrono::day day() const noexcept;
+```
+*Returns:* `d_`.
+``` cpp
+constexpr operator sys_days() const noexcept;
+```
+*Returns:* If `ok()`, returns a `sys_days` holding a count of days from
+the `sys_days` epoch to `*this` (a negative value if `*this` represents
+a date prior to the `sys_days` epoch). Otherwise, if
+`y_.ok() && m_.ok()` is `true`, returns
+`sys_days{y_/m_/1d} + (d_ - 1d)`. Otherwise the value returned is
+unspecified.
+*Remarks:* A `sys_days` in the range \[`days{-12687428}`,
+`days{11248737}`\] which is converted to a `year_month_day` has the same
+value when converted back to a `sys_days`.
+[*Example 1*:
+``` cpp
+static_assert(year_month_day{sys_days{2017y/January/0}}  == 2016y/December/31);
+static_assert(year_month_day{sys_days{2017y/January/31}} == 2017y/January/31);
+static_assert(year_month_day{sys_days{2017y/January/32}} == 2017y/February/1);
+```
+— *end example*]
+``` cpp
+constexpr explicit operator local_days() const noexcept;
+```
+*Returns:* `local_days{sys_days{*this}.time_since_epoch()}`.
+``` cpp
+constexpr bool ok() const noexcept;
+```
+*Returns:* If `y_.ok()` is `true`, and `m_.ok()` is `true`, and `d_` is
+in the range \[`1d`, `(y_/m_/last).day()`\], then returns `true`;
+otherwise returns `false`.
+#### Non-member functions <a id="time.cal.ymd.nonmembers">[[time.cal.ymd.nonmembers]]</a>
+``` cpp
+constexpr bool operator==(const year_month_day& x, const year_month_day& y) noexcept;
+```
+*Returns:*
+`x.year() == y.year() && x.month() == y.month() && x.day() == y.day()`.
+``` cpp
+constexpr strong_ordering operator<=>(const year_month_day& x, const year_month_day& y) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+if (auto c = x.year() <=> y.year(); c != 0) return c;
+if (auto c = x.month() <=> y.month(); c != 0) return c;
+return x.day() <=> y.day();
+```
+``` cpp
+constexpr year_month_day operator+(const year_month_day& ymd, const months& dm) noexcept;
+```
+*Constraints:* If the argument supplied by the caller for the `months`
+parameter is convertible to `years`, its implicit conversion sequence to
+`years` is worse than its implicit conversion sequence to `months`
+[[over.ics.rank]].
+*Returns:* `(ymd.year() / ymd.month() + dm) / ymd.day()`.
+[*Note 1*: If `ymd.day()` is in the range \[`1d`, `28d`\], `ok()` will
+return `true` for the resultant `year_month_day`. — *end note*]
+``` cpp
+constexpr year_month_day operator+(const months& dm, const year_month_day& ymd) noexcept;
+```
+*Constraints:* If the argument supplied by the caller for the `months`
+parameter is convertible to `years`, its implicit conversion sequence to
+`years` is worse than its implicit conversion sequence to `months`
+[[over.ics.rank]].
+*Returns:* `ymd + dm`.
+``` cpp
+constexpr year_month_day operator-(const year_month_day& ymd, const months& dm) noexcept;
+```
+*Constraints:* If the argument supplied by the caller for the `months`
+parameter is convertible to `years`, its implicit conversion sequence to
+`years` is worse than its implicit conversion sequence to `months`
+[[over.ics.rank]].
+*Returns:* `ymd + (-dm)`.
+``` cpp
+constexpr year_month_day operator+(const year_month_day& ymd, const years& dy) noexcept;
+```
+*Returns:* `(ymd.year() + dy) / ymd.month() / ymd.day()`.
+[*Note 2*: If `ymd.month()` is February and `ymd.day()` is not in the
+range \[`1d`, `28d`\], `ok()` may return `false` for the resultant
+`year_month_day`. — *end note*]
+``` cpp
+constexpr year_month_day operator+(const years& dy, const year_month_day& ymd) noexcept;
+```
+*Returns:* `ymd + dy`.
+``` cpp
+constexpr year_month_day operator-(const year_month_day& ymd, const years& dy) noexcept;
+```
+*Returns:* `ymd + (-dy)`.
+``` cpp
+template<class charT, class traits>
+  basic_ostream<charT, traits>&
+    operator<<(basic_ostream<charT, traits>& os, const year_month_day& ymd);
+```
+*Effects:* Equivalent to:
+``` cpp
+return os << (ymd.ok() ?
+  format(STATICALLY-WIDEN<charT>("{:%F}"), ymd) :
+  format(STATICALLY-WIDEN<charT>("{:%F} is not a valid date"), ymd));
+```
+``` cpp
+template<class charT, class traits, class Alloc = allocator<charT>>
+  basic_istream<charT, traits>&
+    from_stream(basic_istream<charT, traits>& is, const charT* fmt,
+                year_month_day& ymd, basic_string<charT, traits, Alloc>* abbrev = nullptr,
+                minutes* offset = nullptr);
+```
+*Effects:* Attempts to parse the input stream `is` into the
+`year_month_day` `ymd` using the format flags given in the NTCTS `fmt`
+as specified in [[time.parse]]. If the parse fails to decode a valid
+`year_month_day`, `is.setstate(ios_base::failbit)` is called and `ymd`
+is not modified. If `%Z` is used and successfully parsed, that value
+will be assigned to `*abbrev` if `abbrev` is non-null. If `%z` (or a
+modified variant) is used and successfully parsed, that value will be
+assigned to `*offset` if `offset` is non-null.
+*Returns:* `is`.

Diff to HTML by rtfpessoa