26 Time library [time]

26.10 Time zones [time.zone]

26.10.7 Class template zoned_­time [time.zone.zonedtime]

26.10.7.1 Overview [time.zone.zonedtime.overview]

namespace std::chrono {
  template<class Duration, class TimeZonePtr = const time_zone*>
  class zoned_time {
  public:
    using duration = common_type_t<Duration, seconds>;

  private:
    TimeZonePtr        zone_;                   // exposition only
    sys_time<duration> tp_;                     // exposition only

    using traits = zoned_traits<TimeZonePtr>;   // exposition only

  public:
    zoned_time();
    zoned_time(const zoned_time&) = default;
    zoned_time& operator=(const zoned_time&) = default;

    zoned_time(const sys_time<Duration>& st);
    explicit zoned_time(TimeZonePtr z);
    explicit zoned_time(string_view name);

    template<class Duration2>
      zoned_time(const zoned_time<Duration2, TimeZonePtr>& zt) noexcept;

    zoned_time(TimeZonePtr z,    const sys_time<Duration>& st);
    zoned_time(string_view name, const sys_time<Duration>& st);

    zoned_time(TimeZonePtr z,    const local_time<Duration>& tp);
    zoned_time(string_view name, const local_time<Duration>& tp);
    zoned_time(TimeZonePtr z,    const local_time<Duration>& tp, choose c);
    zoned_time(string_view name, const local_time<Duration>& tp, choose c);

    template<class Duration2, class TimeZonePtr2>
      zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& zt);
    template<class Duration2, class TimeZonePtr2>
      zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& zt, choose);

    zoned_time(string_view name, const zoned_time<Duration>& zt);
    zoned_time(string_view name, const zoned_time<Duration>& zt, choose);

    zoned_time& operator=(const sys_time<Duration>& st);
    zoned_time& operator=(const local_time<Duration>& ut);

    operator sys_time<duration>() const;
    explicit operator local_time<duration>() const;

    TimeZonePtr          get_time_zone()  const;
    local_time<duration> get_local_time() const;
    sys_time<duration>   get_sys_time()   const;
    sys_info             get_info()       const;
  };

  zoned_time() -> zoned_time<seconds>;

  template<class Duration>
    zoned_time(sys_time<Duration>)
      -> zoned_time<common_type_t<Duration, seconds>>;

  template<class TimeZonePtr, class Duration>
    zoned_time(TimeZonePtr, sys_time<Duration>)
      -> zoned_time<common_type_t<Duration, seconds>, TimeZonePtr>;

  template<class TimeZonePtr, class Duration>
    zoned_time(TimeZonePtr, local_time<Duration>, choose = choose::earliest)
      -> zoned_time<common_type_t<Duration, seconds>, TimeZonePtr>;

  template<class TimeZonePtr, class Duration>
    zoned_time(TimeZonePtr, zoned_time<Duration>, choose = choose::earliest)
      -> zoned_time<common_type_t<Duration, seconds>, TimeZonePtr>;

  zoned_time(string_view) -> zoned_time<seconds>;

  template<class Duration>
    zoned_time(string_view, sys_time<Duration>)
      -> zoned_time<common_type_t<Duration, seconds>>;

  template<class Duration>
    zoned_time(string_view, local_time<Duration>, choose = choose::earliest)
      -> zoned_time<common_type_t<Duration, seconds>>;

  template<class Duration, class TimeZonePtr, class TimeZonePtr2>
    zoned_time(TimeZonePtr, zoned_time<Duration, TimeZonePtr2>, choose = choose::earliest)
      -> zoned_time<Duration, TimeZonePtr>;
}
1
#
zoned_­time represents a logical pairing of a time_­zone and a time_­point with precision Duration.
zoned_­time<Duration> maintains the invariant that it always refers to a valid time zone and represents a point in time that exists and is not ambiguous in that time zone.
2
#
If Duration is not a specialization of chrono::duration, the program is ill-formed.

26.10.7.2 Constructors [time.zone.zonedtime.ctor]

🔗
zoned_time();
1
#
Remarks: This constructor does not participate in overload resolution unless traits::default_­zone() is a well-formed expression.
2
#
Effects: Constructs a zoned_­time by initializing zone_­ with traits::default_­zone() and default constructing tp_­.
🔗
zoned_time(const sys_time<Duration>& st);
3
#
Remarks: This constructor does not participate in overload resolution unless traits::default_­zone() is a well-formed expression.
4
#
Effects: Constructs a zoned_­time by initializing zone_­ with traits::default_­zone() and tp_­ with st.
🔗
explicit zoned_time(TimeZonePtr z);
5
#
Requires: z refers to a time zone.
6
#
Effects: Constructs a zoned_­time by initializing zone_­ with std::move(z).
🔗
explicit zoned_time(string_view name);
7
#
Remarks: This constructor does not participate in overload resolution unless traits::locate_­zone(string_­view{}) is a well-formed expression and zoned_­time is constructible from the return type of traits::locate_­zone(string_­view{}).
8
#
Effects: Constructs a zoned_­time by initializing zone_­ with traits::locate_­zone(name) and default constructing tp_­.
🔗
template<class Duration2> zoned_time(const zoned_time<Duration2, TimeZonePtr>& y) noexcept;
9
#
Remarks: Does not participate in overload resolution unless sys_­time<Duration2> is implicitly convertible to sys_­time<Duration>.
10
#
Effects: Constructs a zoned_­time by initializing zone_­ with y.zone_­ and tp_­ with y.tp_­.
🔗
zoned_time(TimeZonePtr z, const sys_time<Duration>& st);
11
#
Requires: z refers to a time zone.
12
#
Effects: Constructs a zoned_­time by initializing zone_­ with std::move(z) and tp_­ with st.
🔗
zoned_time(string_view name, const sys_time<Duration>& st);
13
#
Remarks: This constructor does not participate in overload resolution unless zoned_­time is constructible from the return type of traits::locate_­zone(name) and st.
14
#
Effects: Equivalent to construction with {traits::locate_­zone(name), st}.
🔗
zoned_time(TimeZonePtr z, const local_time<Duration>& tp);
15
#
Requires: z refers to a time zone.
16
#
Remarks: This constructor does not participate in overload resolution unless 
decltype(declval<TimeZonePtr&>()->to_sys(local_time<Duration>{}))
is convertible to sys_­time<duration>.
17
#
Effects: Constructs a zoned_­time by initializing zone_­ with std::move(z) and tp_­ with zone_­->to_­sys(tp).
🔗
zoned_time(string_view name, const local_time<Duration>& tp);
18
#
Remarks: This constructor does not participate in overload resolution unless zoned_­time is constructible from the return type of traits::locate_­zone(name) and tp.
19
#
Effects: Equivalent to construction with {traits::locate_­zone(name), tp}.
🔗
zoned_time(TimeZonePtr z, const local_time<Duration>& tp, choose c);
20
#
Requires: z refers to a time zone.
21
#
Remarks: This constructor does not participate in overload resolution unless 
decltype(declval<TimeZonePtr&>()->to_sys(local_time<Duration>{}, choose::earliest))
is convertible to sys_­time<duration>.
22
#
Effects: Constructs a zoned_­time by initializing zone_­ with std::move(z) and tp_­ with zone_­->to_­sys(tp, c).
🔗
zoned_time(string_view name, const local_time<Duration>& tp, choose c);
23
#
Remarks: This constructor does not participate in overload resolution unless zoned_­time is constructible from the return type of traits::locate_­zone(name), local_­time<Duration>, and choose.
24
#
Effects: Equivalent to construction with {traits::locate_­zone(name), tp, c}.
🔗
template<class Duration2, class TimeZonePtr2> zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& y);
25
#
Remarks: Does not participate in overload resolution unless sys_­time<Duration2> is implicitly convertible to sys_­time<Duration>.
26
#
Requires: z refers to a valid time zone.
27
#
Effects: Constructs a zoned_­time by initializing zone_­ with std::move(z) and tp_­ with y.tp_­.
🔗
template<class Duration2, class TimeZonePtr2> zoned_time(TimeZonePtr z, const zoned_time<Duration2, TimeZonePtr2>& y, choose);
28
#
Remarks: Does not participate in overload resolution unless sys_­time<Duration2> is implicitly convertible to sys_­time<Duration>.
29
#
Requires: z refers to a valid time zone.
30
#
Effects: Equivalent to construction with {z, y}.
31
#
[ Note
:
The choose parameter has no effect.
— end note
 ]
🔗
zoned_time(string_view name, const zoned_time<Duration>& y);
32
#
Remarks: This constructor does not participate in overload resolution unless zoned_­time is constructible from the return type of traits::locate_­zone(name) and zoned_­time.
33
#
Effects: Equivalent to construction with {traits::locate_­zone(name), y}.
🔗
zoned_time(string_view name, const zoned_time<Duration>& y, choose c);
34
#
Remarks: This constructor does not participate in overload resolution unless zoned_­time is constructible from the return type of traits::locate_­zone(name), zoned_­time, and choose.
35
#
Effects: Equivalent to construction with {traits::locate_­zone(name), y, c}.
36
#
[ Note
:
The choose parameter has no effect.
— end note
 ]

26.10.7.3 Member functions [time.zone.zonedtime.members]

🔗
zoned_time& operator=(const sys_time<Duration>& st);
1
#
Effects: After assignment, get_­sys_­time() == st.
This assignment has no effect on the return value of get_­time_­zone().
2
#
Returns: *this.
🔗
zoned_time& operator=(const local_time<Duration>& lt);
3
#
Effects: After assignment, get_­local_­time() == lt.
This assignment has no effect on the return value of get_­time_­zone().
4
#
Returns: *this.
🔗
operator sys_time<duration>() const;
5
#
Returns: get_­sys_­time().
🔗
explicit operator local_time<duration>() const;
6
#
Returns: get_­local_­time().
🔗
TimeZonePtr get_time_zone() const;
7
#
Returns: zone_­.
🔗
local_time<duration> get_local_time() const;
8
#
Returns: zone_­->to_­local(tp_­).
🔗
sys_time<duration> get_sys_time() const;
9
#
Returns: tp_­.
🔗
sys_info get_info() const;
10
#
Returns: zone_­->get_­info(tp_­).

26.10.7.4 Non-member functions [time.zone.zonedtime.nonmembers]

🔗
template<class Duration1, class Duration2, class TimeZonePtr> bool operator==(const zoned_time<Duration1, TimeZonePtr>& x, const zoned_time<Duration2, TimeZonePtr>& y);
1
#
Returns: x.zone_­ == y.zone_­ && x.tp_­ == y.tp_­.
🔗
template<class Duration1, class Duration2, class TimeZonePtr> bool operator!=(const zoned_time<Duration1, TimeZonePtr>& x, const zoned_time<Duration2, TimeZonePtr>& y);
2
#
Returns: !(x == y).
🔗
template<class charT, class traits, class Duration, class TimeZonePtr> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const zoned_time<Duration, TimeZonePtr>& t);
3
#
Effects: Streams the value returned from t.get_­local_­time() to os using the format "%F %T %Z".
4
#
Returns: os.
🔗
template<class charT, class traits, class Duration, class TimeZonePtr> basic_ostream<charT, traits>& to_stream(basic_ostream<charT, traits>& os, const charT* fmt, const zoned_time<Duration, TimeZonePtr>& tp);
5
#
Effects: First obtains a sys_­info via tp.get_­info() which for exposition purposes will be referred to as info.
Then calls to_­stream(os, fmt, tp.get_­local_­time(), &info.abbrev, &info.offset).
6
#
Returns: os.