32 releases
0.10.0 | Sep 9, 2024 |
---|---|
0.9.0 | Apr 5, 2024 |
0.8.6 | Feb 12, 2024 |
0.8.5 | Dec 29, 2023 |
0.2.4 | Nov 27, 2016 |
#1 in Date and time
2,143,541 downloads per month
Used in 788 crates
(363 directly)
375KB
748 lines
Chrono-TZ
Chrono-TZ
is a library that provides implementors of the TimeZone
trait for chrono. The
impls are generated by a build script using the IANA database
and parse-zoneinfo
.
Documentation
Documentation is hosted on docs.rs
Examples
Create a time in one timezone and convert it to UTC
use chrono::{TimeZone, Utc};
use chrono_tz::US::Pacific;
let pacific_time = Pacific.ymd(1990, 5, 6).and_hms(12, 30, 45);
let utc_time = pacific_time.with_timezone(&Utc);
assert_eq!(utc_time, Utc.ymd(1990, 5, 6).and_hms(19, 30, 45));
Create a naive datetime and convert it to a timezone-aware datetime
use chrono::{TimeZone, NaiveDate};
use chrono_tz::Africa::Johannesburg;
let naive_dt = NaiveDate::from_ymd(2038, 1, 19).and_hms(3, 14, 08);
let tz_aware = Johannesburg.from_local_datetime(&naive_dt).unwrap();
assert_eq!(tz_aware.to_string(), "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.
use chrono::TimeZone;
use chrono_tz::Europe::London;
use chrono_tz::America::New_York;
let london_time = London.ymd(2016, 3, 18).and_hms(3, 0, 0);
let ny_time = london_time.with_timezone(&New_York);
assert_eq!(ny_time, New_York.ymd(2016, 3, 17).and_hms(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.
use chrono::{Duration, TimeZone};
use chrono_tz::Europe::London;
use chrono_tz::OffsetComponents;
let london_time = London.ymd(2016, 5, 10).and_hms(12, 0, 0);
// London typically has zero offset from UTC, but has a 1h adjustment forward
// when summer time is in effect.
assert_eq!(london_time.offset().base_utc_offset(), Duration::hours(0));
assert_eq!(london_time.offset().dst_offset(), Duration::hours(1));
Adding 24 hours across a daylight savings change causes a change in local time
use chrono::{TimeZone, Duration};
use chrono_tz::Europe::London;
let dt = London.ymd(2016, 10, 29).and_hms(12, 0, 0);
let later = dt + Duration::hours(24);
assert_eq!(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
use chrono::TimeZone;
use chrono_tz::Asia::Kolkata;
let dt = Kolkata.ymd(2000, 1, 1).and_hms(0, 0, 0);
let timestamp = dt.timestamp();
assert_eq!(timestamp, 946665000);
Pretty-printing a string will use the correct abbreviation for the timezone
use chrono::TimeZone;
use chrono_tz::Europe::London;
let dt = London.ymd(2016, 5, 10).and_hms(12, 0, 0);
assert_eq!(dt.to_string(), "2016-05-10 12:00:00 BST");
assert_eq!(dt.to_rfc3339(), "2016-05-10T12:00:00+01:00");
You can convert a timezone string to a timezone using the FromStr trait
use chrono::TimeZone;
use chrono_tz::Tz;
use chrono_tz::UTC;
let tz: Tz = "Antarctica/South_Pole".parse().unwrap();
let dt = tz.ymd(2016, 10, 22).and_hms(12, 0, 0);
let utc = dt.with_timezone(&UTC);
assert_eq!(utc.to_string(), "2016-10-21 23:00:00 UTC");
no_std
Support
To use this library without depending on the Rust standard library, put this
in your Cargo.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:
[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.
Limiting the Timezone Table to Zones of Interest
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:
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".
Developing
chrono-tz
uses git submodules, so in order to build locally you will need to
run git submodule init
and git submodule update
.
Future Improvements
- Handle leap seconds
- Handle Julian to Gregorian calendar transitions
- Load tzdata always from latest version
- Dynamic tzdata loading
Dependencies
~1–2MB
~32K SLoC