Crate hourglass [−] [src]
hourglass
provides support for timezone, datetime arithmetic and take care
of subtleties related to time handling, like leap seconds.
Usage
Add the following in your Cargo.toml
:
[dependencies]
hourglass = "0.*"
And put this in your crate root:
extern crate hourglass;
Overview
Timezone
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
:
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:
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).unwrap(); // ... and project it into UTC timezone. let t_utc = t.project(&utc); assert_eq!(t_utc.date(), (2015, 12, 24)); assert_eq!(t_utc.time(), (23, 0, 0, 0));
Arithmetic
Datetime
arithmetic is performed with a Deltatime
. Several granularities
are available when handling Deltatime
and will yield different results:
use hourglass::{Timezone, Deltatime}; let utc = Timezone::utc(); let t = utc.datetime(2015, 6, 30, 0, 0, 0, 0).unwrap(); let t_plus_1_day = t + Deltatime::days(1); let t_plus_86400_sec = t + Deltatime::seconds(86400); assert_eq!(t_plus_1_day.date(), (2015, 7, 1)); // One leap second was inserted this day. assert_eq!(t_plus_86400_sec.date(), (2015, 6, 30)); assert_eq!(t_plus_86400_sec.time(), (23, 59, 60, 0));
Two Datetime
can also be compared:
use hourglass::{Timezone, Deltatime}; let utc = Timezone::utc(); let t0 = utc.datetime(2015, 6, 30, 0, 0, 0, 0).unwrap(); let t1 = utc.datetime(2015, 7, 1, 0, 0, 0, 0).unwrap(); assert_eq!(t0 < t1, true); assert_eq!(t0 >= t1, false); assert_eq!(t1 == t1, true); assert_eq!(t1 - t0, Deltatime::seconds(86401));
Iterators
hourglass
also provides the Every
iterator for scheduling a loop
body execution at regular time interval:
use hourglass::{Timezone, Deltatime, Timespec, Every}; let paris = Timezone::new("Europe/Paris").unwrap(); let until = Timespec::now() + Deltatime::seconds(5); for t in Every::until(Deltatime::seconds(1), until) { println!("it is {} in Paris", t.to_datetime(&paris).format("%H:%M:%S").unwrap()); }
The Range
iterator can be used to iterate over a range of Timespec
:
use hourglass::{Deltatime, Timespec, Range}; let now = Timespec::now(); let then = now + Deltatime::minutes(1); for t in Range::new(now, then, Deltatime::seconds(1)) { println!("tick {}", t.seconds()); }
Structs
Datetime |
A precise point in time along associated to a |
Deltatime |
A delta of time used in |
Every |
An iterator used to schedule execution at regular time interval. |
Range |
An iterator over a period of time. |
Timespec |
An offset from the Unix Epoch. |
Timezone |
A timezone. |
Enums
FmtError |
Possible errors when formatting a |
InputError |
Possible errors when creating a |
TzError |
Possible errors when creating a |