Kōtuku Manual

Simplifies the management of date/time information.

The Time class is available for programs that require time and date management in a multi-platform manner.

To get the current system time, use the Query() action.

Structure

The Time class consists of the following fields:

Access	Name	Type	Comment
	Day	INT	Day (1 - 31)
	DayOfWeek	INT	Day of week (0 - 6) starting from Sunday.
	Hour	INT	Hour (0 - 23)
	MicroSecond	INT	A microsecond is one millionth of a second (0 - 999999)
	MilliSecond	INT	A millisecond is one thousandth of a second (0 - 999)
	Minute	INT	Minute (0 - 59)
	Month	INT	Month (1 - 12)
	Second	INT	Second (0 - 59)
	SystemTime	INT64	Represents the system time when the time object was last queried.
The SystemTime field returns the system time if the Time object has been queried. The time is represented in microseconds. This field serves no purpose beyond its initial query value.
	Timestamp	INT64	Read this field to get representation of the time as a single integer.
The Timestamp field is a 64-bit integer that represents the time object as an approximation of the number of milliseconds represented in the time object (approximately the total amount of time passed since Zero-AD). This is convenient for summarising a time value for comparison with other time stamps, or for storing time in a 64-bit space. The Timestamp value is dynamically calculated when reading this field.
	Year	INT	Year (-ve for BC, +ve for AD).

Actions

The following actions are currently supported:

	Query	Updates the values in a time object with the current system date and time.
	Refresh	Refreshes the state of an object.

Methods

The following methods are currently supported:

GetTimeZoneInfo Returns time-zone metadata and transition records.

ERR pt::GetTimeZoneInfo(OBJECTPTR Object, STRVIEW ZoneID, INT StartYear, INT EndYear, struct TimeZoneInfo ** Info)

Parameter	Description
ZoneID	Zone identifier, or an empty string to request the local system zone.
StartYear	Inclusive first year. Must be in the supported 1601-9999 range.
EndYear	Inclusive final year. Must be >= StartYear, no later than 9999 and within 400 years of `StartYear`.
Info	Receives the allocated metadata and transition resource. Release with FreeResource() when no longer required.

Returns normalised time-zone information for a named zone or for the host system's local zone. The returned TimeZoneInfo resource includes the preferred public zone identifier, the host-native identifier, the data source, standard UTC offset and any transition records found within the requested inclusive year range.

The ZoneID value may be empty to request the local system zone. Explicit zone IDs support UTC aliases on all platforms. Linux builds also accept IANA zone names that resolve under /usr/share/zoneinfo. Windows builds accept Windows native time-zone IDs and the IANA IDs that are mapped by the Core Windows time-zone wrapper.

For explicit zone requests, an unknown or unsupported ID returns ERR::Search. For local-zone requests, host lookup failure is not fatal; the method returns a UTC result with Source set to utc and IsFallback set to 1.

Transition Instant values are UTC Unix epoch timestamps in microseconds. OffsetBefore, OffsetAfter and BaseOffset are expressed in seconds east of UTC. DaylightSaving is 1 when the transition enters a daylight-saving period.

Error Codes

Okay	Time-zone information was returned. Local-zone failures may return a UTC fallback result.
Search	An explicit zone ID could not be resolved.
OutOfRange	A value is outside of the valid range
AllocMemory	Failed to create a new memory block
SystemCall	A required host time-zone API call failed.
NullArgs	Function call missing argument value(s)

SetTime Apply the time to the system clock.

ERR pt::SetTime(OBJECTPTR Object)

This method will apply the time object's values to the BIOS. Depending on the host platform, this method may only work if the user is logged in as the administrator.

Field	Type	Description
ZoneID	STRING	Preferred public ID, e.g. Europe/London or UTC.
NativeID	STRING	Host-native ID, e.g. GMT Standard Time on Windows.
Source	STRING	"tzif", "win32", or "utc".
DataPath	STRING	TZif path on Linux, otherwise empty.
Version	STRING	TZDB/source version if available, otherwise empty.
Transitions	kt::vector<TimeZoneTransition>	Transitions available for the requested range.
BaseOffset	INT	Standard UTC offset in seconds.
StartYear	INT16	Inclusive requested start year.
EndYear	INT16	Inclusive requested end year.
IsLocal	INT8	1 if ZoneID requested the local system zone.
IsFallback	INT8	1 if UTC fallback was used.

Time Class

Structure

Actions

Methods

TimeZoneInfo Structure