Time and Date
(ply-system.h)

Plywood provides two families of functions for working with time and dates.

• Unix timestamps are used to obtain the current system time and convert it to a human-readable format.
• The performance timer is used to measure the elapsed time between two points in code. Useful for profiling and animation.

Unix Timestamps

A Unix timestamp is an amount of elapsed time since January 1, 1970 at 00:00 UTC. Plywood uses Unix timestamps even in non-Unix environments such as Windows. These timestamps can be converted to DateTime objects that identify the calendar date and time of day.

s64 getUnixTimestamp()

Returns the current system time as a Unix timestamp in microseconds.

DateTime convertToDateTime(s64 unixTimestamp)
DateTime convertToDateTime(s64 unixTimestamp, s16 timeZoneOffsetInMinutes)

Converts a Unix timestamp to a DateTime object with the following member variables:

s32 year	The calendar year.
u8 month	1..12
u8 day	1..31
u8 weekday	Sunday = 0, Saturday = 6
u8 hour	0..23
u8 minute	0..59
u8 second	0..59
s16 timeZoneOffsetInMinutes	eg. EST = -300
u32 microsecond	0..999999

The same Unix timestamp can produce different DateTime objects depending on the time zone used during conversion. The time zone of each DateTime object is indicated by the timeZoneOffsetInMinutes member and expressed relative to Coordinated Universal Time (UTC). For example, a timeZoneOffsetInMinutes of -300 corresponds to Eastern Standard Time (EST), which is 5 hours behind UTC.

The first form of convertToDateTime uses the local time zone offset as reported by the underlying operating system. The second form accepts timeZoneOffsetInMinutes as an additional argument. If you call the second form, you'll have to determine the time zone offset yourself, since Plywood doesn't provide a way to determine time zone offsets at arbitrary geographic locations.

s64 convertToUnixTimestamp(const DateTime& dateTime)

Converts a DateTime object back to a Unix timestamp.

void printDateTime(Stream& out, StringView format, const DateTime& dateTime)

Prints the contents of a DateTime object as human-readable text. Month and weekday names are output in English only. The format string accepts the following conversion specifiers:

s64 sysTime = getUnixTimestamp();
DateTime dateTime = convertToDateTime(sysTime);
Stream out = getStdOut();
printDateTime(out, "[%Y-%m-%d %H:%M:%S.%L]\n", dateTime);
out.format("The date is {}.\n", String::fromDateTime("%A, %B %e, %Y", dateTime));
out.format("The time is {}.\n", String::fromDateTime("%l:%M %p (UTC%Z)", dateTime));

// Output:
// [2025-12-01 19:00:01.234]
// The date is Monday, December 1, 2025.
// The time is 7:00 PM (UTC-05:00).

Performance Timer

The performance timer takes precise CPU timing measurements. Timestamps are measured in CPU ticks, a system-specific unit of time.

u64 getCpuTicks()

Returns the current timestamp, measured in CPU ticks.

float getCpuTicksPerSecond()

Returns the number of CPU ticks per second on the current system. To measure a time interval in seconds, subtract two timestamps and divide the result by this value.

u64 startTimeStamp = getCpuTicks();
doSomeWork();
u64 endTimeStamp = getCpuTicks();
float duration = (endTimeStamp - startTimeStamp) / getCpuTicksPerSecond();
getStdOut().write("{} seconds elapsed.\n", duration);
// Output: 1.234 seconds elapsed.