[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)