92 lines
4.3 KiB
Markdown
92 lines
4.3 KiB
Markdown
# parse-zoneinfo
|
||
|
||
[![parse-zoneinfo GitHub Actions][gh-image]][gh-checks]
|
||
[![parse-zoneinfo on crates.io][cratesio-image]][cratesio]
|
||
[![parse-zoneinfo on docs.rs][docsrs-image]][docsrs]
|
||
[![Chat][discord-image]][discord]
|
||
|
||
[gh-image]: https://github.com/chronotope/chrono-tz/actions/workflows/rust.yml/badge.svg
|
||
[gh-checks]: https://github.com/chronotope/chrono-tz/actions/workflows/rust.yml
|
||
[cratesio-image]: https://img.shields.io/crates/v/parse-zoneinfo.svg
|
||
[cratesio]: https://crates.io/crates/parse-zoneinfo
|
||
[docsrs-image]: https://docs.rs/parse-zoneinfo/badge.svg
|
||
[docsrs]: https://docs.rs/parse-zoneinfo
|
||
[discord-image]: https://img.shields.io/discord/976380008299917365?logo=discord
|
||
[discord]: https://discord.gg/sXpav4PS7M
|
||
|
||
Rust library for reading the text files comprising the [zoneinfo database], which records time zone changes and offsets across the world from multiple sources.
|
||
|
||
The zoneinfo database is distributed in one of two formats: a raw text format with one file per continent, and a compiled binary format with one file per time zone. This crate deals with the text format.
|
||
|
||
The database itself is maintained by IANA. For more information, see [IANA’s page on the time zone database][iana]. You can also find the text files in [the tz repository][tz].
|
||
|
||
Parse-zoneinfo is a fork of [`zoneinfo_parse`] by Benjamin Sago (now unmaintained). It is used by [`chrono-tz`].
|
||
|
||
[iana]: https://www.iana.org/time-zones
|
||
[tz]: https://github.com/eggert/tz
|
||
[zoneinfo database]: https://en.wikipedia.org/wiki/Tz_database
|
||
[`zoneinfo_parse`]: https://crates.io/crates/zoneinfo_parse
|
||
[`chrono-tz`]: https://crates.io/crates/chrono-tz
|
||
|
||
## Rust version requirements
|
||
|
||
The Minimum Supported Rust Version (MSRV) is currently **Rust 1.57.0**.
|
||
|
||
# Usage
|
||
|
||
The zoneinfo files contains `Zone`, `Rule`, and `Link` information. Each type of line forms a variant in the `line::Line` enum.
|
||
|
||
To get started, here are a few lines representing what time is like in the `Europe/Madrid` time zone:
|
||
```
|
||
# Zone NAME GMTOFF RULES FORMAT [UNTIL]
|
||
Zone Europe/Madrid -0:14:44 - LMT 1901 Jan 1 0:00u
|
||
0:00 Spain WE%sT 1940 Mar 16 23:00
|
||
1:00 Spain CE%sT 1979
|
||
1:00 EU CE%sT
|
||
```
|
||
|
||
The first line is a comment. The second starts with `Zone`, so we know
|
||
|
||
So parsing these five lines would return the five following results:
|
||
|
||
- A `line::Line::Space` for the comment, because the line doesn’t contain any information (but isn’t strictly *invalid* either).
|
||
- A `line::Line::Zone` for the first `Zone` entry. This contains a `Zone` struct that holds the name of the zone. All the other fields are stored in the `ZoneInfo` struct.
|
||
- A `line::Line::Continuation` for the next entry. This is different from the line above as it doesn’t contain a name field; it only has the information in a `ZoneInfo` struct.
|
||
- The fourth line contains the same types of data as the third.
|
||
- As does the fifth.
|
||
|
||
Lines with rule definitions look like this:
|
||
```
|
||
# Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S
|
||
Rule Spain 1918 only - Apr 15 23:00 1:00 S
|
||
Rule Spain 1918 1919 - Oct 6 24:00s 0 -
|
||
Rule Spain 1919 only - Apr 6 23:00 1:00 S
|
||
Rule Spain 1924 only - Apr 16 23:00 1:00 S
|
||
Rule Spain 1924 only - Oct 4 24:00s 0 -
|
||
```
|
||
|
||
All these lines follow the same pattern: A `line::Line::Rule` that contains a `Rule` struct, which has a field for each column of data.
|
||
|
||
Finally, there are lines that link one zone to another’s name:
|
||
```
|
||
# Link TARGET LINK-NAME #= TARGET1
|
||
link Australia/Sydney Australia/ACT #= Australia/Canberra
|
||
```
|
||
|
||
The `Link` struct simply contains the names of both the existing and new time zones.
|
||
|
||
## Interpretation
|
||
|
||
Once the input lines have been parsed, they must be *interpreted* to form a table of time zone data.
|
||
|
||
The easiest way to do this is with a `TableBuilder`. You can add various lines to the builder, and it will throw an error as soon as it detects that something’s wrong, such as a duplicate or a missing entry. When all the lines have been fed to the builder, you can use the `build` method to produce a `Table` containing fields for the rule, zone, and link lines.
|
||
|
||
## Example program
|
||
|
||
The `example` folder of this crate contains a basic parser example.
|
||
|
||
`parse-zoneinfo` is used to produce the data for [`chrono-tz`]. For a full example of its use see [`chrono-tz-build`].
|
||
|
||
[`chrono-tz-build`]: https://github.com/chronotope/chrono-tz/tree/main/chrono-tz-build
|
||
|