diff --git a/tz.html b/tz.html index a633e72..6c19929 100644 --- a/tz.html +++ b/tz.html @@ -26,7 +26,7 @@

Howard E. Hinnant
-2016-04-09
+2016-05-08
Creative Commons License
This work is licensed @@ -60,6 +60,7 @@ Commons Attribution 4.0 International License.
  • Thread Safety
    • +
  • Reference
  • Installation — this is where you find the implementation
  • Acknowledgements
    • @@ -209,7 +210,7 @@ namespace date using second_point = std::chrono::time_point<std::chrono::system_clock, std::chrono::seconds>; -struct Info +struct sys_info { second_point begin; second_point end; @@ -219,9 +220,8 @@ struct Info }; std::ostream& -operator<<(std::ostream& os, const Info& r); +operator<<(std::ostream& os, const sys_info& r); -enum class tz {utc, local}; enum class choose {earliest, latest}; class nonexistent_local_time @@ -268,7 +268,7 @@ public: choose z) const; template <class Rep, class Period> - Info + sys_info get_info(std::chrono::time_point<std::chrono::system_clock, std::chrono::duration<Rep, Period>> tp, tz timezone) const; @@ -645,7 +645,7 @@ using second_point = std::chrono::time_point<std::chrono::system_clock, system_clock but with the precision of seconds. This library will interoperate with system_clock::time_points of any precision. However the data in the database is largely based on second_point, and -some of the data which is presented, such as that in the Info class, uses +some of the data which is presented, such as that in the sys_info class, uses this type alias as a convenience, and to reduce verbosity. second_point will implicitly convert to system_clock::time_point. And coarser time_points such as the day_point from the @@ -654,7 +654,7 @@ will implicitly convert to system_clock::time_point. And coarser 

    -struct Info
+struct sys_info
 {
     second_point         begin;
     second_point         end;
@@ -665,13 +665,13 @@ struct Info

    -The Info struct is the return type of the get_info member +The sys_info struct is the return type of the get_info member function of the Zone class. It contains very detailed information about the Zone at the time_point (UTC or local) input into this member -function. Info contains no pointers or references into the database. -Therefore clients do not need to be concerned about holding on to Infos +function. sys_info contains no pointers or references into the database. +Therefore clients do not need to be concerned about holding on to sys_infos during a call to reload_tzdb(). Though a call to reload_tzdb() -could potentially make the data in an outstanding Info obsolete. See +could potentially make the data in an outstanding sys_info obsolete. See Zone::get_info for more details.

    @@ -766,7 +766,7 @@ public: choose z) const; template <class Rep, class Period> - Info + sys_info get_info(std::chrono::time_point<std::chrono::system_clock, std::chrono::duration<Rep, Period>> tp, tz timezone) const; @@ -1089,7 +1089,7 @@ are guaranteed to stay valid: 
     template <class Rep, class Period>
-Info
+sys_info
 get_info(std::chrono::time_point<std::chrono::system_clock,
                                  std::chrono::duration<Rep, Period>> tp,
          tz timezone) const;
@@ -1098,48 +1098,48 @@ get_info(std::chrono::time_point<std::chrono::system_clock,
 
    
 Input a time_point tp, and indicate whether tp represents a UTC
 time_point (tz::utc) or a local time_point
-(tz::local), and a struct Info for that time_point
+(tz::local), and a struct sys_info for that time_point
 is returned:
 
    
 
 
    -auto info = locate_zone("America/New_York")->get_info(system_clock::now(), tz::utc);
+auto sys_info = locate_zone("America/New_York")->get_info(system_clock::now(), tz::utc);
 
    
 
 
    
-Upon return info will contain the following information:
+Upon return sys_info will contain the following information:
 
    
 
 
 
 
    
-The Info also has a streaming operator which is mainly useful for debugging
+The sys_info also has a streaming operator which is mainly useful for debugging
 purposes.  Here is sample code and output:
 
    
 
@@ -1844,7 +1844,7 @@ const TZ_DB& get_tzdb();
 // Zone functions
 const Zone* locate_zone(const std::string& tz_name);
 const Zone* current_zone();
-Info Zone::get_info(std::chrono::system_clock::time_point tp, tz timezone) const;
+info Zone::get_info(std::chrono::system_clock::time_point tp, tz timezone) const;
 
 template <class Rep, class Period>
 auto
@@ -1889,6 +1889,1260 @@ reference or pointer.
 is read-only and there is no need for synchronization with an external mutex.
 
    
 
+
    Reference
    
+
+
    The database
    
+
    
+
+
    
+The following data structure is the time zone database, and the following
+functions access it.
+
    
+
+
    +struct TZ_DB
+{
+    std::string            version;
+    std::vector<time_zone> zones;
+    std::vector<Link>      links;
+    std::vector<Leap>      leaps;
+    std::vector<Rule>      rules;
+};
+
    
+
+
    
+The TZ_DB database is a singleton.  And access to it is
+read-only, except for reload_tzdb() which re-initializes it.
+Each vector is sorted to enable fast lookup.  You don't have to explicitly
+program binary search lookups on it.  That is handled by the API.  But you can
+explicitly iterate over and inspect this database.  And knowing that it is sorted may
+be of benefit to your inspection logic.
+
    
+
+
    
+All information in the
+IANA time zone database is
+represented in the above TZ_DB data structure, except for the
+comments in the database.  Thus it is up to you, the client of this library, to
+decide what to do with this data.  This library makes it especially easy and
+convenient to extract the data in the way that is most commonly used (e.g. time
+conversions among time zones).  But it represents all of the data, and
+hides none of it.
+
    
+
+
    +const TZ_DB& get_tzdb();
+
    
+
    
+
    
+Effects:  If this is the first access to the database, will initialize
+the database.  If tz.cpp was compiled with the configuration macro
+AUTO_DOWNLOAD == 1, initialization will include checking the
+IANA website for the latest
+version, and downloading the latest version if your local version is out of
+date, or doesn't exist at the location referred to by the install
+configuration variable in tz.cpp.  If tz.cpp was
+compiled with AUTO_DOWNLOAD == 0, you will have to download and
+decompress the IANA database from the
+IANA website and place it at the
+location referred to by the install configuration variable.
+
    
+
    
+AUTO_DOWNLOAD == 1 requires linking tz.cpp to
+libcurl.
+
    
+
    
+Returns: A const reference to the database.
+
    
+
    
+Thread Safety:  It is safe to call this function from multiple threads at
+one time.  There will be no race to initialize the singleton database as long as
+your compiler implements threadsafe function-local statics as specified by C++11.
+
    
+
    
+Throws: std::runtime_error if for any reason a reference can not
+be returned to a valid TZ_DB.
+
    
+
    
+
+
    +const time_zone* locate_zone(const std::string& tz_name);
+
    
+
    
+
    
+Effects:  Calls get_tzdb() which will initialize the timezone
+database if this is the first reference to the database.
+
    
+
    
+Returns: If a time_zone is found for which
+name() == tz_name, returns a pointer to that time_zone.
+Otherwise if a Link is found where tz_name == link.name(),
+then a pointer is returned to the time_zone for which
+zone.name() == link.target() [Note: A Link is an
+alternative name for a time_zone. — end note]
+
    
+
    
+Throws: Any exception propagated from get_tzdb().  If a
+const time_zone* can not be found as described in the
+Returns clause, throws a std::runtime_error. [Note:
+On non-exceptional return, the return value is always a pointer to a
+valid time_zone. — end note]
+
    
+
    
+
+
    +const time_zone* current_zone();
+
    
+
    
+Effects:  Calls locate_zone() which will initialize the timezone
+database if this is the first reference to the database.
+
    
+
    
+Returns: A const time_zone* referring to the time zone which your
+computer has set as its local time zone.
+
    
+
    
+Throws: Any exception propagated from locate_zone().
+[Note: On non-exceptional return, the return value is always a
+pointer to a valid time_zone. — end note]
+
    
+
+
    +const TZ_DB& reload_tzdb();
+
    
+
    
+
    
+Effects:
+
    
+
    
+
    
+If If tz.cpp was compiled with the configuration macro
+AUTO_DOWNLOAD == 1, this function first checks the latest version at the
+IANA website.  If the
+IANA website is unavailable, or if the
+latest version is already installed, there are no effects.  Otherwise, a new version
+is available.  It is downloaded and installed, and then the program re-initializes
+the TZ_DB singleton from the new disk files.
+
    
+
+
    
+If tz.cpp was compiled with the configuration macro
+AUTO_DOWNLOAD == 0, this function re-initializes the
+TZ_DB singleton from the disk files.  You can manually replace the
+database without ill-effects after your program has called
+get_tzdb() and before it calls reload_tzdb(), as there is
+no access to the files on disk between the first call to get_tzdb() and
+subsequent calls to reload_tzdb().
+
    
+
    
+
    
+Returns: A const reference to the database.
+
    
+
    
+Thread Safety:  This function is not thread safe.  You must
+provide your own synchronization among threads accessing the time zone database
+to safely use this function.  If this function re-initializes the database (as
+it always does when AUTO_DOWNLOAD == 0), all outstanding
+const time_zone* are invalidated (including those held within
+zoned_time objects).  And afterwards, all outstanding
+sys_info may hold obsolete data.
+
    
+
    
+Throws: std::runtime_error if for any reason a reference can not
+be returned to a valid TZ_DB.
+
    
+
    
+
+
    
+The following functions are available only if you compile with the configuration macro
+HAS_REMOTE_API == 1.  Use of this API requires linking to
+libcurl.
+AUTO_DOWNLOAD == 1 requires HAS_REMOTE_API == 1.  You
+will be notified at compile time if AUTO_DOWNLOAD == 1 and
+HAS_REMOTE_API == 0.  If HAS_REMOTE_API == 1, then
+AUTO_DOWNLOAD defaults to 1, otherwise
+AUTO_DOWNLOAD defaults to 0.  On Windows,
+HAS_REMOTE_API defaults to 0.  Everywhere else it
+defaults to 1.  This is because
+libcurl comes preinstalled
+everywhere but Windows, but it is available for Windows.
+
    
+
+
    
+[Note:  Even with AUTO_DOWNLOAD == 1, there are no thread-safety
+issues with this library unless one of the following functions are explicitly
+called by your code:
+
    
+
+
    +const TZ_DB& reload_tzdb();
+bool remote_download(const std::string& version);
+bool remote_install(const std::string& version);
+
    
+
+
    
+Once your program has initialized the TZ_DB singleton, that singleton
+can never be changed without explicit use of reload_tzdb().
+— end note]
+
    
+
+
    
+
+
    +std::string remote_version();
+
    
+
    
+
    
+Returns: The latest database version number from the
+IANA website.  If the
+IANA website can not be reached, or
+if it can be reached but the latest version number is unexpectedly not
+available, the empty string is returned.
+
    
+
    
+Note:  If non-empty, this can be compared with get_tzdb().version to
+discover if you have the latest database installed.
+
    
+
    
+
+
    +bool remote_download(const std::string& version);
+
    
+
    
+
    
+Effects:  If version == remote_version() this function will download
+the compressed tar file holding the latest time zone database from the
+IANA website.  The tar file will be placed
+at the location indicated by the install configuration variable in
+tz.cpp.
+
    
+
    
+Returns:  true if the database was successfully downloaded, else
+false.
+
    
+
    
+Thread safety:  If called by multiple threads, there will be a race on the
+creation of the tar file at install.
+
    
+
    
+
+
    +bool remote_install(const std::string& version);
+
    
+
    
+
    
+Effects:  If version refers to the file successfully
+downloaded by remote_download() this function will remove the
+existing time zone database at install, then extract a new database
+from the tar file and place it at install, and finally will delete
+the tar file.
+
    
+
    
+This function does not cause your program to re-initialize itself from
+this new database.  In order to do that, you must call
+reload_tzdb() (or get_tzdb() if the database has yet
+to be initialized).  If tz.cpp was compiled with
+AUTO_DOWNLOAD == 1, then reload_tzdb() uses this API
+to check if the database is out of date, and reinitializes it with a freshly downloaded
+database only if it needs to.  Indeed, if AUTO_DOWNLOAD == 1 there is
+never any need to call remote_download() or remote_install()
+explicitly.  You can just call reload_tzdb() instead.  This API is
+only exposed so that you can take care of this manually if desired
+(HAS_REMOTE_API == 1 && AUTO_DOWNLOAD == 0).
+
    
+
    
+Returns:  true if the database was successfully replaced by
+the tar file , else false.
+
    
+
    
+Thread safety:  If called by multiple threads, there will be a race on the
+creation of the new database at install.
+
    
+
    
+
+
    
+
+
    
+Everything else in this library concerns read-only access to this
+database, and intuitive ways to compute with that information, even while being
+oblivious to the fact that you are accessing a database.
+
    
+
+
    
+The entire database on disk occupies less than half of the disk space consumed by
+an average Beatles song.  Don't sweat multiple copies of it.  It will easily fit in
+your smart toaster.
+
    
+
+
    
+
+
    choose
    
+
+
    
+
    
+For some conversions from local_time to a sys_time,
+choose::earliest or choose::latest can be used to
+convert a non-existent or ambiguous local_time into a
+sys_time, instead of throwing an exception.
+
    
+
    +enum class choose {earliest, latest};
+
    
+
    
+
+
    nonexistent_local_time
    
+
+
    
+
    
+nonexistent_local_time is thrown when one attempts to convert a
+non-existent local_time to a sys_time without specifying
+choose::earliest or choose::latest.
+
    
+
    +class nonexistent_local_time
+    : public std::runtime_error
+{
+public:
+    // Construction is undocumented
+};
+
    
+
    
+[Example:
+
    
+
    
+
    +#include "tz.h"
+#include <iostream>
+
+int
+main()
+{
+    using namespace date;
+    using namespace std::chrono_literals;
+    try
+    {
+        auto zt = make_zoned("America/New_York", local_days{sun[2]/mar/2016} + 2h + 30min);
+    }
+    catch (const nonexistent_local_time& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+}
+
    
+
    
+Which outputs:
+
    
+
    +2016-03-13 02:30:00 is in a gap between
+2016-03-13 02:00:00 EST and
+2016-03-13 03:00:00 EDT which are both equivalent to
+2016-03-13 07:00:00 UTC
+
    
+
    
+
    
+— end example:]
+
    
+
    
+
+
    ambiguous_local_time
    
+
+
    
+
    
+ambiguous_local_time is thrown when one attempts to convert an ambiguous
+local_time to a sys_time without specifying
+choose::earliest or choose::latest.
+
    
+
    +class ambiguous_local_time
+    : public std::runtime_error
+{
+public:
+    // Construction is undocumented
+};
+
    
+
    
+[Example:
+
    
+
    
+
    +#include "tz.h"
+#include <iostream>
+
+int
+main()
+{
+    using namespace date;
+    using namespace std::chrono_literals;
+    try
+    {
+        auto zt = make_zoned("America/New_York", local_days{sun[1]/nov/2016} + 1h + 30min);
+    }
+    catch (const ambiguous_local_time& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+}
+
    
+
    
+Which outputs:
+
    
+
    +2016-11-06 01:30:00 is ambiguous.  It could be
+2016-11-06 01:30:00 EDT == 2016-11-06 05:30:00 UTC or
+2016-11-06 01:30:00 EST == 2016-11-06 06:30:00 UTC
+
    
+
    
+
    
+— end example:]
+
    
+
    
+
+
    sys_info
    
+
+
    
+
    
+This structure can be obtained from the combination of a time_zone and
+either a sys_time, or local_time.  It can also be obtained
+from a zoned_time which is effectively a pair of
+a time_zone and sys_time.
+
    
+
    
+This structure represents a lower-level API.  Typical conversions from
+sys_time to local_time will use this structure
+implicitly, not explicitly.
+
    
+
    +struct sys_info
+{
+    sys_seconds          begin;
+    sys_seconds          end;
+    std::chrono::seconds offset;
+    std::chrono::minutes save;
+    std::string          abbrev;
+};
+
    
+
    
+The begin and end fields indicate that for the
+associated time_zone and time_point, the
+offset and abbrev are in effect in the range
+[begin, end).  This information can be used to efficiently iterate the
+transitions of a time_zone.
+
    
+
    
+The offset field indicates the UTC offset in effect for the associated
+time_zone and time_point.  The relationship between
+local_time and sys_time is:
+
    
+
    +offset = local_time - sys_time
+
    
+
    
+The save field is "extra" information not normally needed for
+conversion between local_time and sys_time.  If
+save != 0min, this sys_info is said to be on "daylight
+saving" time, and offset - save suggests what this
+time_zone might use if it were off daylight saving. However
+this information should not be taken as authoritative.  The only sure way to get
+such information is to query the time_zone with a
+time_point that returns an sys_info where save ==
+0min.  There is no guarantee what time_point might return such
+an sys_info except that it is guaranteed not to be in the range
+[begin, end) (if save != 0min for this sys_info).
+
    
+
    
+The abbrev field indicates the current abbreviation used for the
+associated time_zone and time_point.  Abbreviations
+are not unique among the time_zones, and so one can not reliably
+map abbreviations back to a time_zone and UTC offset.
+
    
+
    
+You can stream out a sys_info:
+
    
+
    +std::ostream& operator<<(std::ostream& os, const sys_info& r);
+
    
+
    
+
+
    local_info
    
+
+
    
+
    
+This structure represents a lower-level API.  Typical conversions from
+local_time to sys_time will use this structure
+implicitly, not explicitly.
+
    
+
    +struct local_info
+{
+    enum {unique, nonexistent, ambiguous} result;
+    sys_info first;
+    sys_info second;
+};
+
    
+
    
+When a local_time to sys_time conversion is unique,
+result == unique, first will be filled out with the
+correct sys_info and second will be zero-initialized.
+If the conversion stems from a nonexistent local_time then
+result == nonexistent, first will be filled out with
+the sys_info that ends just prior to the local_time
+and second will be filled out with the sys_info that
+begins just after the local_time. If the conversion stems from an
+ambiguous local_time then result == ambiguous,
+first will be filled out with the sys_info that ends
+just after the local_time and second will be filled
+out with the sys_info that starts just before the
+local_time.
+
    
+
    
+You can stream out a local_info:
+
    
+
    +std::ostream& operator<<(std::ostream& os, const local_info& r);
+
    
+
+
    
+
+
    time_zone
    
+
+
    
+
    
+A time_zone represents all time zone transitions for a specific geographic
+area.  time_zone construction is undocumented, and done for you during
+the database initialization.  You can gain const access to a
+time_zone via functions such as locate_zone.
+
    
+
    +class time_zone
+{
+public:
+    time_zone(const time_zone&) = delete;
+    time_zone& operator=(const time_zone&) = delete;
+
+    const std::string& name() const;
+
+    template <class Duration> sys_info   get_info(sys_time<Duration> st) const;
+    template <class Duration> local_info get_info(local_time<Duration> tp) const;
+
+    template <class Duration>
+        sys_time<typename std::common_type<Duration, std::chrono::seconds>::type>
+        to_sys(local_time<Duration> tp) const;
+
+    template <class Duration>
+        sys_time<typename std::common_type<Duration, std::chrono::seconds>::type>
+        to_sys(local_time<Duration> tp, choose z) const;
+
+    template <class Duration>
+        local_time<typename std::common_type<Duration, std::chrono::seconds>::type>
+        to_local(sys_time<Duration> tp) const;
+};
+
+bool operator==(const time_zone& x, const time_zone& y);
+bool operator!=(const time_zone& x, const time_zone& y);
+bool operator< (const time_zone& x, const time_zone& y);
+bool operator> (const time_zone& x, const time_zone& y);
+bool operator<=(const time_zone& x, const time_zone& y);
+bool operator>=(const time_zone& x, const time_zone& y);
+
+std::ostream& operator<<(std::ostream& os, const time_zone& z)
+
    
+
    +const std::string& time_zone::name() const;
+
    
+
    
+
    
+Returns: The name of the time_zone.
+
    
+
    
+Example: "America/New_York".
+
    
+
    
+Note: Here is an unofficial list of time_zone names:
+https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
+
    
+
    
+
+
    +template <class Duration> sys_info time_zone::get_info(sys_time<Duration> st) const;
+
    
+
    
+
    
+Returns: A sys_info i for which st is in the
+range [i.begin, i.end).
+
    
+
    
+
+
    +template <class Duration> local_info time_zone::get_info(local_time<Duration> tp) const;
+
    
+
    
+
    
+Returns: A local_info for tp.
+
    
+
    
+
+
    +template <class Duration>
+sys_time<typename std::common_type<Duration, std::chrono::seconds>::type>
+time_zone::to_sys(local_time<Duration> tp) const;
+
    
+
    
+
    
+Returns: A sys_time that is at least as fine as seconds,
+and will be finer if the argument tp has finer precision.  This
+sys_time is the UTC equivalent of tp according to the rules
+of this time_zone.
+
    
+
    
+Throws: If the conversion from tp to a sys_time
+is ambiguous, throws ambiguous_local_time.  If the conversion from
+tp to a sys_time is nonexistent, throws
+nonexistent_local_time.
+
    
+
    
+
+
    +template <class Duration>
+sys_time<typename std::common_type<Duration, std::chrono::seconds>::type>
+time_zone::to_sys(local_time<Duration> tp, choose z) const;
+
    
+
    
+
    
+Returns: A sys_time that is at least as fine as
+seconds, and will be finer if the argument tp has
+finer precision.  This sys_time is the UTC equivalent of
+tp according to the rules of this time_zone. If the
+conversion from tp to a sys_time is ambiguous, returns
+the earlier sys_time if z == choose::earliest, and
+returns the later sys_time if z == choose::latest. If
+the tp represents a non-existent time between two UTC
+time_points, then the two UTC time_points will be the
+same, and that UTC time_point will be returned.
+
    
+
    
+
+
    +template <class Duration>
+local_time<typename std::common_type<Duration, std::chrono::seconds>::type>
+time_zone::to_local(sys_time<Duration> tp) const;
+
    
+
    
+
    
+Returns: The local_time associated with tp and this
+time_zone.
+
    
+
    
+
+
    +bool operator==(const time_zone& x, const time_zone& y);
+
    
+
    
+
    
+Returns: x.name() == y.name().
+
    
+
    
+
+
    +bool operator!=(const time_zone& x, const time_zone& y);
+
    
+
    
+
    
+Returns: !(x == y).
+
    
+
    
+
+
    +bool operator<(const time_zone& x, const time_zone& y);
+
    
+
    
+
    
+Returns: x.name() < y.name().
+
    
+
    
+
+
    +bool operator>(const time_zone& x, const time_zone& y);
+
    
+
    
+
    
+Returns: y < x.
+
    
+
    
+
+
    +bool operator<=(const time_zone& x, const time_zone& y);
+
    
+
    
+
    
+Returns: !(y < x).
+
    
+
    
+
+
    +bool operator>=(const time_zone& x, const time_zone& y);
+
    
+
    
+
    
+Returns: !(x < y).
+
    
+
    
+
+
    +std::ostream& operator<<(std::ostream& os, const time_zone& z)
+
    
+
    
+
    
+Produces an output that is probably more meaningful to me than it is to you.  I found it
+useful for debugging this library.
+
    
+
    
+
+
    
+
+
    zoned_time
    
+
+
    
+
    
+zoned_time represents a logical paring of time_zone and a
+time_point with precision Duration.  If seconds
+is not implicitly convertible to Duration, the instantiation is ill-formed.
+[Note: There exist time_zones with UTC offsets that require a
+precision of seconds. — end note:] 
+
    
+
+
    +template <class Duration>
+class zoned_time
+{
+    const time_zone*   zone_;  // exposition only
+    sys_time<Duration> tp_;    // exposition only
+
+public:
+    zoned_time(const zoned_time&) = default;
+    zoned_time& operator=(const zoned_time&) = default;
+
+             zoned_time(sys_time<Duration> st);
+    explicit zoned_time(const time_zone* z);
+    explicit zoned_time(const std::string& name);
+
+    template <class Duration2,
+              class = std::enable_if_t
+                      <
+                          std::is_convertible<sys_time<Duration2>,
+                                              sys_time<Duration>>{}
+                      >>
+        zoned_time(const zoned_time<Duration2>& zt) noexcept;
+
+    zoned_time(const time_zone* z,      local_time<Duration> tp);
+    zoned_time(const std::string& name, local_time<Duration> tp);
+    zoned_time(const time_zone* z,      local_time<Duration> tp, choose c);
+    zoned_time(const std::string& name, local_time<Duration> tp, choose c);
+
+    zoned_time(const time_zone* z,      const zoned_time<Duration>& zt);
+    zoned_time(const std::string& name, const zoned_time<Duration>& zt);
+    zoned_time(const time_zone* z,      const zoned_time<Duration>& zt, choose);
+    zoned_time(const std::string& name, const zoned_time<Duration>& zt, choose);
+
+    zoned_time(const time_zone* z,      const sys_time<Duration>& st);
+    zoned_time(const std::string& name, const sys_time<Duration>& st);
+
+    zoned_time& operator=(sys_time<Duration> st);
+    zoned_time& operator=(local_time<Duration> ut);
+
+             operator sys_time<Duration>() const;
+    explicit operator local_time<Duration>() const;
+
+    const time_zone*     get_time_zone() const;
+    local_time<Duration> get_local_time() const;
+    sys_time<Duration>   get_sys_time() const;
+    sys_info             get_info() const;
+};
+
+using zoned_seconds = zoned_time<std::chrono::seconds>;
+
+template <class Duration1, class Duration2>
+bool
+operator==(const zoned_time<Duration1>& x, const zoned_time<Duration2>& y);
+
+template <class Duration1, class Duration2>
+bool
+operator!=(const zoned_time<Duration1>& x, const zoned_time<Duration2>& y);
+
    
+
+
    
+An invariant of zoned_time<Duration> is that it always refers
+to a valid time_zone, and represents a point in time that exists
+and is not ambiguous.
+
    
+
+
    +zoned_time<Duration>::zoned_time(const zoned_time&) = default;
+zoned_time<Duration>& zoned_time<Duration>::operator=(const zoned_time&) = default;
+
    
+
    
+
    
+The copy members transfer the associated time_zone from the source
+to the destination.  After copying, source and destination compare equal.  If
+Duration has noexcept copy members, then
+zoned_time<Duration> has noexcept copy
+members.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(sys_time<Duration> st);
+
    
+
    
+
    
+Effects: Constructs a zoned_time zt such that
+zt.get_time_zone()->name() == "UTC", and
+zt.get_sys_time() == st.
+
    
+
    
+
+
    +explicit zoned_time<Duration>::zoned_time(const time_zone* z);
+
    
+
    
+
    
+Requires: z refers to a valid time_zone.
+
    
+
    
+Effects: Constructs a zoned_time zt such that
+zt.get_time_zone()-> == z, and
+zt.get_sys_time() == sys_seconds{}.
+
    
+
    
+
+
    +explicit zoned_time<Duration>::zoned_time(const std::string& name);
+
    
+
    
+
    
+Effects: Equivalent to construction with locate_zone(name).
+
    
+
    
+Throws: Any exception propagating out of locate_zone(name).
+
    
+
    
+
+
    +template <class Duration2,
+          class = std::enable_if_t
+                  <
+                      std::is_convertible<sys_time<Duration2>,
+                                          sys_time<Duration>>{}
+                  >>
+    zoned_time<Duration>::zoned_time(const zoned_time<Duration2>& y) noexcept;
+
    
+
    
+
    
+Effects: Constructs a zoned_time x such that
+x == y.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const time_zone* z, local_time<Duration> tp);
+
    
+
    
+
    
+Requires: z refers to a valid time_zone.
+
    
+
    
+Effects: Constructs a zoned_time zt such that
+zt.get_time_zone()-> == z, and zt.get_local_time() == tp.
+
    
+
    
+Throws: Any exception that z->to_sys(tp) would throw.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const std::string& name, local_time<Duration> tp);
+
    
+
    
+
    
+Effects: Equivalent to construction with {locate_zone(name), tp}.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const time_zone* z, local_time<Duration> tp, choose c);
+
    
+
    
+
    
+Requires: z refers to a valid time_zone.
+
    
+
    
+Effects: Constructs a zoned_time zt such that
+zt.get_time_zone()-> == z, and
+zt.get_sys_time() == z->to_sys(tp, c).
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const std::string& name, local_time<Duration> tp, choose c);
+
    
+
    
+
    
+Effects: Equivalent to construction with {locate_zone(name), tp, c}.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const time_zone* z, const zoned_time<Duration>& y);
+
    
+
    
+
    
+Requires: z refers to a valid time_zone.
+
    
+
    
+Effects: Constructs a zoned_time zt such that
+zt.get_time_zone()-> == z, and
+zt.get_sys_time() == y.get_sys_time().
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const std::string& name, const zoned_time<Duration>& y);
+
    
+
    
+
    
+Effects: Equivalent to construction with {locate_zone(name), y}.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const time_zone* z, const zoned_time<Duration>& y, choose);
+
    
+
    
+
    
+Requires: z refers to a valid time_zone.
+
    
+
    
+Effects: Constructs a zoned_time zt such that
+zt.get_time_zone()-> == z, and
+zt.get_sys_time() == y.get_sys_time().
+
    
+
    
+Note: The choose parameter is allowed here, but has no impact.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const std::string& name, const zoned_time<Duration>& y, choose);
+
    
+
    
+
    
+Effects: Equivalent to construction with {locate_zone(name), y}.
+
    
+
    
+Note: The choose parameter is allowed here, but has no impact.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const time_zone* z, const sys_time<Duration>& st);
+
    
+
    
+
    
+Requires: z refers to a valid time_zone.
+
    
+
    
+Effects: Constructs a zoned_time zt such that
+zt.get_time_zone()-> == z, and zt.get_sys_time() == st.
+
    
+
    
+
+
    +zoned_time<Duration>::zoned_time(const std::string& name, const sys_time<Duration>& st);
+
    
+
    
+
    
+Effects: Equivalent to construction with {locate_zone(name), st}.
+
    
+
    
+
+
    +zoned_time<Duration>& zoned_time<Duration>::operator=(sys_time<Duration> st);
+
    
+
    
+
    
+Effects: After assignment get_sys_time() == st.  This assignment has
+no effect on the return value of get_time_zone().
+
    
+
    
+Returns: *this.
+
    
+
    
+
+
    +zoned_time<Duration>& zoned_time<Duration>::operator=(local_time<Duration> lt);
+
    
+
    
+
    
+Effects: After assignment get_local_time() == lt.  This assignment has
+no effect on the return value of get_time_zone().
+
    
+
    
+Returns: *this.
+
    
+
    
+
+
    +zoned_time<Duration>::operator sys_time<Duration>() const;
+
    
+
    
+
    
+Returns: get_sys_time().
+
    
+
    
+
+
    +explicit zoned_time<Duration>::operator local_time<Duration>() const;
+
    
+
    
+
    
+Returns: get_local_time().
+
    
+
    
+
+
    +const time_zone* zoned_time<Duration>::get_time_zone() const;
+
    
+
    
+
    
+Returns: zone_.
+
    
+
    
+
+
    +local_time<Duration> zoned_time<Duration>::get_local_time() const;
+
    
+
    
+
    
+Returns: zone_->to_local(tp_).
+
    
+
    
+
+
    +sys_time<Duration> zoned_time<Duration>::get_sys_time() const;
+
    
+
    
+
    
+Returns: tp_.
+
    
+
    
+
+
    +sys_info zoned_time<Duration>::get_info() const;
+
    
+
    
+
    
+Returns: zone_->get_info(tp_).
+
    
+
    
+
+
    +template <class Duration1, class Duration2>
+bool
+operator==(const zoned_time<Duration1>& x, const zoned_time<Duration2>& y);
+
    
+
    
+
    
+Returns: x.zone_ == y.zone_ && x.tp_ == y.tp_.
+
    
+
    
+
+
    +template <class Duration1, class Duration2>
+bool
+operator!=(const zoned_time<Duration1>& x, const zoned_time<Duration2>& y);
+
    
+
    
+
    
+Returns: !(x == y).
+
    
+
    
+
+
    +template 
+std::ostream&
+operator<<(std::ostream& os, const zoned_time& t)
+
    
+
    
+
    
+Effects: Streams t to os using the format "%F %T %Z"
+and the value returned from t.get_local_time().
+
    
+
    
+Returns: os.
+
    
+
    
+
+
    
+
+
    make_zoned
    
+
+
    
+
    
+There exist several overloaded functions named make_zoned
+which serve as factory functions for zoned_time<Duration> and
+will deduce the correct Duration from the argument list.  In every
+case the correct return type is
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>.
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(sys_time<Duration> tp)
+
    
+
    
+
    
+Returns: {tp}.
+
    
+
    
+
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const time_zone* zone, local_time<Duration> tp)
+
    
+
    
+
    
+Returns: {zone, tp}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const std::string& name, local_time<Duration> tp)
+
    
+
    
+
    
+Returns: {name, tp}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const time_zone* zone, local_time<Duration> tp, choose c)
+
    
+
    
+
    
+Returns: {zone, tp, c}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const std::string& name, local_time<Duration> tp, choose c)
+
    
+
    
+
    
+Returns: {name, tp, c}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const time_zone* zone, const zoned_time<Duration>& zt)
+
    
+
    
+
    
+Returns: {zone, zt}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const std::string& name, const zoned_time<Duration>& zt)
+
    
+
    
+
    
+Returns: {name, zt}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const time_zone* zone, const zoned_time<Duration>& zt, choose c)
+
    
+
    
+
    
+Returns: {zone, zt, c}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const std::string& name, const zoned_time<Duration>& zt, choose c)
+
    
+
    
+
    
+Returns: {name, zt, c}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const time_zone* zone, const sys_time<Duration>& st)
+
    
+
    
+
    
+Returns: {zone, st}.
+
    
+
    
+
+
    +template <class Duration>
+zoned_time<std::common_type_t<Duration, std::chrono::seconds>>
+make_zoned(const std::string& name, const sys_time<Duration>& st)
+
    
+
    
+
    
+Returns: {name, st}.
+
    
+
    
+
+
    
+
+
    format
    
+
    
+
    needs documentation
    
+
    
+
+
    parse
    
+
    
+
    needs documentation
    
+
    
+
+
    Leap
    
+
    
+
    needs documentation
    
+
    
+
+
    utc_clock
    
+
    
+
    needs documentation
    
+
    
+
+
    Link
    
+
    
+
    needs documentation
    
+
    
+
 
    Installation
    
 
 
    
@@ -2101,6 +3355,13 @@ Arthur David Olson.  I would also like to thank the entire group of people who c
 maintain it, and especially the IESG-designated TZ Coordinator, Paul Eggert.  Without the
 work of these people, this software would have no data to parse.
 
    
-
+
    
+I would also like to thank Jiangang Zhuang and Bjarne Stroustrup for invaluable feedback
+for the timezone portion of this library, which ended up influencing the date.h library.
+
    
+
    
+And I would also especially like to thank contributors to this library:  gmcode,
+Ivan Pizhenko, tomy2105 and Ville Voutilainen.
+