Time handling in GreyCat

Time is a very important concept within GreyCat, as we strive to allow developers an intuitive and fast way to time series data. Towards this goal, the standard library offers a few native types to handle the notion of time.

Time

time is a native concept and represented internally as a primitive signed int64. It is absolute, chronological, and represents the number of microseconds since 01/01/1970 UTC. Timestamps in GreyCat have no explicit timezone and are by the previous definition always given in UTC. The concept of timezone is represented by the native enum TimeZone and is required for some operations on time instances as well as for the conversion to the human-readable Date type. For printing times during development in a human-friendly way, the time::format function can be used.

Name	Symbol	Min	Max	Precision
Time (64 bits)	time	21/12/-290308	10/01/294247	1 microsecond

There are several ways to initialize time in GreyCat:

fn main() {
    var t1 = time::now(); //Current system time
    var t2 = 5_time; //5 microseconds after 01/01/1970
    var t3 = -1000000_time; //1 second before 01/01/1970
    var t4 = time::new(23, DurationUnit::hours); //23 hours after 01/01/1970
    var t5 = time::new(1684163705, DurationUnit::seconds); //If you have the POSIX epoch in seconds
    var t6 = time::parse("07/06/2023 10:57:32", "%d/%m/%Y %H:%M:%S");
    // print formated time
    println(t6.format("%d/%m/%Y %H:%M:%S",TimeZone::"Europe/Luxembourg")); // 07/06/2023 12:57:32, beware timezone shift
}

Since time is represented internally as an int64, it can be compared to another time (absolute order)

if (t5 > t4) {
    //Do something
}

You can also subtract two times and return a duration

var duration = t1 - t2 // duration instance representing the passed time between t1 and t2

To get to a later timestamp, you can add a duration to a time (it is not possible to add two timeinstances together!)

var newT = t1 + 10_s

This syntax allows you to easily manipulate time, a good example of this are for loops with time

for (var t = 0_time; t < 1000_time; t = t + 1_us) {
    //Stuff
}

Date

Since dealing with epoch time is not human friendly, we have the notion of Date. Date exists purely as a human friendly representation of time and should therefore only ever be used for user interaction. Converting time to Date or vice-versa is done like this:

fn main() {
    var t = time::now(); // Current system time
    var date = t.toDate(null); // Date in UTC Timezone
    var dateLux = t.toDate(TimeZone::"Europe/Luxembourg"); // Date in Luxembourg Timezone

    println("Date in UTC: ${date}"); // Date in UTC
    println("Date in Luxembourg: ${dateLux}"); // Date in Luxembourg time

    var convert_back_to_time = date.to_time(null); //Convert date back to time
}

The conversion time to Date is resource intensive, while the conversion Date to time is straightforward

A Date can be created either by converting from time OR by parsing a String with a given format:

fn main() {
    var d1 = Date::from_time(time::now(), TimeZone::"Europe/Luxembourg");
    println(d1); // curent time as date using Lux timezone
    var d2 = Date::parse("07/06/2023 10:57:32", "%d/%m/%Y %H:%M:%S");
    println(d2); // Date{year:2023,month:6,day:7,hour:10,minute:57,second:32,microsecond:0}
}

In addition to to_time, Date also provides the to_nearest_time to gracefully deal with invalid dates. Let’s consider for instance the 30th of March, 2025, that we want to convert to a timestamp in Lebanon:

fn main() {
    var tz = TimeZone::"Asia/Beirut";
    var d = Date::parse("2025-03-30", "%Y-%m-%d");
    var t = d.to_time(tz); // throws an error
    pprint(t);
}

The reason here is the unset fields in the parse method (here hours, minutes, seconds and microseconds), all default to 0, but sharp midnight is not a valid hour in Lebanon on the 30th of March, 2025, as at this exact moment DST makes it jump to 1am instead. To deal with this, you can do:

fn main() {
    var tz = TimeZone::"Asia/Beirut";
    var d = Date::parse("2025-03-30", "%Y-%m-%d");
    var t = d.to_nearest_time(tz);
    pprint(t); // '2025-03-29T22:00:00Z'
}

Note that defaulting to to_nearest_time whenever to_time fails is almost never the way to go. Converting a date to a time in a time zone where the date is invalid should always lead you to question your assumptions first, that had you consider this specific date in this specific time zone.

Date String Format

Both time and Date offer a parse function which expects a String value and optionally a String format. The timezone will default to UTC and the format to ISO 8601. Below an overview of the specifiers that can be used to indicate a different format.

Specifier	Meaning	Example
%d	Day of the month, zero-padded (01-31)	22
%D	Short MM/DD/YY date, equivalent to %m/%d/%y	07/30/09
%e	Day of the month, space-padded ( 1-31)	22
%H	Hour in 24h format (00-23)	16
%I	Hour in 12h format (01-12)	08
%m	Month as a decimal number (01-12)	08
%M	Minute (00-59)	52
%S	Second (00-61)	06
%s	Unix time; the number of seconds since the Unix epoch.	1455803239
%y	Year, last two digits (00-99)	11
%Y	Year	2016

Some examples:

    var d0 = Date::parse("31.01.2022-01:30:30", "%d.%m.%Y-%H:%M:%S") // Date{year:2022,month:1,day:31,hour:1,minute:30,second:30,microsecond:0}
    var d1 = Date::parse("31.01.22-03", "%d.%m.%y-%I"); // Date{year:2022,month:1,day:31,hour:3,minute:0,second:0,microsecond:0}

Duration

Another important concept when manipulating time is duration, it is defined as the span between 2 points in time.

fn main() {
    var t1 = time::new(1684164000, DurationUnit::seconds); //timestamp 1
    var t2 = time::new(1684165000, DurationUnit::seconds); //timestamp 2
    var d = t2 - t1; //d will automatically be a duration
    println(d.to(DurationUnit::seconds)); // Prints the integer number of seconds
    println(d.tof(DurationUnit::hours));  // Prints the fractional number of hours
}

The native unit of duration in GreyCat is microseconds (since time itself is in microseconds), just like time it is represented internally as a primitive signed int64

Some other ways to initialize duration

var d1 = duration::new(5, DurationUnit::microseconds);
var d2 = duration::new(2, DurationUnit::days);         //new is used for int
var d3 = duration::newf(1.5, DurationUnit::years);     //newf is used for float
var d4 = 5.6_s;  // 5.6 seconds duration
var d5 = 7_hour; // 7 hours duration

And like time you can compare them

if(d4 > d5){
 //Stuff
}

You can also subtract and add durations with each other

var d1 = 10_s + 10_s   //20_s
var d2 = 10_s - 5_s   //5_s

DurationUnit and CalendarUnit

GreyCat comes with two enum types to map spans of time to pre-defined units, namely DurationUnit and CalendarUnit.

A DurationUnit simply maps to a fixed number of microseconds and should be used to shift time by this exact fixed quantity. A Duration using a DurationUnit can also be accessed via shorthands as indicated in the table below (where N is the number of units).

DurationUnit	Value in microseconds	Explanation	Shorthand
microseconds	1	lowest GreyCat time precision	N_microseconds OR N_us
milliseconds	1e3	1 thousand microseconds	N_milliseconds OR N_ms
seconds	1e6	1 thousand milliseconds	N_seconds OR N_s
minutes	60e6	60 seconds	N_minutes OR N_m
hours	3600e6	60 minutes	N_hours OR N_h
days	86400e6	24 hours	N_days OR N_d

CalendarUnits are used is as input parameters for functions on time instances with the goal of covering spans of time while respecting the Gregorian calendar (i.e. differing month lengths, leap year) as well as TimeZone specifics (i.e. start/end of day, summer/winter time). The CalendarUnit enum defines the following units:

microseconds
seconds
minutes
hours
days
months
years

Below an overview of the time functions making use of CalendarUnit. All use an optional parameter tz, which indicates the TimeZone and defaults to UTC.

Function Name	What it does
calendar_add	Shift `time`by the indicated value of units. Negative values will shift to the past
calendar_floor	Floor to the first instance of the indicated unit. I.e. floor to years will set to January 1st at 00:00:00:000000.
calendar_ceiling	Ceil to the last instance of the indicated unit. I.e. floor to years will set to December 31st at 23:59:59:999999.