Concept time/date/calendar library for the Janet programming language
The goal is to provide a lightweight library for working with times and dates. "complicated" functionaltiy like localization and time zone handling should be delagated to the operating system or C library when possible.
The functions that perform conversion between time
and datetime
types
all have an optional time zone argument tz
; this argument is a string
with a RFC 2822/ISO 8601 time zone name.
when this argument is not given the functions act on the local time zone.
The following functions all return time as a floating point number:
(time/now)
Read the real time clock. The result is a floating point number indicating the number of seconds since the UNIX epoch.
(time/monotonic)
Get current monotonic time. The result is a floating point number with an undefined epoch that is guarunteed to be monotonic.
(time/cputime)
Get CPU time used by current process. The result is a floating point number indicating the number of seconds the current process has spent executing on the CPU.
(time/to-datetime time &opt tz)
:
Convert a time to a datetime struct.
(time/from-datetime dt &opt tz)
Convert a datetime struct to a time.
(time/format time &opt fmt tz)
Format the given time to ASCII string. The format string is C89 strftime(3) format, or one of the predefined formats:
- :iso-8601
- :rfc-3339
- :rfc-2822
- :w3c
When the fmt
argument is not given, it defaults to the :rfc-2822
format.
(time/parse fmt string &opt tz)
parse a time in the given format. The format string is a subset of the C89 strftime(3) format:
- %Y: year, 4 digits
- %y: year, 2 digits, 2000 is added if the year is less than 70
- %m: month, 2 digits, 01-12
- %d: day, 2 digits, 01-31
- %H: hour, 2 digits, 00-23
- %I: hour, 2 digits, 01-12
- %M: minute, 2 digits, 00-59
- %S: second, 2 digits, 00-59
- %p: AM/PM
or one of the predefined formats:
- :iso-8601
- :rfc-3339
- :rfc-2822
- :w3c
-
clock: some functiality measuring and providing time (typically provided by the OS)
-
clock source: indentifier specifying a source of time:
:monononic-time
,:system-time
,:cpu-time
-
monotonic time: floating point representation of a monotonically increasing time in seconds with no defined epoch.
-
system time: floating point representation of the system clock in seconds, relative to the system time epoch
-
cpu time: floating point representation of the CPU time used by a process or thread.
-
system time epoch: Represents the timestamp of the system time value
0
: equal to the UNIX time epoch: January 1st 1970 00:00:00 UTC. -
interval: the difference between two
monotime
orsystem-time
times, in seconds. -
time zone: a string identifying a world region time zone, for example "GMT", "UTC", "CET", "CET+3", etc. See ISO 8610.
-
datetime: time components: year, month, day-of-month, day-of-year, weekday, hour, minute, second.
-
UTC time: representation of a system time in datetime in Coordinated Universal Time.
-
local time: representation of a system time in datetime in a given time zone.
-
resolution: the smallest interval a given clock source can represent.
The time library should offer the following functionality, properly handling time zones where appropiate:
-
Querying system time, monotonic time and cpu time
-
Breaking down system time to individual datetime components.
-
Composing individual datetime components into a system time.
-
Formatting datetime to human readable format using custom formatting or well-known time formats.
-
Parsing datetime from human readable format using custom formatting or well-known time formats.
-
Basic time arithmatic: adddition and subtraction of system time and datetime
Querying time from a given clock source is provided by the stdlib os/clock
and os/time
functions. These are implemented with the following primitives:
-
Windows: system time:
GetSystemTimeAsFileTime()
, monotonic time:QueryPerformanceCounter()
, cpu time:GetProcessTimes()
-
Apple: system time:
host_get_clock_service()
, monotonic time:host_get_clock_service()
, cpu time:clock()
-
Linux/POSIX: system time:
clock_gettime(CLOCK_REALTIME)
, monotonic time:clock_gettime(CLOCK_MONOTONIC)
, cpu time:clock_gettime(CLOCK_PROCESS_CPUTIME_ID)
Janet already has a representation for broken down time as a date struct
,
https://janet-lang.org/api/index.html#os/date
Reuse this time? It uses a somewhat confusing 0-based indexing for day-of-month and month-of-year though.
Janet provides basic functionality through the C library mktime()
and
timegm()
funcion wrapper os/mktime
. mktime
has no portable way for
handling time zones though.
Janet provides os/date
as a wrapper around the C library localtime()
and
gmtime()
functions. These have no portable way for handling time zones.
I don't even want to think about that. Delegate to C library
See "Localization"
Some thoughts:
-
Implementaion in native Janet janet should be easy for numerical times and dates, but will not support localazation for week and month names.
-
Janet provides a wrapper around the C library
strftime()
function asos/strftime
, which does take care of localzation. -
Time zone handling is not standardized for
strftime()
POSIX defines the strptime()
C function, which parses a struct tm
from a
given time format; this is not available on Windows.
Implementing time parsing in native Janet should not be too hard.