{"id":18014813,"url":"https://github.com/zevv/janet-time","last_synced_at":"2026-03-19T02:53:48.763Z","repository":{"id":170417532,"uuid":"646501979","full_name":"zevv/janet-time","owner":"zevv","description":null,"archived":false,"fork":false,"pushed_at":"2023-09-21T14:18:12.000Z","size":14,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-12-13T13:17:15.676Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Janet","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zevv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-28T15:50:27.000Z","updated_at":"2023-05-28T19:03:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"6915c9ee-e89a-421f-903e-b2b9bcb18e37","html_url":"https://github.com/zevv/janet-time","commit_stats":null,"previous_names":["zevv/janet-time"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zevv/janet-time","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fjanet-time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fjanet-time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fjanet-time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fjanet-time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zevv","download_url":"https://codeload.github.com/zevv/janet-time/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fjanet-time/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28531993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T04:11:11.417Z","updated_at":"2026-01-18T06:10:39.831Z","avatar_url":"https://github.com/zevv.png","language":"Janet","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n## Introduction\n\nConcept time/date/calendar library for the Janet programming language\n\nThe goal is to provide a lightweight library for working with times and dates.\n\"complicated\" functionaltiy like localization and time zone handling should be\ndelagated to the operating system or C library when possible.\n\n\n## API\n\nThe functions that perform conversion between `time` and `datetime` types\nall have an optional time zone argument `tz`; this argument is a string\nwith a RFC 2822/ISO 8601 time zone name.\n\nwhen this argument is not given the functions act on the local time zone.\n\n\n### Read clock\n\nThe following functions all return time as a floating point number:\n\n`(time/now)`\n\nRead the real time clock. The result is a floating point number indicating\nthe number of seconds since the UNIX epoch.\n\n\n`(time/monotonic)`\n\nGet current monotonic time. The result is a floating point number with an\nundefined epoch that is guarunteed to be monotonic.\n\n\n`(time/cputime)`\n\nGet CPU time used by current process. The result is a floating point number\nindicating the number of seconds the current process has spent executing on\nthe CPU.\n\n\n### Conversion\n\n`(time/to-datetime time \u0026opt tz)`:\n\nConvert a time to a datetime struct.\n\n\n`(time/from-datetime dt \u0026opt tz)`\n\nConvert a datetime struct to a time.\n\n\n### Formatting and parsing\n\n\n`(time/format time \u0026opt fmt tz)`\n\nFormat the given time to ASCII string. The format string is C89 \nstrftime(3) format, or one of the predefined formats:\n\n- :iso-8601\n- :rfc-3339\n- :rfc-2822\n- :w3c\n\nWhen the `fmt` argument is not given, it defaults to the `:rfc-2822` format.\n\n\n`(time/parse fmt string \u0026opt tz)`\n\nparse a time in the given format. The format string is a subset of the C89\nstrftime(3) format:\n- %Y: year, 4 digits\n- %y: year, 2 digits, 2000 is added if the year is less than 70\n- %m: month, 2 digits, 01-12\n- %d: day, 2 digits, 01-31\n- %H: hour, 2 digits, 00-23\n- %I: hour, 2 digits, 01-12\n- %M: minute, 2 digits, 00-59\n- %S: second, 2 digits, 00-59\n- %p: AM/PM\n\nor one of the predefined formats:\n- :iso-8601\n- :rfc-3339\n- :rfc-2822\n- :w3c\n\n\n## Design considerations and other ramblings\n\n### Basic concepts\n\n- *clock*: some functiality measuring and providing time (typically provided by the OS)\n\n- *clock source*: indentifier specifying a source of time: `:monononic-time`,\n  `:system-time`, `:cpu-time`\n\n- *monotonic time*: floating point representation of a monotonically increasing \n  time in seconds with no defined epoch.\n\n- *system time*: floating point representation of the system clock in seconds,\n  relative to the *system time epoch*\n\n- *cpu time*: floating point representation of the CPU time used by a process\n  or thread.\n\n- *system time epoch*: Represents the timestamp of the *system time* value `0`:\n  equal to the UNIX time epoch: January 1st 1970 00:00:00 UTC.\n\n- *interval*: the difference between two `monotime` or `system-time` times, in\n  seconds.\n\n- *time zone*: a string identifying a world region time zone, for example\n  \"GMT\", \"UTC\", \"CET\", \"CET+3\", etc. See ISO 8610.\n\n- *datetime*: time components: *year*, *month*, *day-of-month*, *day-of-year*, *weekday*,\n  *hour*, *minute*, *second*.\n\n- *UTC time*: representation of a system time in *datetime* in\n  Coordinated Universal Time.\n\n- *local time*: representation of a system time in *datetime* in\n  a given time zone.\n\n- *resolution*: the smallest interval a given clock source can represent.\n\n\n### Functionality\n\nThe time library should offer the following functionality, properly handling\ntime zones where appropiate:\n\n- Querying system time, monotonic time and cpu time\n\n- Breaking down system time to individual *datetime* components.\n\n- Composing individual *datetime* components into a system time.\n\n- Formatting *datetime* to human readable format using custom formatting or\n  well-known time formats.\n\n- Parsing *datetime* from human readable format using custom formatting or\n  well-known time formats.\n\n- Basic time arithmatic: adddition and subtraction of *system time* and\n  *datetime*\n\n\n### Implementation\n\n\n#### Clocks and sources\n\nQuerying time from a given clock source is provided by the stdlib `os/clock`\nand `os/time` functions. These are implemented with the following primitives:\n\n  * Windows: system time: `GetSystemTimeAsFileTime()`, monotonic time:\n    `QueryPerformanceCounter()`, cpu time: `GetProcessTimes()`\n\n  * Apple: system time: `host_get_clock_service()`, monotonic time:\n    `host_get_clock_service()`, cpu time: `clock()`\n\n  * Linux/POSIX: system time: `clock_gettime(CLOCK_REALTIME)`, monotonic time:\n    `clock_gettime(CLOCK_MONOTONIC)`, cpu time:\n    `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)`\n\n\n#### *datetime*\n\nJanet already has a representation for broken down time as a `date struct`,\nhttps://janet-lang.org/api/index.html#os/date\n\nReuse this time? It uses a somewhat confusing 0-based indexing for\n*day-of-month* and *month-of-year* though.\n\n\n#### Composing system time from datetime\n\nJanet provides basic functionality through the C library `mktime()` and\n`timegm()` funcion wrapper `os/mktime`. `mktime` has no portable way for\nhandling time zones though.\n\n\n#### Splitting system time into datetime\n\nJanet provides `os/date` as a wrapper around the C library `localtime()` and\n`gmtime()`\nfunctions. These have no portable way for handling time zones.\n\n\n### Localization\n\nI don't even want to think about that. Delegate to C library\n\n\n### Time zones\n\nSee \"Localization\"\n\n\n#### Time formatting\n\nSome thoughts:\n\n- Implementaion in native Janet janet should be easy for numerical times and\n  dates, but will not support localazation for week and month names.\n\n- Janet provides a wrapper around the C library `strftime()` function as\n  `os/strftime`, which does take care of localzation.\n\n- Time zone handling is not standardized for `strftime()`\n\n\n#### Time parsing\n\nPOSIX defines the `strptime()` C function, which parses a `struct tm` from a\ngiven time format; this is not available on Windows.\n\nImplementing time parsing in native Janet should not be too hard.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevv%2Fjanet-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzevv%2Fjanet-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevv%2Fjanet-time/lists"}