Date & Time

PBDate represents a point in calendar time and time zone, for example 2026-03-12 16:37:07 PDT. PBDateNow returns the current date-and-time and PBDateFmt creates string representations.
PBTime represents a point in system time; a high-resolution timestamp that is monotonically incrementing, used for timing (timers, duration calculations, etc.) PBTimeNow returns the current system time.
PBTimeDuration describes a duration of time, like 134ms. PBTimeDurationFormat can be used to format a human-readable string like "1.2h".

#include <playbit/date.h>

PBDate

typedef struct PBDate {
    PBSysDate  timestamp; // microseconds since 1970-01-01 00:00:00 UTC
    PBTimeZone timeZone;
} PBDate;

PBDate represents a point in "real" time (microseconds since 1970-01-01 00:00:00 UTC.) Range limit: [290309 BCE, Dec 22, 19:59:05 UTC - 294247, Jan 10, 04:00:54 UTC]

PBDateComponents

typedef struct PBDateComponents {
    i32  year;       // e.g. 2026
    u8   month;      // [0-11] 0=January ... 11=December
    bool leapMonth;  // if this month is a leap month or not
    u8   week;       // [0-52]
    u8   day;        // [0-30] 0=first day of month
    u8   weekday;    // [0-6] 0=Sunday ... 6=Saturday
    u8   hour;       // [0-23] e.g. 14
    u8   minute;     // [0-59]
    u8   second;     // [0-59]
    u32  nanosecond; // [0-999999000] remainder of time, not total
} PBDateComponents;

PBDateFormatLayout

typedef enum PBDateFormatLayout {
    PBDateFormatLayout_DEFAULT,   // "2006-01-02 15:04:05 EDT"
    PBDateFormatLayout_DATE_TIME, // "2006-01-02 15:04:05"
    PBDateFormatLayout_DATE,      // "2006-01-02"
    PBDateFormatLayout_TIME,      // "15:04:05"
    PBDateFormatLayout_STAMP,     // "Jan 2 15:04:05.123456"
} PBDateFormatLayout;

PBDateFormat

usize PBDateFormat(PBDate             date,
                   PBDateFormatLayout layout,
                   char*              buf,
                   usize              bufCap);

PBDateFormat writes a string representation of date to buf with the given layout.

bufCap: is the capacity of buf
Returns: the number of bytes that would have been written to buf, excluding a NUL terminator, as if bufCap was infinite.

PBDateComponentsOf

PBDateComponents PBDateComponentsOf(PBDate     date,
                                    PBCalendar calendar);

PBDateComponentsOf returns components of a date interpreted in calendar

PBSysDateMake

PBSysDate PBSysDateMake(i32 year,
                        u32 month,
                        u32 day,
                        u32 hour,
                        u32 minute,
                        u32 second);

PBSysDateMake constructs a PBSysDate timestamp from components, in UTC.

PBSystemClock

PBSysHandle PBSystemClock();

PBSystemClock returns the handle to the system clock (PBSysHandle_INVALID if none)

#include <playbit/timezone.h>

PBTimeZone

typedef struct PBTimeZone {
    u32 id;
} PBTimeZone;

PBTimeZoneOfName

PBTimeZone PBTimeZoneOfName(const char* name);

PBTimeZoneOfName returns a PBTimeZone for the time zone named by IANA identifier name.

Returns: PBTimeZone_NONE if the name is invalid or unknown.

PBTimeZoneDefault

PBTimeZone PBTimeZoneDefault();

PBTimeZoneDefault returns the current default (system) time zone.

PBTimeZoneSetDefault

void PBTimeZoneSetDefault(PBTimeZone tz);

PBTimeZoneSetDefault sets the time zone that is used for new PBDate values, i.e. from calling PBDateNow. If you pass PBTimeZone_NONE, the host system's time zone will be used, effectively "clearing an override."

PBTimeZoneSetDefaultFromSystem

void PBTimeZoneSetDefaultFromSystem();

PBTimeZoneSetDefaultFromSystem sets the time zone that is used for new PBDate values by asking the system what the user's current time zone is.

PBTimeZoneUTCOffset

i64 PBTimeZoneUTCOffset(PBTimeZone tz);

PBTimeZoneUTCOffset returns the standard (non-DST) offset in seconds from UTC.

PBTimeZoneUTCOffset2

i64 PBTimeZoneUTCOffset2(PBTimeZone tz,
                         PBSysDate  timestamp);

PBTimeZoneUTCOffset returns the standard offset in seconds from UTC, accounting for DST.

PBTimeZoneDSTOffset

i64 PBTimeZoneDSTOffset(PBTimeZone tz,
                        PBSysDate  timestamp);

PBTimeZoneDSTOffset returns the daylight-savings time offset for the specified UTC timestamp

PBTimeZoneName

const char* PBTimeZoneName(PBTimeZone tz);

PBTimeZoneName returns the IANA identifier ("" for tz=PBTimeZone_NONE)

PBTimeZoneShortName

const char* PBTimeZoneShortName(PBTimeZone tz);

PBTimeZoneShortName returns an abbreviated name, e.g. "EDT" (Eastern Daylight Time.)

PBTimeZoneShortNameAt

const char* PBTimeZoneShortNameAt(PBTimeZone tz,
                                  PBSysDate  timestamp);

PBTimeZoneShortNameAt returns an abbreviated name at the specified UTC timestamp

#include <playbit/time.h>

PBTime

typedef u64 PBTime;

PBTime is a monotonic clock value; a specific point in time.

Can be used with PB_TIME_ constants to calculate other values, for example:

PBTime value = PBTimeNow();
value + 100*PB_TIME_MILLISECOND; // 100ms in the future
value - 2*PB_TIME_HOUR;          // 2 hours in the past

PBTimeDuration

typedef i64 PBTimeDuration;

PBTimeDuration describes a duration of time, like 134ms or -1.2h

Can be used with PB_TIME_ constants to calculate other values, for example:

PBTimeDuration td = 72 * PB_TIME_HOUR;
td + 100*PB_TIME_MILLISECOND; // 100ms later
td - 2*PB_TIME_HOUR;          // 2 hours sooner

// convert to hours
td / PB_TIME_HOUR;                    // truncation
(td + PB_TIME_HOUR/2) / PB_TIME_HOUR; // integer round-to-nearest
(i64)((f64)td / (f64)PB_TIME_HOUR)    // IEEE-754 round-to-nearest
(f64)td / (f64)PB_TIME_HOUR;

PB_TIME_HOUR

const PBTimeDuration PB_TIME_HOUR = 3600000000000;

PB_TIME_MINUTE

const PBTimeDuration PB_TIME_MINUTE = 60000000000;

PB_TIME_SECOND

const PBTimeDuration PB_TIME_SECOND = 1000000000;

PB_TIME_MILLISECOND

const PBTimeDuration PB_TIME_MILLISECOND = 1000000;

PB_TIME_MICROSECOND

const PBTimeDuration PB_TIME_MICROSECOND = 1000;

PB_TIME_NANOSECOND

const PBTimeDuration PB_TIME_NANOSECOND = 1;

PBTimeNow

PBTime PBTimeNow();

PBTimeNow returns the current system time; the current value of a high-resolution monotonically-incrementing clock with undefined base. If you want to know the "human" time (wall clock / date-time), use PBDateNow instead.

PBTime is compatible with PBTimeDuration, so to make a time in the future, simply add to PBTime, i.e. "10 seconds from now" = PBTimeNow() + 10*PB_TIME_SECOND

PBTimeSince

PBTimeDuration PBTimeSince(PBTime past);

PBTimeSince returns the time delta between now and a point in time in the past

PBTimeUntil

PBTimeDuration PBTimeUntil(PBTime future);

PBTimeUntil returns the time delta between now and a point in time in the future

PBTimeBetween

PBTimeDuration PBTimeBetween(PBTime a,
                             PBTime b);

PBTimeBetween returns the time delta between a and b. i.e.

PBTimeBetween(1, 3) == -2
PBTimeBetween(3, 1) == 2

PBTimeDurationFormat

const char* PBTimeDurationFormat(PBTimeDuration d,
                                 char*          buf);

PBTimeDurationFormat writes a human-readable string like "1.6s" to buf.

Returns: a pointer to beginning of buf.

PBTimeDurationHours

f64 PBTimeDurationHours(PBTimeDuration d);

PBTimeDurationHours converts duration d to hours as floating-point.

PBTimeDurationMinutes

f64 PBTimeDurationMinutes(PBTimeDuration d);

PBTimeDurationMinutes converts duration d to minutes as floating-point.

PBTimeDurationSeconds

f64 PBTimeDurationSeconds(PBTimeDuration d);

PBTimeDurationSeconds converts duration d to seconds as floating-point.

PBTimeDurationMilliseconds

i64 PBTimeDurationMilliseconds(PBTimeDuration d);

PBTimeDurationMilliseconds converts duration d to whole milliseconds.

PBTimeDurationMicroseconds

i64 PBTimeDurationMicroseconds(PBTimeDuration d);

PBTimeDurationMicroseconds converts duration d to whole microseconds.

PBTimeDurationNanoseconds

i64 PBTimeDurationNanoseconds(PBTimeDuration d);

PBTimeDurationNanoseconds converts duration d to whole nanoseconds.

PBTimeTimespec

void PBTimeTimespec(PBTime           t,
                    struct timespec* ts);

PBTimeTimespec populates a timespec struct with the value of t

PBTimeDurationTimespec

void PBTimeDurationTimespec(PBTimeDuration   d,
                            struct timespec* ts);

PBTimeDurationTimespec populates a timespec struct with the value of d

#include <playbit/timer.h>

PBTimer

typedef struct {
    u64 id;
} PBTimer;

PBTimer identifies a timer

PBTimerStart

PBTimer PBTimerStart(PBTime         when,
                     PBTimeDuration repeat,
                     PBTimeDuration leeway,
                     u64            arg1,
                     u64            arg2);

PBTimerStartTimeout

PBTimer PBTimerStartTimeout(PBTimeDuration delay,
                            u64            arg1,
                            u64            arg2);

PBTimerStartTimeout starts a one-shot timer which triggers delay time from now.

PBTimerStartInterval

PBTimer PBTimerStartInterval(PBTimeDuration interval,
                             u64            arg1,
                             u64            arg2);

PBTimerStartInterval starts a repeating timer which triggers interval time from now and then repeats every interval time duration.

PBTimerStop

bool PBTimerStop(PBTimer timer);

PBTimerStop cancels a timer.

Returns: true if timer was stopped, or false if timer is invalid or already stopped.

PBTimerUpdate

void PBTimerUpdate(PBTimer        timer,
                   PBTime         when,
                   PBTimeDuration repeat,
                   PBTimeDuration leeway);

PBTimerUpdate modifies an existing timer with new values

PBTimerSetRepeatRate

void PBTimerSetRepeatRate(PBTimer        timer,
                          PBTimeDuration repeat);

PBTimerSetRepeatRate sets the repeat rate of an existing timer

PBTimerPoll

bool PBTimerPoll(PBTime        now,
                 PBTimerEvent* result);

PBTimerPoll returns an expired timer, a timer which when time has recently passed now.

Returns: false if there are no expired timers.