https://github.com/zevv/janet-time
https://github.com/zevv/janet-time
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/zevv/janet-time
- Owner: zevv
- Created: 2023-05-28T15:50:27.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-21T14:18:12.000Z (over 2 years ago)
- Last Synced: 2025-12-13T13:17:15.676Z (3 months ago)
- Language: Janet
- Size: 13.7 KB
- Stars: 0
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## Introduction
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.
## API
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.
### Read clock
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.
### Conversion
`(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.
### Formatting and parsing
`(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
## Design considerations and other ramblings
### Basic concepts
- *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` or `system-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.
### Functionality
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*
### Implementation
#### Clocks and sources
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)`
#### *datetime*
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.
#### Composing system time from datetime
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.
#### Splitting system time into datetime
Janet provides `os/date` as a wrapper around the C library `localtime()` and
`gmtime()`
functions. These have no portable way for handling time zones.
### Localization
I don't even want to think about that. Delegate to C library
### Time zones
See "Localization"
#### Time formatting
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 as
`os/strftime`, which does take care of localzation.
- Time zone handling is not standardized for `strftime()`
#### Time parsing
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.