Crate utc2k

source ·
Expand description

§UTC2K changelog ci
license contributions welcome

UTC2K is a fast and lean date/time library that only cares about UTC happenings in this century (between 2000-01-01 00:00:00 and 2099-12-31 23:59:59).

With that very significant constraint in mind, UTC2K can:

  • Convert to/from Unix timestamps (u32);
  • Convert to/from date strings of the YYYY-MM-DD and YYYY-MM-DD hh:mm:ss varieties;
  • Perform addition/subtraction (in seconds), checked or saturating;
  • Calculate the date’s ordinal;
  • Calculate the number of seconds from midnight;

That’s it!

Compared to more robust libraries like chrono and time, UTC2K can be magnitudes faster, particularly in regards to string parsing and printing.

This library is still a work in progress and there is certainly room to improve performance further.

If you have any suggestions for improvement, feel free to open an issue on Github!


The main date object is Utc2k.

use utc2k::Utc2k;

let date = Utc2k::default(); // 2000-01-01 00:00:00
let date = Utc2k::now(); // The current time.
let date = Utc2k::from(4_102_444_799_u32); // 2099-12-31 23:59:59
let date = Utc2k::new(2010, 10, 31, 15, 30, 0); // 2010-10-31 15:30:00

// String parsing is fallible, but flexible. So long as the numbers we
// need are in the right place, it will be fine. (At least, it won't error
// out; if the date string is trying to communicate a time zone, that won't
// be listened to.)
assert!(Utc2k::try_from("2099-12-31 23:59:59").is_ok()); // Fine.
assert!(Utc2k::try_from("2099-12-31T23:59:59.0000Z").is_ok()); // Also fine.
assert!(Utc2k::try_from("January 1, 2010 @ Eleven O'Clock").is_err()); // Nope!

There is also FmtUtc2k, used for string representation.

use utc2k::{FmtUtc2k, Utc2k};

// You can generate it from an existing Utc2k with either:
assert_eq!(Utc2k::default().formatted(), FmtUtc2k::from(Utc2k::default()));

// You could also skip `Utc2k` and seed directly from a timestamp or date/time
// string.
let fmt = FmtUtc2k::from(4_102_444_799_u32);
let fmt = FmtUtc2k::try_from("2099-12-31 23:59:59").unwrap();

Once you have a FmtUtc2k, you can turn it into a string with:

use utc2k::{FmtUtc2k, Utc2k};
use std::borrow::Borrow;

let fmt = FmtUtc2k::from(4_102_444_799_u32);

let s: &str = &fmt;
let s: &str = fmt.as_ref();
let s: &str = fmt.as_str();
let s: &str = fmt.borrow();

§Optional Crate Features

  • local: Enables the LocalOffset struct. Refer to the documentation for important caveats and limitations.
  • serde: Enables serialization/deserialization support.