Query Date & Time

Table of Contents

• Query the current date and time
• Extract the date and time components
• Create a date and time
• Notes

FPL provides a couple of functions for querying and constructing calendar date and time values.
A date time is stored in the fplDateTime structure, which holds the Unix epoch (seconds since 1970-01-01), additional milliseconds and the UTC offset in minutes.

Note

Pre-1970 dates are not supported. The epoch field is unsigned and fplDateTimeCreate() rejects any year below 1970.

For pure delta/profiling measurements, use the functions described in Time Measurement & Profiling instead.

Query the current date and time

You can query the current date and time by calling fplDateTimeQuery() and passing a fplDateTimeType value.
Pass fplDateTimeType_UTC to get the time in UTC (+0) or fplDateTimeType_Local to get the local time including the current UTC offset.

// Query the current local date time
fplDateTime now = fplDateTimeQuery(fplDateTimeType_Local);
 
// Query the current UTC date time
fplDateTime utcNow = fplDateTimeQuery(fplDateTimeType_UTC);

The returned fplDateTime is not directly human readable - it stores the epoch, milliseconds and UTC offset only.
To get the individual date and time components, use fplFormatDateTime() (see Extract the date and time components).

Extract the date and time components

To break a fplDateTime into its individual fields (year, month, day, hour, etc.), call fplFormatDateTime() .
It returns a fplDateTimeResult, which contains the year, month, day, hour, minute, second and millisecond.

The fplDateTimeType argument controls whether the components are computed in UTC or local time.

fplDateTime now = fplDateTimeQuery(fplDateTimeType_Local);
 
// Compute the individual components in local time
fplDateTimeResult fields = fplFormatDateTime(now, fplDateTimeType_Local);
 
fplConsoleFormatOut("%04d-%02d-%02d %02d:%02d:%02d.%03d\n",
    fields.year, fields.month, fields.day,
    fields.hour, fields.minute, fields.second, fields.millisecond);

Create a date and time

You can construct a fplDateTime from individual components by calling fplDateTimeCreate() .
It takes the year, month, day, hour, minute, second, millisecond and the UTC offset in minutes.

The result is returned as a fplDateTimeCreationResult. Always check the success field before using the resulting date time.
If the creation fails, the errors field contains a combination of fplDateTimeErrors flags describing which component was invalid.

// Create the date time 2026-05-16 13:45:00.000 in UTC (+0)
fplDateTimeCreationResult result = fplDateTimeCreate(2026, 5, 16, 13, 45, 0, 0, 0);
if (result.success) {
    fplDateTime dateTime = result.dateTime;
    // Do something with the date time
} else {
    if (result.errors & fplDateTimeErrors_InvalidYear) {
        // The year was out of range (expected 1970 or higher)
    }
}

Note

If invalid arguments are passed, an empty date time is returned and success is set to false.

Notes

• The fplDateTime structure is the canonical storage format - convert it with fplFormatDateTime() only when you need the individual fields.
• The utcOffset field is zero when the date time is UTC or +0, otherwise it holds the offset in minutes used to convert back into UTC.
• fplDateTimeQuery() and fplFormatDateTime() are platform functions, while fplDateTimeCreate() is a common function available on all platforms.