Timezone-aware datetime library for the Rust programming language (doc)
hourglass provides support for timezone, datetime arithmetic and take care
of subtleties related to time handling, like leap seconds.
Add the following in your Cargo.toml:
toml
[dependencies]
hourglass = "0.*"
And put this in your crate root:
rust
extern crate hourglass;
Because a datetime without a timezone is ambiguous and error-prone, hourglass
only exposes a Datetime that is timezone-aware. The creation of a Timezone
is the entry point of the API. hourglass provides several way of creating
a Timezone:
```rust use hourglass::Timezone;
let utc = Timezone::utc(); let local = Timezone::local().unwrap(); let paris = Timezone::new("Europe/Paris").unwrap(); let fixed = Timezone::fixed(-5 * 3600); ```
A Datetime is created for a specific timezone and can be projected in another
timezone:
```rust use hourglass::Timezone;
let utc = Timezone::utc(); let paris = Timezone::new("Europe/Paris").unwrap();
// Create a Datetime corresponding to midnight in Paris timezone...
let t = paris.datetime(2015, 12, 25, 0, 0, 0, 0);
// ... and project it into UTC timezone.
let tutc = t.project(&utc);
asserteq!(tutc.date(), (2015, 12, 24));
asserteq!(t_utc.time(), (23, 0, 0, 0));
```
Datetime arithmetic is performed with a Deltatime. Several granularities
are available when handling Deltatime and will yield different results:
```rust use hourglass::{Timezone, Deltatime};
let utc = Timezone::utc(); let t = utc.datetime(2015, 6, 30, 0, 0, 0, 0); let tplus1day = t + Deltatime::days(1); let tplus86400sec = t + Deltatime::seconds(86400);
asserteq!(tplus1day.date(), (2015, 7, 1)); // One leap second was inserted this day. asserteq!(tplus86400sec.date(), (2015, 6, 30)); asserteq!(tplus86400sec.time(), (23, 59, 60, 0)); ```
Two Datetime can also be compared:
```rust use hourglass::{Timezone, Deltatime};
let utc = Timezone::utc(); let t0 = utc.datetime(2015, 6, 30, 0, 0, 0, 0); let t1 = utc.datetime(2015, 7, 1, 0, 0, 0, 0);
asserteq!(t0 < t1, true); asserteq!(t0 >= t1, false); asserteq!(t1 == t1, true); asserteq!(t1 - t0, Deltatime::seconds(86401)); ```