27 Time library [time]

27.11 Time zones [time.zone]

27.11.2 Time zone database [time.zone.db]

27.11.2.1 Class tzdb [time.zone.db.tzdb]

namespace std::chrono {
  struct tzdb {
    string                 version;
    vector<time_zone>      zones;
    vector<time_zone_link> links;
    vector<leap_second>    leap_seconds;

    const time_zone* locate_zone(string_view tz_name) const;
    const time_zone* current_zone() const;
  };
}
1
#
Each vector in a tzdb object is sorted to enable fast lookup.
🔗
const time_zone* locate_zone(string_view tz_name) const;
2
#
Returns:
  • (2.1)
    If zones contains an element tz for which tz.name() == tz_­name, a pointer to tz;
  • (2.2)
    otherwise, if links contains an element tz_­l for which tz_­l.name() == tz_­name, then a pointer to the element tz of zones for which tz.name() == tz_­l.target().
[Note
:
A time_­zone_­link specifies an alternative name for a time_­zone.
— end note
]
3
#
Throws: If a const time_­zone* cannot 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* current_zone() const;
4
#
Returns: A pointer to the time zone which the computer has set as its local time zone.

27.11.2.2 Class tzdb_­list [time.zone.db.list]

namespace std::chrono {
  class tzdb_list {
  public:
    tzdb_list(const tzdb_list&) = delete;
    tzdb_list& operator=(const tzdb_list&) = delete;

    // unspecified additional constructors

    class const_iterator;

    const tzdb& front() const noexcept;

    const_iterator erase_after(const_iterator p);

    const_iterator begin() const noexcept;
    const_iterator end()   const noexcept;

    const_iterator cbegin() const noexcept;
    const_iterator cend()   const noexcept;
  };
}
1
#
The tzdb_­list database is a singleton; the unique object of type tzdb_­list can be accessed via the get_­tzdb_­list() function.
[Note
:
This access is only needed for those applications that 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().
— end note
]
The tzdb_­list object contains a list of tzdb objects.
2
#
tzdb_­list​::​const_­iterator is a constant iterator which meets the Cpp17ForwardIterator requirements and has a value type of tzdb.
🔗
const tzdb& front() const noexcept;
3
#
Synchronization: This operation is thread-safe with respect to reload_­tzdb().
[Note
:
reload_­tzdb() pushes a new tzdb onto the front of this container.
— end note
]
4
#
Returns: A reference to the first tzdb in the container.
🔗
const_iterator erase_after(const_iterator p);
5
#
Preconditions: The iterator following p is dereferenceable.
6
#
Effects: Erases the tzdb referred to by the iterator following p.
7
#
Returns: An iterator pointing to the element following the one that was erased, or end() if no such element exists.
8
#
Postconditions: No pointers, references, or iterators are invalidated except those referring to the erased tzdb.
[Note
:
It is not possible to erase the tzdb referred to by begin().
— end note
]
9
#
Throws: Nothing.
🔗
const_iterator begin() const noexcept;
10
#
Returns: An iterator referring to the first tzdb in the container.
🔗
const_iterator end() const noexcept;
11
#
Returns: An iterator referring to the position one past the last tzdb in the container.
🔗
const_iterator cbegin() const noexcept;
12
#
Returns: begin().
🔗
const_iterator cend() const noexcept;
13
#
Returns: end().

27.11.2.3 Time zone database access [time.zone.db.access]

🔗
tzdb_list& get_tzdb_list();
1
#
Effects: If this is the first access to the time zone database, initializes the database.
If this call initializes the database, the resulting database will be a tzdb_­list holding a single initialized tzdb.
2
#
Synchronization: It is safe to call this function from multiple threads at one time.
3
#
Returns: A reference to the database.
4
#
Throws: runtime_­error if for any reason a reference cannot be returned to a valid tzdb_­list containing one or more valid tzdbs.
🔗
const tzdb& get_tzdb();
5
#
Returns: get_­tzdb_­list().front().
🔗
const time_zone* locate_zone(string_view tz_name);
6
#
Returns: get_­tzdb().locate_­zone(tz_­name).
7
#
[Note
:
The time zone database will be initialized if this is the first reference to the database.
— end note
]
🔗
const time_zone* current_zone();
8
#
Returns: get_­tzdb().current_­zone().

27.11.2.4 Remote time zone database support [time.zone.db.remote]

1
#
The local time zone database is that supplied by the implementation when the program first accesses the database, for example via current_­zone().
While the program is running, the implementation may choose to update the time zone database.
This update shall not impact the program in any way unless the program calls the functions in this subclause.
This potentially updated time zone database is referred to as the remote time zone database.
🔗
const tzdb& reload_tzdb();
2
#
Effects: This function first checks the version of the remote time zone database.
If the versions of the local and remote databases are the same, there are no effects.
Otherwise the remote database is pushed to the front of the tzdb_­list accessed by get_­tzdb_­list().
3
#
Synchronization: This function is thread-safe with respect to get_­tzdb_­list().front() and get_­tzdb_­list().erase_­after().
4
#
Postconditions: No pointers, references, or iterators are invalidated.
5
#
Returns: get_­tzdb_­list().front().
6
#
Throws: runtime_­error if for any reason a reference cannot be returned to a valid tzdb.
🔗
string remote_version();
7
#
Returns: The latest remote database version.
[Note
:
This can be compared with get_­tzdb().version to discover if the local and remote databases are equivalent.
— end note
]