[time.cal.ym]

# 30 Time library [[time]](./#time)

## 30.8 The civil calendar [[time.cal]](time.cal#ym)

### 30.8.13 Class year_month [time.cal.ym]

#### [30.8.13.1](#overview) Overview [[time.cal.ym.overview]](time.cal.ym.overview)

namespace std::chrono {class year_month { chrono::year y_; // *exposition only* chrono::month m_; // *exposition only*public: year_month() = default; constexpr year_month(const chrono::year& y, const chrono::month& m) noexcept; constexpr chrono::year year() const noexcept; constexpr chrono::month month() const noexcept; constexpr year_month& operator+=(const months& dm) noexcept; constexpr year_month& operator-=(const months& dm) noexcept; constexpr year_month& operator+=(const years& dy) noexcept; constexpr year_month& operator-=(const years& dy) noexcept; constexpr bool ok() const noexcept; };}

[1](#overview-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6012)

year_month represents a specific month of a specific year,
but with an unspecified day[.](#overview-1.sentence-1)

year_month is a field-based time point with a resolution of months[.](#overview-1.sentence-2)

year_month 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-3)

[2](#overview-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6019)

year_month is a trivially copyable and standard-layout class type[.](#overview-2.sentence-1)

#### [30.8.13.2](#members) Member functions [[time.cal.ym.members]](time.cal.ym.members)

[ð](#lib:year_month,constructor)

`constexpr year_month(const chrono::year& y, const chrono::month& m) noexcept;
`

[1](#members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6030)

*Effects*: Initializes y_ with y, and m_ with m[.](#members-1.sentence-1)

[ð](#lib:year,year_month)

`constexpr chrono::year year() const noexcept;
`

[2](#members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6041)

*Returns*: y_[.](#members-2.sentence-1)

[ð](#lib:month,year_month)

`constexpr chrono::month month() const noexcept;
`

[3](#members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6052)

*Returns*: m_[.](#members-3.sentence-1)

[ð](#lib:operator+=,year_month)

`constexpr year_month& operator+=(const months& dm) noexcept;
`

[4](#members-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6063)

*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-4.sentence-1)

[5](#members-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6071)

*Effects*: *this = *this + dm[.](#members-5.sentence-1)

[6](#members-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6075)

*Returns*: *this[.](#members-6.sentence-1)

[ð](#lib:operator-=,year_month)

`constexpr year_month& operator-=(const months& dm) noexcept;
`

[7](#members-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6086)

*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-7.sentence-1)

[8](#members-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6094)

*Effects*: *this = *this - dm[.](#members-8.sentence-1)

[9](#members-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6098)

*Returns*: *this[.](#members-9.sentence-1)

[ð](#lib:operator+=,year_month_)

`constexpr year_month& operator+=(const years& dy) noexcept;
`

[10](#members-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6109)

*Effects*: *this = *this + dy[.](#members-10.sentence-1)

[11](#members-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6113)

*Returns*: *this[.](#members-11.sentence-1)

[ð](#lib:operator-=,year_month_)

`constexpr year_month& operator-=(const years& dy) noexcept;
`

[12](#members-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6124)

*Effects*: *this = *this - dy[.](#members-12.sentence-1)

[13](#members-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6128)

*Returns*: *this[.](#members-13.sentence-1)

[ð](#lib:ok,year_month)

`constexpr bool ok() const noexcept;
`

[14](#members-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6139)

*Returns*: y_.ok() && m_.ok()[.](#members-14.sentence-1)

#### [30.8.13.3](#nonmembers) Non-member functions [[time.cal.ym.nonmembers]](time.cal.ym.nonmembers)

[ð](#lib:operator==,year_month)

`constexpr bool operator==(const year_month& x, const year_month& y) noexcept;
`

[1](#nonmembers-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6152)

*Returns*: x.year() == y.year() && x.month() == y.month()[.](#nonmembers-1.sentence-1)

[ð](#lib:operator%3c=%3e,year_month)

`constexpr strong_ordering operator<=>(const year_month& x, const year_month& y) noexcept;
`

[2](#nonmembers-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6163)

*Effects*: Equivalent to:if (auto c = x.year() <=> y.year(); c != 0) return c;return x.month() <=> y.month();

[ð](#lib:operator+,year_month)

`constexpr year_month operator+(const year_month& ym, const months& dm) noexcept;
`

[3](#nonmembers-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6178)

*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#L6186)

*Returns*: A year_month value z such that z.ok() && z - ym == dm is true[.](#nonmembers-4.sentence-1)

[5](#nonmembers-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6191)

*Complexity*: O(1) with respect to the value of dm[.](#nonmembers-5.sentence-1)

[ð](#lib:operator+,year_month_)

`constexpr year_month operator+(const months& dm, const year_month& ym) noexcept;
`

[6](#nonmembers-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6202)

*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#L6210)

*Returns*: ym + dm[.](#nonmembers-7.sentence-1)

[ð](#lib:operator-,year_month)

`constexpr year_month operator-(const year_month& ym, const months& dm) noexcept;
`

[8](#nonmembers-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6221)

*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#L6229)

*Returns*: ym + -dm[.](#nonmembers-9.sentence-1)

[ð](#lib:operator-,year_month_)

`constexpr months operator-(const year_month& x, const year_month& y) noexcept;
`

[10](#nonmembers-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6240)

*Returns*: x.year() - y.year() + months{static_cast<int>(unsigned{x.month()}) -static_cast<int>(unsigned{y.month()})}

[ð](#lib:operator+,year_month__)

`constexpr year_month operator+(const year_month& ym, const years& dy) noexcept;
`

[11](#nonmembers-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6254)

*Returns*: (ym.year() + dy) / ym.month()[.](#nonmembers-11.sentence-1)

[ð](#lib:operator+,year_month___)

`constexpr year_month operator+(const years& dy, const year_month& ym) noexcept;
`

[12](#nonmembers-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6265)

*Returns*: ym + dy[.](#nonmembers-12.sentence-1)

[ð](#lib:operator-,year_month__)

`constexpr year_month operator-(const year_month& ym, const years& dy) noexcept;
`

[13](#nonmembers-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6276)

*Returns*: ym + -dy[.](#nonmembers-13.sentence-1)

[ð](#lib:operator%3c%3c,year_month)

`template<class charT, class traits>
  basic_ostream<charT, traits>&
    operator<<(basic_ostream<charT, traits>& os, const year_month& ym);
`

[14](#nonmembers-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6289)

*Effects*: Equivalent to:return os << format(os.getloc(), *STATICALLY-WIDEN*<charT>("{}/{:L}"),
 ym.year(), ym.month());

[ð](#lib:from_stream,year_month)

`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& ym, basic_string<charT, traits, Alloc>* abbrev = nullptr,
                minutes* offset = nullptr);
`

[15](#nonmembers-15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/time.tex#L6308)

*Effects*: Attempts to parse the input stream is into the year_month ym 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,is.setstate(ios_base​::​failbit) is called andym 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#L6322)

*Returns*: is[.](#nonmembers-16.sentence-1)
