From c110f40e76caafbce7fe6ceb59eca498e7c3f8b6 Mon Sep 17 00:00:00 2001 From: Howard Hinnant Date: Mon, 17 Jul 2017 23:05:16 -0400 Subject: [PATCH] Expose a list * Existing API always accesses the front of the list. * Add locate_zone and current_zone member functions to tzdb. * reload_tzdb() pushes a new database to the front of the list. * get_tzdb_list() exposes the list&. --- d0355r4.html | 143 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 88 insertions(+), 55 deletions(-) diff --git a/d0355r4.html b/d0355r4.html index 9058325..8022994 100644 --- a/d0355r4.html +++ b/d0355r4.html @@ -37,7 +37,7 @@ Document number: D0355R4

Howard E. Hinnant
-2017-07-07
+2017-07-17

Extending <chrono> to Calendars and Time Zones

@@ -59,6 +59,7 @@ Document number: D0355R4

Changes since R3

    +
  • Make the database singleton a list<tzdb> instead of a single tzdb.
  • Rewrite in terms of string_view.
  • Improve spec for operator-(const year_month& x, const year_month& y).
  • Refine constraints on conversions from calendar types to sys_days.
    • @@ -1406,6 +1407,7 @@ template<class charT, class traits, class Rep, class Period> struct tzdb; const tzdb& get_tzdb(); +list<TZ_DB*gt;& get_tzdb_list(); const time_zone* locate_zone(string_view tz_name); const time_zone* current_zone(); @@ -9083,46 +9085,34 @@ struct tzdb vector<time_zone> zones; vector<link> links; vector<leap> leaps; + + const time_zone* locate_zone(string_view tz_name) const; + const time_zone* current_zone() const; }; + +list<tzdb>

    -The tzdb 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 can iterate over -and inspect this database. +The list<tzdb> database is a singleton. Access is +granted to it via the get_tzdb_list() function which +returns a reference to it. However this access is only needed for +those applications which need to have long uptimes and have a need to +update the time zone database while running. Other applications can +implicitly access the front() of this list via the +read-only namespace scope functions get_tzdb(), +locate_zone() and current_zone(). Each +vector in tzdb is sorted to enable fast +lookup. You can iterate over and inspect this database. And even +hold multiple versions of the database at once, via the +list<tzdb>. 

    -const tzdb& get_tzdb();
+const time_zone* tzdb::locate_zone(string_view tz_name) const;

    -Effects: If this is the first access to the database, will initialize -the database. -

    -

    -Returns: A const reference to the database. -

    -

    -Thread Safety: It is safe to call this function from multiple threads at -one time. -

    -

    -Throws: runtime_error if for any reason a reference can not -be returned to a valid tzdb. -

    -
    - -
    -const time_zone* locate_zone(string_view 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(), @@ -9131,11 +9121,66 @@ then a pointer is returned to the time_zone for which 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 runtime_error. [Note: -On non-exceptional return, the return value is always a pointer to a -valid time_zone. — end note] +Throws: If a const time_zone* can not be found as +described in the Returns clause, throws a +runtime_error. [Note: On non-exceptional return, +the return value is always a pointer to a valid +time_zone. — end note] +

    +
    + +
    +const time_zone* tzdb::current_zone() const;
+
    +
    +

    +Returns: A const time_zone* referring to the time zone which your +computer has set as its local time zone. +

    +
    + +
    +list<tzdb>& get_tzdb_list();
+
    +
    +

    +Effects: If this is the first access to the database, will +initialize the database. If this call initializes the database, the +resulting database will be a list<tzdb> with +size() == 1. +

    +

    +Returns: A reference to the database. +

    +

    +Thread Safety: It is safe to call this function from multiple threads at +one time. +

    +

    +Throws: runtime_error if for any reason a +reference can not be returned to a valid +list<tzdb>& containing one or more valid +tzdb. +

    +
    + +
    +const tzdb& get_tzdb();
+
    +
    +

    +Returns: get_tzdb_list().front(). +

    +
    + +
    +const time_zone* locate_zone(string_view tz_name);
+
    +
    +

    +Returns: get_tzdb().locate_zone(tz_name) which +will initialize the timezone database if this is the first reference +to the database.

    @@ -9144,23 +9189,13 @@ 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] +Returns: get_tzdb().current_zone().

    +

    Back to TOC

    -

    23.17.12.1.1 Remote time zone database support [time.timezone.database.remote]

    @@ -9177,19 +9212,17 @@ const tzdb& reload_tzdb(); 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 tzdb singleton from the new disk files. +is available. It is downloaded and installed, and then the program initializes +a new tzdb from the new disk files and pushes it to the front of +the list<tzdb>& accessed by get_tzdb_list().

    -Returns: A const reference to the database. +Returns: get_tzdb_list().front().

    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, all outstanding -const time_zone* are invalidated (including those held within -zoned_time objects). And afterwards, all outstanding -sys_info may hold obsolete data. +to safely use this function.

    Throws: runtime_error if for any reason a reference can not