Class Reference time.h

Calendar time and clocks for C++ macros. More...

Member

Detailed Description

Calendar time and clocks for C++ macros. Load with #include or #include (same plugin). Available from LayoutEditor 20260918.

Unix time is a single integer: seconds since 1 January 1970, 00:00:00 UTC. That is what time() returns. To show a date to a human, convert it into a tm (broken-down fields: year, month, day, hour, …) with localtime or gmtime, then format it with strftime.

Several calls differ from desktop C:

• time() takes no argument (not time(NULL)).
• localtime / gmtime copy into a tm you declare: localtime(now, &t) returns 0 on success. They do not return a pointer to hidden library memory.
• strftime(fmt, &t) returns a string (no output buffer).

time_t is treated as int in macros.

Example

#include <time.h>

int main(){
 int now = time();
 tm t;
 if (localtime(now, &t) != 0) return 1;
 string s = strftime("%Y-%m-%d %H:%M:%S", &t);
 cout("local: ", s, "\n");
 cout("hour = ", t.tm_hour, "\n");
}

Type tm

A tm is a structure (a group of named fields). Declare tm t; then fill it with localtime. Fields:

POSIX tm_gmtoff is not bound.

Constants

Member Function Documentation

int time.h::time()

Current calendar time as seconds since 1970-01-01 UTC.

Takes no arguments.

Returns: int — Unix time. Useful as a timestamp or as input to localtime.

double time.h::difftime(int later, int earlier)

Difference between two time() values, in seconds (as a double, so fractions are possible if the values allow it).

Takes later (int), usually the more recent time(), and earlier (int), the older time().

Returns: double — later - earlier in seconds. Can be negative if you swap the arguments.

int time.h::clock()

Processor time used by the program, in ticks. Divide by CLOCKS_PER_SEC to get seconds. This is not wall-clock time; it measures CPU work.

Takes no arguments.

Returns: int — ticks since an unspecified start (often since the macro started). Not comparable across machines without dividing by CLOCKS_PER_SEC.

int time.h::localtime(int t, tm *out)

Converts Unix time t into local time (your timezone) and writes the fields into out.

Takes t (int), value from time(), and out (tm pointer), address of a tm you declared (&t). Must not be omitted.

Returns: 0 on success, -1 on failure.

int time.h::gmtime(int t, tm *out)

Same as localtime, but the result is UTC (no local timezone, no DST).

Takes t (int), Unix time, and out (tm pointer), &t of a tm variable.

Returns: 0 on success, -1 on failure.

int time.h::mktime(tm *t)

Opposite of localtime: takes a filled tm (local time) and returns Unix time. It also normalizes the fields (for example day 32 becomes the next month).

Takes t (tm pointer), pointer to a tm. tm_wday and tm_yday are ignored on input and set on output.

Returns: Unix time (int), or -1 on error / if t is NULL.

string time.h::strftime(string fmt, tm *t)

Builds a human-readable date/time string from a tm using a format string.

Parameters:

• fmt (string) — format. Common pieces:
  • %Y four-digit year
  • %m month 01–12
  • %d day 01–31
  • %H hour 00–23
  • %M minute
  • %S second
  • %Y-%m-%d → 2026-09-16
• t (tm pointer) — &t after localtime or gmtime.

Returns: string — the formatted text (empty on error). Maximum length is 255 characters.

This is not the four-argument C strftime.

string time.h::asctime(tm *t)

Fixed English format: Www Mmm dd hh:mm:ss yyyy\n (for example Wed Sep 16 10:15:00 2026).

Takes t (tm pointer), &t.

Returns: string including a trailing newline. Empty if t is invalid.

Python: import time / datetime. This include is for C++ macros only.