unix-ts: Convertible Unix timestamps for Rust

unix-ts is a library for dealing with timestamps. It supports lightweight creation of timestamps, and conversions into and out of other formats, from integers to chrono DateTime objects.

The goal is to serve as a glue library that can take a timestamp and convert to whatever other formats are needed.

Usage

Add the crate to your Cargo.toml file like usual:

[dependencies]
unix-ts = "0.2"

You can create a timestamp with the ts! macro, which takes the Unix timestamp as an argument:

use unix_ts::ts;

// The argument is the number of seconds since the Unix epoch.
let t = ts!(1335020400);

// Fractional seconds are also allowed.
let t2 = ts!(1335020400.25);

For whole-second timestamps, you can also use the from method:

use unix_ts::Timestamp;

let t = Timestamp::from(1335020400);

For milliseconds, microseconds, or nanoseconds, there are specific from methods available:

use unix_ts::Timestamp;

let t = Timestamp::from_nanos(1335020400_000_000_000i64);

Finally, the new method accepts seconds and nanos. This is generally less convenient than the macro, though, because you have to convert fractional seconds to nanos by yourself.

Reading timestamps

There are three methods available for reading timestamps:

• seconds() -> i64: Returns the whole seconds value of the timestamp.
• at_precision(e) -> i128: Returns the timestamp as an integer at greater precision than the second. The e value represents the power of 10; therefore, at_precision(3) would return the value in milliseconds.
• subsec(e) -> u32: Returns the subsecond value at the given precision. The e value represents the power of 10; therefore, subsec(3) would return the sub-second value in milliseconds.

Converting timestamps

Timestamps can currently be converted into integers (with the loss of the subsecond), or std::time::Duration. This is done by implementing the Rust From trait (so you can use the from or into methods).

If the chrono feature is enabled, unix-ts also supports converting to chrono::DateTime and chrono::NaiveDateTime. This is done through the to_datetime and to_naive_datetime methods. (A to_utc_datetime is also offered to simplify time zone specification for this common case.)

Features

All dependencies outside the standard library are optional, meaning that unix-ts will not force you to also install, for example, chrono (although there is a good chance you should if you are dealing with time).

Optional features:

• chrono: Adds converstion functions to chrono DateTime and NaiveDateTime.