depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
cppdraft_translate/cppdraft/time/cal/ymd.md
Leonov Artur (Depish) 043225d523 Init
2025-10-25 03:02:53 +03:00

451 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[time.cal.ymd]
# 30 Time library [[time]](./#time)
## 30.8 The civil calendar [[time.cal]](time.cal#ymd)
### 30.8.14 Class year_month_day [time.cal.ymd]
#### [30.8.14.1](#overview) Overview [[time.cal.ymd.overview]](time.cal.ymd.overview)
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; };}
[1](#overview-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6363)
year_month_day represents a specific year, month, and day[.](#overview-1.sentence-1)
year_month_day is a field-based time point with a resolution of days[.](#overview-1.sentence-2)
[*Note [1](#overview-note-1)*:
year_month_day supports years- and months-oriented arithmetic,
but not days-oriented arithmetic[.](#overview-1.sentence-3)
For the latter, there is a conversion to sys_days,
which efficiently supports days-oriented arithmetic[.](#overview-1.sentence-4)
— *end note*]
year_month_day meets the [*Cpp17EqualityComparable*](utility.arg.requirements#:Cpp17EqualityComparable "16.4.4.2 Template argument requirements [utility.arg.requirements]") (Table [28](utility.arg.requirements#tab:cpp17.equalitycomparable "Table 28: Cpp17EqualityComparable requirements"))
and [*Cpp17LessThanComparable*](utility.arg.requirements#:Cpp17LessThanComparable "16.4.4.2 Template argument requirements [utility.arg.requirements]") (Table [29](utility.arg.requirements#tab:cpp17.lessthancomparable "Table 29: Cpp17LessThanComparable requirements")) requirements[.](#overview-1.sentence-5)
[2](#overview-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6375)
year_month_day is a trivially copyable and standard-layout class type[.](#overview-2.sentence-1)
#### [30.8.14.2](#members) Member functions [[time.cal.ymd.members]](time.cal.ymd.members)
[🔗](#lib:year_month_day,constructor)
`constexpr year_month_day(const chrono::year& y, const chrono::month& m,
const chrono::day& d) noexcept;
`
[1](#members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6387)
*Effects*: Initializesy_ with y,m_ with m, andd_ with d[.](#members-1.sentence-1)
[🔗](#lib:year_month_day,constructor_)
`constexpr year_month_day(const year_month_day_last& ymdl) noexcept;
`
[2](#members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6401)
*Effects*: Initializesy_ with ymdl.year(),m_ with ymdl.month(), andd_ with ymdl.day()[.](#members-2.sentence-1)
[*Note [1](#members-note-1)*:
This conversion from year_month_day_last to year_month_day can 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[.](#members-2.sentence-2)
— *end note*]
[🔗](#lib:year_month_day,constructor__)
`constexpr year_month_day(const sys_days& dp) noexcept;
`
[3](#members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6420)
*Effects*: Constructs an object of type year_month_day that corresponds to the date represented by dp[.](#members-3.sentence-1)
[4](#members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6425)
*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[.](#members-4.sentence-1)
[🔗](#lib:year_month_day,constructor___)
`constexpr explicit year_month_day(const local_days& dp) noexcept;
`
[5](#members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6439)
*Effects*: Equivalent to constructing with sys_days{dp.time_since_epoch()}[.](#members-5.sentence-1)
[🔗](#lib:operator+=,year_month_day)
`constexpr year_month_day& operator+=(const months& m) noexcept;
`
[6](#members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6450)
*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 tomonths ([[over.ics.rank]](over.ics.rank "12.2.4.3 Ranking implicit conversion sequences"))[.](#members-6.sentence-1)
[7](#members-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6458)
*Effects*: *this = *this + m[.](#members-7.sentence-1)
[8](#members-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6462)
*Returns*: *this[.](#members-8.sentence-1)
[🔗](#lib:operator-=,year_month_day)
`constexpr year_month_day& operator-=(const months& m) noexcept;
`
[9](#members-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6473)
*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 tomonths ([[over.ics.rank]](over.ics.rank "12.2.4.3 Ranking implicit conversion sequences"))[.](#members-9.sentence-1)
[10](#members-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6481)
*Effects*: *this = *this - m[.](#members-10.sentence-1)
[11](#members-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6485)
*Returns*: *this[.](#members-11.sentence-1)
[🔗](#lib:operator+=,year_month_day_)
`constexpr year_month_day& year_month_day::operator+=(const years& y) noexcept;
`
[12](#members-12)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6496)
*Effects*: *this = *this + y[.](#members-12.sentence-1)
[13](#members-13)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6500)
*Returns*: *this[.](#members-13.sentence-1)
[🔗](#lib:operator-=,year_month_day_)
`constexpr year_month_day& year_month_day::operator-=(const years& y) noexcept;
`
[14](#members-14)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6511)
*Effects*: *this = *this - y[.](#members-14.sentence-1)
[15](#members-15)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6515)
*Returns*: *this[.](#members-15.sentence-1)
[🔗](#lib:year,year_month_day)
`constexpr chrono::year year() const noexcept;
`
[16](#members-16)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6526)
*Returns*: y_[.](#members-16.sentence-1)
[🔗](#lib:month,year_month_day)
`constexpr chrono::month month() const noexcept;
`
[17](#members-17)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6537)
*Returns*: m_[.](#members-17.sentence-1)
[🔗](#lib:day,year_month_day)
`constexpr chrono::day day() const noexcept;
`
[18](#members-18)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6548)
*Returns*: d_[.](#members-18.sentence-1)
[🔗](#lib:operator_sys_days,year_month_day)
`constexpr operator sys_days() const noexcept;
`
[19](#members-19)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6559)
*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)[.](#members-19.sentence-1)
Otherwise, if y_.ok() && m_.ok() is true,
returns sys_days{y_/m_/1d} + (d_ - 1d)[.](#members-19.sentence-2)
Otherwise the value returned is unspecified[.](#members-19.sentence-3)
[20](#members-20)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6569)
*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[.](#members-20.sentence-1)
[21](#members-21)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6575)
[*Example [1](#members-example-1)*: 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*]
[🔗](#lib:operator_local_days,year_month_day)
`constexpr explicit operator local_days() const noexcept;
`
[22](#members-22)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6591)
*Returns*: local_days{sys_days{*this}.time_since_epoch()}[.](#members-22.sentence-1)
[🔗](#lib:ok,year_month_day)
`constexpr bool ok() const noexcept;
`
[23](#members-23)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6602)
*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[.](#members-23.sentence-1)
#### [30.8.14.3](#nonmembers) Non-member functions [[time.cal.ymd.nonmembers]](time.cal.ymd.nonmembers)
[🔗](#lib:operator==,year_month_day)
`constexpr bool operator==(const year_month_day& x, const year_month_day& y) noexcept;
`
[1](#nonmembers-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6618)
*Returns*: x.year() == y.year() && x.month() == y.month() && x.day() == y.day()[.](#nonmembers-1.sentence-1)
[🔗](#lib:operator%3c=%3e,year_month_day)
`constexpr strong_ordering operator<=>(const year_month_day& x, const year_month_day& y) noexcept;
`
[2](#nonmembers-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6629)
*Effects*: Equivalent to: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();
[🔗](#lib:operator+,year_month_day)
`constexpr year_month_day operator+(const year_month_day& ymd, const months& dm) noexcept;
`
[3](#nonmembers-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6645)
*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 tomonths ([[over.ics.rank]](over.ics.rank "12.2.4.3 Ranking implicit conversion sequences"))[.](#nonmembers-3.sentence-1)
[4](#nonmembers-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6653)
*Returns*: (ymd.year() / ymd.month() + dm) / ymd.day()[.](#nonmembers-4.sentence-1)
[5](#nonmembers-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6657)
[*Note [1](#nonmembers-note-1)*:
If ymd.day() is in the range [1d, 28d],ok() will return true for
the resultant year_month_day[.](#nonmembers-5.sentence-1)
— *end note*]
[🔗](#lib:operator+,year_month_day_)
`constexpr year_month_day operator+(const months& dm, const year_month_day& ymd) noexcept;
`
[6](#nonmembers-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6671)
*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 tomonths ([[over.ics.rank]](over.ics.rank "12.2.4.3 Ranking implicit conversion sequences"))[.](#nonmembers-6.sentence-1)
[7](#nonmembers-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6679)
*Returns*: ymd + dm[.](#nonmembers-7.sentence-1)
[🔗](#lib:operator-,year_month_day)
`constexpr year_month_day operator-(const year_month_day& ymd, const months& dm) noexcept;
`
[8](#nonmembers-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6690)
*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 tomonths ([[over.ics.rank]](over.ics.rank "12.2.4.3 Ranking implicit conversion sequences"))[.](#nonmembers-8.sentence-1)
[9](#nonmembers-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6698)
*Returns*: ymd + (-dm)[.](#nonmembers-9.sentence-1)
[🔗](#lib:operator+,year_month_day__)
`constexpr year_month_day operator+(const year_month_day& ymd, const years& dy) noexcept;
`
[10](#nonmembers-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6709)
*Returns*: (ymd.year() + dy) / ymd.month() / ymd.day()[.](#nonmembers-10.sentence-1)
[11](#nonmembers-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6713)
[*Note [2](#nonmembers-note-2)*:
If ymd.month() is February
and ymd.day() is not in the range [1d, 28d],ok() can return false for
the resultant year_month_day[.](#nonmembers-11.sentence-1)
— *end note*]
[🔗](#lib:operator+,year_month_day___)
`constexpr year_month_day operator+(const years& dy, const year_month_day& ymd) noexcept;
`
[12](#nonmembers-12)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6728)
*Returns*: ymd + dy[.](#nonmembers-12.sentence-1)
[🔗](#lib:operator-,year_month_day_)
`constexpr year_month_day operator-(const year_month_day& ymd, const years& dy) noexcept;
`
[13](#nonmembers-13)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6739)
*Returns*: ymd + (-dy)[.](#nonmembers-13.sentence-1)
[🔗](#lib:operator%3c%3c,year_month_day)
`template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, const year_month_day& ymd);
`
[14](#nonmembers-14)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6752)
*Effects*: Equivalent to:return os << (ymd.ok() ? format(*STATICALLY-WIDEN*<charT>("{:%F}"), ymd) : format(*STATICALLY-WIDEN*<charT>("{:%F} is not a valid date"), ymd));
[🔗](#lib:from_stream,year_month_day)
`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);
`
[15](#nonmembers-15)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6772)
*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]](time.parse "30.13 Parsing")[.](#nonmembers-15.sentence-1)
If the parse fails to decode a valid year_month_day,is.setstate(ios_base​::​failbit) is called andymd is not modified[.](#nonmembers-15.sentence-2)
If %Z is used and successfully parsed,
that value will be assigned to *abbrev if abbrev is non-null[.](#nonmembers-15.sentence-3)
If %z (or a modified variant) is used and successfully parsed,
that value will be assigned to *offset if offset is non-null[.](#nonmembers-15.sentence-4)
[16](#nonmembers-16)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6786)
*Returns*: is[.](#nonmembers-16.sentence-1)
Reference in New Issue View Git Blame Copy Permalink