Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme #177

Merged
merged 10 commits into from
Apr 23, 2024
17 changes: 5 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# Chrono-TZ

`Chrono-TZ` is a library that provides implementors of the
[`TimeZone`][timezone] trait for [`rust-chrono`][chrono]. The
impls are generated by a build script using the [`IANA database`][iana]
and [`parse-zoneinfo`][parse_zoneinfo].
`Chrono-TZ` is a library that provides implementors of the [`TimeZone`] trait for [chrono]. The
djc marked this conversation as resolved.
Show resolved Hide resolved
impls are generated by a build script using the [`IANA database`][iana] and [`parse-zoneinfo`].

[chrono]: https://github.com/lifthrasiir/rust-chrono
[timezone]: https://lifthrasiir.github.io/rust-chrono/chrono/offset/trait.TimeZone.html
[chrono]: https://crates.io/crates/chrono
[`TimeZone`]: https://docs.rs/chrono/latest/chrono/trait.TimeZone.html
[iana]: http://www.iana.org/time-zones
[parse_zoneinfo]: https://github.com/djzin/parse-zoneinfo
[`parse-zoneinfo`]: https://crates.io/crates/parse-zoneinfo

## Documentation

Expand Down Expand Up @@ -152,11 +150,6 @@ environment variable to select them. The environment variable is called
`CHRONO_TZ_TIMEZONE_FILTER` and is a regular expression. It should be specified in your top-level
build:

```toml
[dependencies]
chrono-tz = { version = "0.6", features = [ "filter-by-regex" ] }
```

```sh
CHRONO_TZ_TIMEZONE_FILTER="(Europe/London|US/.*)" cargo build
```
Expand Down
67 changes: 33 additions & 34 deletions parse-zoneinfo/README.md
Original file line number Diff line number Diff line change
@@ -1,42 +1,35 @@
# parse-zoneinfo

Parse-zoneinfo is a fork of [`zoneinfo_parse`][zoneinfo_parse], with adjustments such that it no longer depends on the `Datetime` crate. It is used by [`chrono-tz`][chrono_tz].
Rust library for reading the text files comprising the [zoneinfo database], which records time zone changes and offsets across the world from multiple sources.
djc marked this conversation as resolved.
Show resolved Hide resolved

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 text format.

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 in [the tz repository][tz].

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].
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
[w]: https://en.wikipedia.org/wiki/Tz_database
[zc]: https://github.com/rust-datetime/zoneinfo-compiled
[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

### [View the Rustdoc](https://docs.rs/parse-zoneinfo)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably add back a bunch of badges like we have in the chrono README. Having a link to the docs is actually useful.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is something I also wanted to see and forgot about! I'll open a fresh PR for that.

## Rust version requirements

# Installation

This crate works with [Cargo](https://crates.io). Add the following to your `Cargo.toml` dependencies section:

```toml
[dependencies]
parse-zoneinfo = "0.5"
```

The earliest version of Rust that this crate is tested against is [Rust v1.31.0](https://blog.rust-lang.org/2018/12/06/Rust-1.31-and-rust-2018.html).
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:00s
0:00 Spain WE%sT 1946 Sep 30
1:00 Spain CE%sT 1979
1:00 EU CE%sT
```
# 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

Expand All @@ -49,30 +42,36 @@ So parsing these five lines would return the five following results:
- 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
```
# 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 Europe/Prague Europe/Bratislava
```
# 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`].

## Example program
[`chrono-tz-build`]: https://github.com/chronotope/chrono-tz/tree/main/chrono-tz-build

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).
Loading