Chrono-TZ is a library that provides implementors of the
TimeZone trait for rust-chrono. The
impls are generated by a build script using the IANA database
and parse-zoneinfo.
Documentation is hosted on docs.rs
Create a time in one timezone and convert it to UTC
```rust use chrono::{TimeZone, Utc}; use chrono_tz::US::Pacific;
let pacifictime = Pacific.ymd(1990, 5, 6).andhms(12, 30, 45); let utctime = pacifictime.withtimezone(&Utc); asserteq!(utctime, Utc.ymd(1990, 5, 6).andhms(19, 30, 45)); ```
Create a naive datetime and convert it to a timezone-aware datetime
```rust use chrono::{TimeZone, NaiveDate}; use chrono_tz::Africa::Johannesburg;
let naivedt = NaiveDate::fromymd(2038, 1, 19).andhms(3, 14, 08); let tzaware = Johannesburg.fromlocaldatetime(&naivedt).unwrap(); asserteq!(tzaware.tostring(), "2038-01-19 03:14:08 SAST"); ```
London and New York change their clocks on different days in March so only have a 4-hour difference on certain days.
```rust use chrono::TimeZone; use chronotz::Europe::London; use chronotz::America::New_York;
let londontime = London.ymd(2016, 3, 18).andhms(3, 0, 0); let nytime = londontime.withtimezone(&NewYork); asserteq!(nytime, NewYork.ymd(2016, 3, 17).andhms(23, 0, 0)); ```
You can get the raw offsets as well if you want to see the standard
UTC offset as well as any special offsets in effect (such as DST)
at a given time. Note that you need to import the OffsetComponents
trait.
```rust use chrono::{Duration, TimeZone}; use chronotz::Europe::London; use chronotz::OffsetComponents;
let londontime = London.ymd(2016, 5, 10).andhms(12, 0, 0);
// London typically has zero offset from UTC, but has a 1h adjustment forward // when summer time is in effect. asserteq!(londontime.offset().baseutcoffset(), Duration::hours(0)); asserteq!(londontime.offset().dst_offset(), Duration::hours(1)); ```
Adding 24 hours across a daylight savings change causes a change in local time
```rust use chrono::{TimeZone, Duration}; use chrono_tz::Europe::London;
let dt = London.ymd(2016, 10, 29).andhms(12, 0, 0); let later = dt + Duration::hours(24); asserteq!(later, London.ymd(2016, 10, 30).and_hms(11, 0, 0)); ```
And of course you can always convert a local time to a unix timestamp
```rust use chrono::TimeZone; use chrono_tz::Asia::Kolkata;
let dt = Kolkata.ymd(2000, 1, 1).andhms(0, 0, 0); let timestamp = dt.timestamp(); asserteq!(timestamp, 946665000); ```
Pretty-printing a string will use the correct abbreviation for the timezone
```rust use chrono::TimeZone; use chrono_tz::Europe::London;
let dt = London.ymd(2016, 5, 10).andhms(12, 0, 0); asserteq!(dt.tostring(), "2016-05-10 12:00:00 BST"); asserteq!(dt.to_rfc3339(), "2016-05-10T12:00:00+01:00"); ```
You can convert a timezone string to a timezone using the FromStr trait
```rust use chrono::TimeZone; use chronotz::Tz; use chronotz::UTC;
let tz: Tz = "Antarctica/SouthPole".parse().unwrap(); let dt = tz.ymd(2016, 10, 22).andhms(12, 0, 0); let utc = dt.withtimezone(&UTC); asserteq!(utc.to_string(), "2016-10-21 23:00:00 UTC"); ```
no_std SupportTo use this library without depending on the Rust standard library, put this
in your Cargo.toml:
toml
[dependencies]
chrono = { version = "0.4", default-features = false }
chrono-tz = { version = "0.5", default-features = false }
If you are using this library in an environment with limited program space, such as a microcontroller, take note that you will also likely need to enable optimizations and Link Time Optimization: ```toml [profile.dev] opt-level = 2 lto = true
[profile.release] lto = true ```
Otherwise, the additional binary size added by this library may overflow available program space and trigger a linker error.
Chrono-tz by default generates timezones for all entries in the IANA database. If you are
interested in only a few timezones you can use enable the filter-by-regex feature and set an
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
This can significantly reduce the size of the generated database, depending on how many timezones you are interested in. Wikipedia has an article listing the timezone names.
The filtering applied is liberal; if you use a pattern such as "US/.*" then chrono-tz will
include all the zones that are linked, such as "America/Denver", not just "US/Mountain".