{"id":13862100,"url":"https://github.com/doublep/datetime","last_synced_at":"2026-02-21T00:29:43.955Z","repository":{"id":90058210,"uuid":"59241255","full_name":"doublep/datetime","owner":"doublep","description":"Library for parsing, formatting, matching and recoding timestamps and date-time format strings.","archived":false,"fork":false,"pushed_at":"2025-02-03T20:47:43.000Z","size":2702,"stargazers_count":20,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-14T12:48:17.735Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doublep.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2016-05-19T20:41:02.000Z","updated_at":"2025-04-24T22:46:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"fd750b29-1e99-4db6-9dde-464daeb1d1bf","html_url":"https://github.com/doublep/datetime","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/doublep/datetime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doublep%2Fdatetime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doublep%2Fdatetime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doublep%2Fdatetime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doublep%2Fdatetime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doublep","download_url":"https://codeload.github.com/doublep/datetime/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doublep%2Fdatetime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29668689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"ssl_error","status_checked_at":"2026-02-20T23:52:33.807Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-08-05T06:01:37.130Z","updated_at":"2026-02-21T00:29:43.934Z","avatar_url":"https://github.com/doublep.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":":toc: macro\n:toc-title: Table of contents\n:source-language: lisp\nifndef::env-github[:icons: font]\nifdef::env-github[]\n:warning-caption: :warning:\n:caution-caption: :fire:\n:important-caption: :exclamation:\n:note-caption: :paperclip:\n:tip-caption: :bulb:\nendif::[]\n:uri-icu: https://unicode-org.github.io/icu/userguide/datetime/\n:uri-java-datetimeformatter: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/format/DateTimeFormatter.html\n:uri-php-date: http://php.net/manual/en/function.date.php\n:uri-logview: https://github.com/doublep/logview\n\n\nimage:https://img.shields.io/badge/license-GPL_3-green.svg[License: GPL 3, link=http://www.gnu.org/licenses/gpl-3.0.txt]\nimage:https://img.shields.io/github/release/doublep/datetime.svg[Latest release, link=https://github.com/doublep/datetime/releases]\nimage:http://stable.melpa.org/packages/datetime-badge.svg[MELPA Stable, link=http://stable.melpa.org/#/datetime]\nimage:https://github.com/doublep/datetime/workflows/CI/badge.svg[CI, link=https://github.com/doublep/datetime/actions?query=workflow%3ACI]\n\n\n= datetime\n\nDatetime is a library for parsing, formatting, matching and recoding\ntimestamps and date-time format strings.  Not all of the planned\nfunctionality is implemented yet.\n\n\n== System locale and timezone\n\nThe library will try to guess your system locale and timezone, but\nthis is frustratingly difficult.  In particular, on MS Windows it will\nnot be able to determine the timezone (not sure about locale).\nPatches to improve this are welcome.\n\nIn any case, when it fails completely or guesses incorrectly, you can\nalways override the heuristics results by setting variables\n`datetime-locale` and/or `datetime-timezone` manually.  Both are also\navailable through Emacs customization interface, group `datetime`.\n\nTo find the list of all supported locales and timezones, evaluate the\nfollowing forms:\n\n....\n(prin1-to-string (sort (datetime-list-locales t) #'string\u003c))\n(prin1-to-string (sort (datetime-list-timezones) #'string\u003c))\n....\n\n\n== Overall goals\n\nThis library is targeted at bulk-processing, therefore many functions\nare optimized for speed, but not necessarily for ease of use.  For\nexample, \u003c\u003c#formatting,formatting\u003e\u003e is done in two steps: first you\nneed to generate a formatting function for given pattern, and only\nusing it obtain formatted strings.\n\nThe initial and primary user of the library is {uri-logview}[Logview],\nwhere it is used to quickly \u003c\u003c#matching,match\u003e\u003e thousands of\ntimestamps (usually one per line) in a log file, so speed was very\nimportant from the start.  Later it also started using datetime’s\n\u003c\u003c#parsing,parsing\u003e\u003e functionality in a similar way — meaning that\nspeed was important there too.\n\n\n== Pattern types\n\nThere exist several different ways to specify date and/or time format.\nDifferent programming languages and their libraries use different\nformats.  E.g. format of date 2015-09-24 can be expressed at least in\nthe following ways:\n\n* `yyyy-MM-dd` ({uri-icu}[ICU], {uri-java-datetimeformatter}[Java])\n* `%Y-%m-%d` (POSIX, Emacs)\n* `Y-m-d` ({uri-php-date}[PHP])\n\nThis library currently uses Java pattern format everywhere, but is\ninternally written in such a way that support for other types can be\nadded relatively easily — when someone needs them.\n\n=== Supported Java pattern elements\n\nJava {uri-java-datetimeformatter}[date-time patterns] are very\nversatile and support a lot of features.  This library doesn’t\nimplement — at least currently — every element, but does support all\nthe most imporant ones.  In particular, everything (with the exception\nof timezone names) needed by patterns returned from the three\n`datetime-locale-*-pattern` functions is supported in all other parts\nof the library.  Timezone names are currently supported when\n\u003c\u003c#formatting,formatting\u003e\u003e only.\n\nHere is an overview of Java date-time pattern elements together with\ntheir support in datetime library:\n\n[%autowidth]\n|===\n^| Symbol | Meaning                           ^| Support in the library\n\n^| G      | era (AD/BC)                       ^| full\n^| u      | year                              ^| none\n^| y      | year of era                       ^| full\n^| Y      | week-based year                   ^| full\n^| Q/q    | quarter of year                   ^| none\n^| M/L    | month of year                     ^| full\n^| w      | week of week-based year           ^| full\n^| W      | week of month                     ^| full\n^| D      | day of year                       ^| full\n^| d      | day of month                      ^| full\n^| g      | modified julian day               ^| none\n^| E      | day of week                       ^| full\n^| e/c    | localized day of week             ^| full\n^| F      | day-of-week in month              ^| full\n^| a      | AM/PM                             ^| full\n^| B      | period of day                     ^| full\n^| H      | hour of day (0-23)                ^| full\n^| k      | hour of day (1-24)                ^| full\n^| h      | hour in AM/PM (1-12)              ^| full\n^| K      | hour in AM/PM (0-11)              ^| full\n^| m      | minute of hour                    ^| full\n^| s      | second of minute                  ^| full\n^| S      | fraction of second                ^| full\n^| A      | millisecond of day                ^| none\n^| n      | nanosecond of second              ^| none\n^| V      | timezone id                       ^| none\n^| v      | generic timezone name             ^| none\n^| z      | timezone name                     ^| only formatting\n^| Z      | timezone z-offset                 ^| full\n^| x      | timezone x-offset                 ^| full\n^| X      | timezone x-offset or 'Z' for zero ^| full\n^| O      | localized timezone offset         ^| full\n^| p      | pad modifier                      ^| none\n^| '      | quoting for literal text          ^| full\n^| [/]    | optional section                  ^| none\n|===\n\nSome examples of commonly used patterns:\n\n[%autowidth]\n|===\n| Pattern                    | Example timestamp         | Notes\n\n| `yyyy-MM-dd HH:mm:ss`      | 2023-09-18 21:29:02       |\n| `yyyy-MM-dd HH:mm:ss.SSS`  | 2023-09-18 21:29:02.618   |\n| `yyyy-MM-dd\\'T\\'HH:mm:ssZ` | 2023-09-18T21:29:02+0200  |\n| `yyyy-MM-dd HH:mm:ssXXX`   | 2023-09-18 21:29:02+02:00 |\n| `yyyy-MM-dd HH:mm:ssx`     | 2023-09-18 21:29:02+02    |\n| `yyyy-MM-dd HH:mm:ss O`    | 2023-09-18 21:29:02 GMT+2 |\n| `yyyy-MM-dd HH:mm:ss z`    | 2023-09-18 21:29:02 CEST  | only formatting supported\n| `EEE MMM dd HH:mm:ss yyyy` | Mon Sep 18 21:29:02 2023  |\n| `dd.MM.yyyy`               | 18.09.2023                |\n| `MMM d, yyyy`              | Sep 18, 2023              |\n| `h:mm:ss a`                | 9:29:02 PM                |\n|===\n\n\n[#parsing]\n== Parsing timestamps\n\nParsing timestamps using the library is a two-step operation.  First\nyou create a _parser function_ for a specific pattern and options.\nThen call the parser function with one argument — the timestamp as a\nstring.  It returns a floating point number — number of seconds since\nUNIX epoch in UTC timezone.\n\nCreate a parser:\n\n....\n(datetime-parser-to-float 'java \"yyyy-MM-dd HH:mm:ss.SSS\"\n                          :timezone 'system)\n....\n\nAnd use it:\n\n....\n(let ((parser (datetime-parser-to-float 'java \"yyyy-MM-dd HH:mm:ss.SSS\"\n                                        :timezone 'system)))\n  (funcall parser \"2018-09-18 21:20:00.000\"))\n....\n\nRemember that if you parse timestamps formatted on your machine, you\nneed to pass `'system` as `:timezone` option to\n`datetime-parser-to-float`: default timezone is UTC.\n\nParsing timestamps with varying timezones (i.e. with timezone\ninformation directly in the input string) has limited support as of\n0.9: you can now parse timezone offsets, but not yet timezone names.\nE.g. “20:00:00+01” is parseable (for example, with pattern\n“HH:mm:ssx\"), but “20:00:00 CET” cannot really be parsed.\n\n\n[#formatting]\n== Formatting timestamps\n\nTo format timestamps you first need to create a _formatter function_.\nThis function accepts one argument — the timestamp as a floating point\nnumber — and converts it to a string.  All customization, most\nimportantly, specifying the pattern, is done at the point of creating\nthe formatter.\n\nFor example:\n\n....\n(datetime-float-formatter 'java \"yyyy-MM-dd HH:mm:ss.SSS\"\n                          :timezone 'system)\n....\n\nWith this formatter function you can now format timestamps as follows:\n\n....\n(let ((formatter (datetime-float-formatter 'java \"yyyy-MM-dd HH:mm:ss.SSS\"\n                                           :timezone 'system)))\n  (funcall formatter (float-time)))\n....\n\nNote that if you plan to format result of `float-time` function, you\nneed to pass `'system` as `:timezone` option to\n`datetime-float-formatter`: default timezone is UTC.\n\nAs of version 0.9 the library fully supports formatting timezones:\nboth names (`z` and `zzzz` in Java patterns) and offsets (`z`, `x`,\n`X`, `O`; in various repetition counts) can be used to format\nabbreviated of full names and offsets to GMT.  For example:\n\n....\n(let ((formatter1 (datetime-float-formatter 'java \"HH:mm:ss z\"\n                                            :timezone 'system))\n      (formatter2 (datetime-float-formatter 'java \"HH:mm:ssx\"\n                                            :timezone 'system)))\n  (cons (funcall formatter1 (float-time)) (funcall formatter2 (float-time))))\n....\n\n\n[#matching]\n== Matching timestamps\n\nSometimes you need to determine if given string is (likely) a\ntimestamp, corresponding to given pattern.  A robust way, of course,\nis to try to parse it.  However, it is much faster, though not as\nprecise, to use a regular expression.\n\nFunction `datetime-matching-regexp` builds such a regular expression\nfor given pattern.  For example,\n\n    (datetime-matching-regexp 'java \"yyyy-MM-dd HH:mm:ss.SSS\")\n\nreturns a regexp that will match all timestamp strings produced by the\nformatter we created earlier.  It will also match some other strings,\nbut is good enough in practice to tell if “this does look like a\ntimestamp”.\n\nTimezone support in matching is currently the same as for\n\u003c\u003c#parsing,parsing\u003e\u003e.\n\n\n== Other functions\n\nThese functions are also part of the library interface.  They are\ndocumented within Emacs.\n\n* `datetime-recode-pattern`\n\n* `datetime-pattern-locale-dependent-p`\n* `datetime-pattern-includes-date-p`\n* `datetime-pattern-includes-time-p`\n* `datetime-pattern-includes-era-p`\n* `datetime-pattern-includes-year-p`\n* `datetime-pattern-includes-month-p`\n* `datetime-pattern-includes-week-p`\n* `datetime-pattern-includes-day-p`\n* `datetime-pattern-includes-weekday-p`\n* `datetime-pattern-includes-hour-p`\n* `datetime-pattern-includes-minute-p`\n* `datetime-pattern-includes-second-p`\n* `datetime-pattern-includes-second-fractionals-p`\n* `datetime-pattern-num-second-fractionals`\n* `datetime-pattern-includes-timezone-p`\n* `datetime-pattern-includes-timezone-name-p`\n* `datetime-pattern-includes-timezone-offset-p`\n\n* `datetime-list-locales`\n* `datetime-list-timezones`\n\n* `datetime-locale-date-pattern`\n* `datetime-locale-time-pattern`\n* `datetime-locale-date-time-pattern`\n* `datetime-locale-field`\n* `datetime-locale-timezone-name`\n\n* `datetime-locale-database-version`\n* `datetime-timezone-database-version`\n* `datetime-timezone-name-database-version`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoublep%2Fdatetime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoublep%2Fdatetime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoublep%2Fdatetime/lists"}