cppdraft_translate/cppdraft/time/zone/db.md

[time.zone.db]

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

## 30.11 Time zones [[time.zone]](time.zone#db)

### 30.11.2 Time zone database [time.zone.db]

#### [30.11.2.1](#tzdb) Class tzdb [[time.zone.db.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](#tzdb-1)

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

Each vector in a tzdb object
is sorted to enable fast lookup[.](#tzdb-1.sentence-1)

[🔗](#lib:locate_zone,tzdb)

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

[2](#tzdb-2)

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

*Returns*: 

- [(2.1)](#tzdb-2.1)

If zones contains an element tz for which tz.name() == tz_name,
a pointer to tz;

- [(2.2)](#tzdb-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()[.](#tzdb-2.sentence-1)

[*Note [1](#tzdb-note-1)*:

A time_zone_link specifies an alternative name for a time_zone[.](#tzdb-2.sentence-2)

— *end note*]

[3](#tzdb-3)

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

*Throws*: If a const time_zone* cannot be found
as described in the *Returns*: element,
throws a runtime_error[.](#tzdb-3.sentence-1)

[*Note [2](#tzdb-note-2)*:

On non-exceptional return, the return value is always a pointer to a valid time_zone[.](#tzdb-3.sentence-2)

— *end note*]

[🔗](#lib:current_zone,tzdb)

`const time_zone* current_zone() const;
`

[4](#tzdb-4)

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

*Returns*: A pointer to the time zone which the computer has set as its local time zone[.](#tzdb-4.sentence-1)

#### [30.11.2.2](#list) Class tzdb_list [[time.zone.db.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 constructorsclass 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](#list-1)

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

The tzdb_list database is a singleton;
the unique object of type tzdb_list can be
accessed via the get_tzdb_list() function[.](#list-1.sentence-1)

[*Note [1](#list-note-1)*:

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[.](#list-1.sentence-2)

Other applications can implicitly access the front() of this list
via the read-only namespace scope functionsget_tzdb(),locate_zone(), andcurrent_zone()[.](#list-1.sentence-3)

— *end note*]

The tzdb_list object contains a list of tzdb objects[.](#list-1.sentence-4)

[2](#list-2)

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

tzdb_list​::​const_iterator is a constant iterator
which meets the [*Cpp17ForwardIterator*](forward.iterators#:Cpp17ForwardIterator "24.3.5.5 Forward iterators [forward.iterators]") requirements
and has a value type of tzdb[.](#list-2.sentence-1)

[🔗](#lib:front,tzdb_list)

`const tzdb& front() const noexcept;
`

[3](#list-3)

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

*Synchronization*: This operation is thread-safe with respect to reload_tzdb()[.](#list-3.sentence-1)

[*Note [2](#list-note-2)*:

reload_tzdb() pushes a new tzdb onto the front of this container[.](#list-3.sentence-2)

— *end note*]

[4](#list-4)

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

*Returns*: A reference to the first tzdb in the container[.](#list-4.sentence-1)

[🔗](#lib:erase_after,tzdb_list)

`const_iterator erase_after(const_iterator p);
`

[5](#list-5)

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

*Preconditions*: The iterator following p is dereferenceable[.](#list-5.sentence-1)

[6](#list-6)

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

*Effects*: Erases the tzdb referred to by the iterator following p[.](#list-6.sentence-1)

[7](#list-7)

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

*Postconditions*: No pointers, references, or iterators are invalidated
except those referring to the erased tzdb[.](#list-7.sentence-1)

[*Note [3](#list-note-3)*:

It is not possible to erase the tzdb referred to by begin()[.](#list-7.sentence-2)

— *end note*]

[8](#list-8)

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

*Returns*: An iterator pointing to the element following the one that was erased,
or end() if no such element exists[.](#list-8.sentence-1)

[9](#list-9)

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

*Throws*: Nothing[.](#list-9.sentence-1)

[🔗](#lib:begin,tzdb_list)

`const_iterator begin() const noexcept;
`

[10](#list-10)

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

*Returns*: An iterator referring to the first tzdb in the container[.](#list-10.sentence-1)

[🔗](#lib:end,tzdb_list)

`const_iterator end() const noexcept;
`

[11](#list-11)

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

*Returns*: An iterator referring to the position one past the last tzdb in the container[.](#list-11.sentence-1)

[🔗](#lib:cbegin,tzdb_list)

`const_iterator cbegin() const noexcept;
`

[12](#list-12)

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

*Returns*: begin()[.](#list-12.sentence-1)

[🔗](#lib:cend,tzdb_list)

`const_iterator cend() const noexcept;
`

[13](#list-13)

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

*Returns*: end()[.](#list-13.sentence-1)

#### [30.11.2.3](#access) Time zone database access [[time.zone.db.access]](time.zone.db.access)

[🔗](#lib:get_tzdb_list)

`tzdb_list& get_tzdb_list();
`

[1](#access-1)

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

*Effects*: If this is the first access to the time zone database,
initializes the database[.](#access-1.sentence-1)

If this call initializes the database,
the resulting database will be a tzdb_list holding a single initialized tzdb[.](#access-1.sentence-2)

[2](#access-2)

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

*Synchronization*: It is safe to call this function from multiple threads at one time[.](#access-2.sentence-1)

[3](#access-3)

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

*Returns*: A reference to the database[.](#access-3.sentence-1)

[4](#access-4)

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

*Throws*: runtime_error if for any reason
a reference cannot be returned to a valid tzdb_list containing one or more valid tzdbs[.](#access-4.sentence-1)

[🔗](#lib:get_tzdb)

`const tzdb& get_tzdb();
`

[5](#access-5)

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

*Returns*: get_tzdb_list().front()[.](#access-5.sentence-1)

[🔗](#lib:locate_zone)

`const time_zone* locate_zone(string_view tz_name);
`

[6](#access-6)

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

*Returns*: get_tzdb().locate_zone(tz_name)[.](#access-6.sentence-1)

[7](#access-7)

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

[*Note [1](#access-note-1)*:

The time zone database will be initialized
if this is the first reference to the database[.](#access-7.sentence-1)

— *end note*]

[🔗](#lib:current_zone)

`const time_zone* current_zone();
`

[8](#access-8)

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

*Returns*: get_tzdb().current_zone()[.](#access-8.sentence-1)

#### [30.11.2.4](#remote) Remote time zone database support [[time.zone.db.remote]](time.zone.db.remote)

[1](#remote-1)

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

The local time zone database
is that supplied by the implementation
when the program first accesses the database,
for example via current_zone()[.](#remote-1.sentence-1)

While the program is running,
the implementation may choose to update the time zone database[.](#remote-1.sentence-2)

This update shall not impact the program in any way
unless the program calls the functions in this subclause[.](#remote-1.sentence-3)

This potentially updated time zone database
is referred to as the [*remote time zone database*](#def:remote_time_zone_database "30.11.2.4 Remote time zone database support [time.zone.db.remote]")[.](#remote-1.sentence-4)

[🔗](#lib:reload_tzdb)

`const tzdb& reload_tzdb();
`

[2](#remote-2)

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

*Effects*: This function first checks
the version of the remote time zone database[.](#remote-2.sentence-1)

If the versions of the local and remote databases are the same,
there are no effects[.](#remote-2.sentence-2)

Otherwise the remote database is pushed
to the front of the tzdb_list accessed by get_tzdb_list()[.](#remote-2.sentence-3)

[3](#remote-3)

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

*Synchronization*: This function is thread-safe with respect toget_tzdb_list().front() and get_tzdb_list().erase_after()[.](#remote-3.sentence-1)

[4](#remote-4)

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

*Postconditions*: No pointers, references, or iterators are invalidated[.](#remote-4.sentence-1)

[5](#remote-5)

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

*Returns*: get_tzdb_list().front()[.](#remote-5.sentence-1)

[6](#remote-6)

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

*Throws*: runtime_error if for any reason
a reference cannot be returned to a valid tzdb[.](#remote-6.sentence-1)

[🔗](#lib:remote_version)

`string remote_version();
`

[7](#remote-7)

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

*Returns*: The latest remote database version[.](#remote-7.sentence-1)

[*Note [1](#remote-note-1)*:

This can be compared with get_tzdb().version to discover if the local and remote databases are equivalent[.](#remote-7.sentence-2)

— *end note*]