Crate astrolabe

source ·
Expand description

Astrolabe is a date and time library for Rust which aims to be feature rich, lightweight (zero dependencies) and easy-to-use. It implements formatting, parsing and manipulating functions for date and time values.

§Features

  • Formatting and parsing with format strings based on Unicode Date Field Symbols
  • RFC 3339 timestamp parsing and formatting
  • Manipulation functions to add, subtract, set and clear date units
  • Cron expression parser
  • Timezone offset
  • Local timezone on UNIX platforms
  • Zero dependencies
  • Serde serializing and deserializing (With feature flag serde)

§Examples

§Basic

A basic example which demonstrates creating, formatting and manipulating a DateTime instance.

use astrolabe::{DateTime, TimeUtilities, Precision};

// Create a DateTime instance from year, month, and days (day of month)
let date_time = DateTime::from_ymd(2022, 5, 2).unwrap();

// Use the format function to freely format your DateTime instance
assert_eq!("2022/05/02", date_time.format("yyyy/MM/dd"));

// Create a new instance with a modified DateTime
// The previous instance is not modified and is still in scope
let modified_dt = date_time.add_hours(11).add_minutes(23);

assert_eq!("2022/05/02 11:23:00", modified_dt.format("yyyy/MM/dd HH:mm:ss"));
assert_eq!("2022-05-02T11:23:00Z", modified_dt.format_rfc3339(Precision::Seconds));

To see all implementations for the DateTime struct, check out it’s documentation.

§Local timezone (UNIX systems only)

Astrolabe can parse the timezone from /etc/localtime to get the local UTC offset. This only works on UNIX systems.

use astrolabe::{DateTime, Offset, OffsetUtilities, Precision};

// Equivalent to `DateTime::now().set_offset(Offset::Local)`
let now = DateTime::now_local();

// Prints for example:
// 2023-10-08T08:30:00+02:00
println!("{}", now.format_rfc3339(Precision::Seconds));
assert_eq!(Offset::Local, now.get_offset());

See Offset

§CRON parsing

use astrolabe::CronSchedule;

// Every 5 minutes
let schedule = CronSchedule::parse("*/5 * * * *").unwrap();
for date in schedule.take(3) {
   println!("{}", date);
}
// Prints for example:
// 2022-05-02 16:15:00
// 2022-05-02 16:20:00
// 2022-05-02 16:25:00

// Every weekday at 10:00
let schedule = CronSchedule::parse("0 10 * * Mon-Fri").unwrap();
for date in schedule.take(3) {
   println!("{}", date.format("yyyy-MM-dd HH:mm:ss eeee"));
}
// Prints for example:
// 2022-05-03 10:00:00 Tuesday
// 2022-05-04 10:00:00 Wednesday
// 2022-05-05 10:00:00 Thursday

See CronSchedule

Modules§

  • errors
    Various error types returned by functions in the astrolabe crate.

Structs§

  • CronSchedule
    A cron expression parser. Implements std::Iterator to generate corresponding DateTime structs.
  • Date
    Date in the proleptic Gregorian calendar.
  • DateTime
    Combined date and time. Date is in the proleptic Gregorian calendar and clock time is with nanosecond precision.
  • Time
    Clock time with nanosecond precision.

Enums§

  • Offset
    Represents an offset from UTC
  • Precision
    Used for specifing the precision for RFC 3339 timestamps.

Traits§