# zoneinfo-parse [![Build status](https://travis-ci.org/rust-datetime/zoneinfo-parse.svg)](https://travis-ci.org/rust-datetime/zoneinfo-parse) [![Coverage status](https://coveralls.io/repos/rust-datetime/zoneinfo-parse/badge.svg?branch=master&service=github)](https://coveralls.io/github/rust-datetime/zoneinfo-parse?branch=master)
Rust library for reading the text files comprising the [zoneinfo database][w], 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 former; for the latter, see the [`zoneinfo_compiled` crate][zc] instead.
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 themselves in [the tz repository][tz].
[iana]: https://www.iana.org/time-zones
[tz]: https://github.com/eggert/tz
[w]: https://en.wikipedia.org/wiki/Tz_database
[zc]: https://github.com/rust-datetime/zoneinfo-compiled
### [View the Rustdoc](https://docs.rs/zoneinfo_parse)
## Format
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:00s
0:00 Spain WE%sT 1946 Sep 30
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 1917 only - May 5 23:00s 1:00 S
Rule Spain 1917 1919 - Oct 6 23:00s 0 -
Rule Spain 1918 only - Apr 15 23:00s 1:00 S
Rule Spain 1919 only - Apr 5 23:00s 1:00 S
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 Europe/Prague Europe/Bratislava
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
This crate is used to produce the data for the [`zoneinfo-data` crate](https://github.com/rust-datetime/zoneinfo-data). For an example of its use, see the bundled [data crate builder](https://github.com/rust-datetime/zoneinfo-parse/tree/master/data-crate-builder).