{"id":13801262,"url":"https://github.com/clj-time/clj-time","last_synced_at":"2025-10-22T02:48:23.220Z","repository":{"id":1754045,"uuid":"2581048","full_name":"clj-time/clj-time","owner":"clj-time","description":"A date and time library for Clojure, wrapping the Joda Time library.","archived":false,"fork":true,"pushed_at":"2021-09-13T17:45:17.000Z","size":614,"stargazers_count":739,"open_issues_count":2,"forks_count":161,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-05-03T01:13:36.277Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"KirinDave/clj-time","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clj-time.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"MIT-LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-10-15T09:12:46.000Z","updated_at":"2025-03-23T03:07:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clj-time/clj-time","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clj-time%2Fclj-time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clj-time%2Fclj-time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clj-time%2Fclj-time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clj-time%2Fclj-time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clj-time","download_url":"https://codeload.github.com/clj-time/clj-time/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253932788,"owners_count":21986448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-04T00:01:21.009Z","updated_at":"2025-10-22T02:48:17.920Z","avatar_url":"https://github.com/clj-time.png","language":"Clojure","funding_links":[],"categories":["Date and Time","\u003ca name=\"Clojure\"\u003e\u003c/a\u003eClojure"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/clj-time/clj-time.svg?branch=master)](https://travis-ci.org/clj-time/clj-time)\n[![Dependencies Status](https://versions.deps.co/clj-time/clj-time/status.svg)](https://versions.deps.co/clj-time/clj-time)\n[![Downloads](https://versions.deps.co/clj-time/clj-time/downloads.svg)](https://versions.deps.co/clj-time/clj-time)\n[![Join the chat at https://gitter.im/clj-time/clj-time](https://badges.gitter.im/clj-time/clj-time.svg)](https://gitter.im/clj-time/clj-time?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n# clj-time\n\nA date and time library for Clojure, wrapping the [Joda Time](http://www.joda.org/joda-time/) library. **DEPRECATED**\n\n## Project Status\n\n**The Joda Time website says:**\n\n\u003e Note that from Java SE 8 onwards, users are asked to migrate to java.time (JSR-310) - a core part of the JDK which replaces this project.\n\n**If you are using Java 8 or later, please use the built-in Java Time instead of Joda Time -- or look at [clojure.java-time](https://github.com/dm3/clojure.java-time) if you want a Clojure wrapper for that, or [cljc.java-time](https://github.com/henryw374/cljc.java-time) for a thin Clojure(Script) wrapper, or [juxt/tick](https://github.com/juxt/tick) for another cross-platform option. See [Converting from Joda Time to java.time](http://blog.joda.org/2014/11/converting-from-joda-time-to-javatime.html) for more details about the similarities and differences between the two libraries.**\n\n## Artifacts\n\n`clj-time` artifacts are [released to Clojars](https://clojars.org/clj-time/clj-time).\n\nIf you are using Maven, add the following repository definition to your `pom.xml`:\n\n``` xml\n\u003crepository\u003e\n  \u003cid\u003eclojars.org\u003c/id\u003e\n  \u003curl\u003ehttp://clojars.org/repo\u003c/url\u003e\n\u003c/repository\u003e\n```\n\n### The Most Recent Release\n\nWith Leiningen:\n\n```\n[clj-time \"0.15.2\"]\n```\n\nWith Maven:\n\n``` xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eclj-time\u003c/groupId\u003e\n  \u003cartifactId\u003eclj-time\u003c/artifactId\u003e\n  \u003cversion\u003e0.15.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Bugs and Enhancements\n\nPlease open issues against the [official clj-time repo on Github](https://github.com/clj-time/clj-time/issues). `clj-time` is a very thin wrapper around Joda Time. That means that if Joda Time has a \"peculiar behavior\", it's likely to be surfaced directly in `clj-time` as well. A good example of this is `clj-time.format/unparse` which simply calls Joda Time's `.print` method -- and if the date passed in happens to be `nil`, you silently get back the _current date/time_ (many people would expect an exception!).\n\n## Mailing List\n\nPlease ask questions on the [clj-time mailing list](http://groups.google.com/forum/#!forum/clj-time).\n\n\n## Usage\n\n### clj-time.core\n\nThe main namespace for date-time operations in the `clj-time` library is `clj-time.core`.\n\n``` clj\n(require '[clj-time.core :as t])\n```\n\nCreate a DateTime instance with date-time, specifying the year, month,\nday, hour, minute, second, and millisecond:\n\n\n``` clj\n(t/date-time 1986 10 14 4 3 27 456)\n=\u003e #\u003cDateTime 1986-10-14T04:03:27.456Z\u003e\n```\n\nLess-significant fields can be omitted:\n\n``` clj\n(t/date-time 1986 10 14)\n=\u003e #\u003cDateTime 1986-10-14T00:00:00.000Z\u003e\n```\n\nGet the current time with `now` and the start of the Unix epoch with\n`epoch`.\n\nOnce you have a date-time, use accessors like `hour` and `second` to\naccess the corresponding fields:\n\n\n```clojure\n(t/hour (t/date-time 1986 10 14 22))\n=\u003e 22\n```\n\nThe date-time constructor always returns times in the UTC time\nzone. If you want a time with the specified fields in a different time\nzone, use `from-time-zone`:\n\n\n``` clj\n(t/from-time-zone (t/date-time 1986 10 22) (t/time-zone-for-offset -2))\n=\u003e #\u003cDateTime 1986-10-22T00:00:00.000-02:00\u003e\n```\n\nIf on the other hand you want a given absolute instant in time in a\ndifferent time zone, use `to-time-zone`:\n\n\n``` clj\n(t/to-time-zone (t/date-time 1986 10 22) (t/time-zone-for-offset -2))\n=\u003e #\u003cDateTime 1986-10-21T22:00:00.000-02:00\u003e\n```\n\nIn addition to `time-zone-for-offset`, you can use the\n`time-zone-for-id` and `default-time-zone` functions and the `utc` Var\nto construct or get `DateTimeZone` instances.\n\n\nIf you only want a date with no time component, consider using the\n`local-date` and `today` functions. These return `LocalDate` instances\nthat do not have time components (and thus don't suffer from\ntimezone-related shifting).\n\n\n``` clj\n(t/local-date 2013 3 20)\n=\u003e #\u003cLocalDate 2013-03-20\u003e\n```\n\nThe functions `equal?`, `after?`, and `before?` determine the relative position\nof two DateTime instances:\n\n```clojure\n(t/equal? (t/date-time 1986 10) (t/date-time 1986 10))\n=\u003e true\n(t/after? (t/date-time 1986 10) (t/date-time 1986 9))\n=\u003e true\n(t/before? (t/date-time 1986 9) (t/date-time 1986 10))\n=\u003e true\n```\n\nOften you will want to find a date some amount of time from a given\ndate. For example, to find the time 1 month and 3 weeks from a given\ndate-time:\n\n\n``` clj\n(t/plus (t/date-time 1986 10 14) (t/months 1) (t/weeks 3))\n=\u003e #\u003cDateTime 1986-12-05T00:00:00.000Z\u003e\n```\n\nYou can perform also `minus` operations\n```clj\n(t/minus (t/date-time 1986 10 14 6) (t/hours 2))\n=\u003e #\u003cDateTime 1986-10-14T04:00:00.000Z\u003e\n```\n\n\nAn `Interval` is used to represent the span of time between two\n`DateTime` instances. Construct one using `interval`, then query them\nusing `within?`, `overlaps?`, and `abuts?`\n\n```clojure\n(t/within? (t/interval (t/date-time 1986) (t/date-time 1990))\n              (t/date-time 1987))\n=\u003e true\n```\n\nThe `in-seconds` and `in-minutes` functions can be used to describe\nintervals in the corresponding temporal units:\n\n```clojure\n(t/in-minutes (t/interval (t/date-time 1986 10 2) (t/date-time 1986 10 14)))\n=\u003e 17280\n```\n\nThe `overlap` function can be used to get an `Interval` representing the\noverlap between two intervals:\n\n``` clj\n(t/overlap (t/interval (t/date-time 1986) (t/date-time 1990))\n         (t/interval (t/date-time 1987) (t/date-time 1991)))\n=\u003e #\u003cInterval 1987-01-01T00:00:00.000Z/1990-01-01T00:00:00.000Z\u003e\n```\n\n`today-at` returns a moment in time at the given hour,\nminute and second on the current date UTC; not the current system date:\n\n``` clj\n(t/today-at 12 00)\n=\u003e #\u003cDateTime 2013-03-29T12:00:00.000Z\u003e\n(t/today-at 12 00 05)\n=\u003e #\u003cDateTime 2013-03-29T12:00:05.000Z\u003e\n\n;; System clock says 11PM on 12/20/2016 UTC-5\n(t/today-at 7 00 00)\n=\u003e #\u003cDateTime 2016-12-21T7:00:00.000Z\u003e\n```\n\n### clj-time.format\n\nIf you need to parse or print date-times, use `clj-time.format`:\n\n``` clj\n(require '[clj-time.format :as f])\n```\n\nParsing and printing are controlled by formatters. You can either use\none of the built in ISO8601 formatters or define your own, e.g.:\n\n```clojure\n(def built-in-formatter (f/formatters :basic-date-time))\n(def custom-formatter (f/formatter \"yyyyMMdd\"))\n```\n\nTo see a list of available built-in formatters and an example of a\ndate-time printed in their format:\n\n\n``` clj\n(f/show-formatters)\n```\n\nRemember that `mm` is minutes, `MM` is months, `ss` is seconds and\n`SS` is milliseconds. You can find a [complete list of patterns](http://www.joda.org/joda-time/key_format.html)\non the Joda Time website.\n\nOnce you have a formatter, parsing and printing are straightforward:\n\n``` clj\n(f/parse custom-formatter \"20100311\")\n=\u003e #\u003cDateTime 2010-03-11T00:00:00.000Z\u003e\n```\n```clojure\n(f/unparse custom-formatter (t/date-time 2010 10 3))\n=\u003e \"20101003\"\n```\n\nTo parse dates in multiple formats and format dates in just one\nformat, you can do this:\n\n\n```clojure\n(def multi-parser (f/formatter (t/default-time-zone) \"YYYY-MM-dd\" \"YYYY/MM/dd\"))\n\n(f/unparse multi-parser (f/parse multi-parser \"2012-02-01\"))\n=\u003e \"2012-02-01\"\n\n(f/unparse multi-parser (f/parse multi-parser \"2012/02/01\"))\n=\u003e \"2012-02-01\"\n```\n\nNote: Joda Time's `.print` method accepts a null date/time object and substitutes the current date/time, so `(f/unparse my-fmt nil)` will not throw an exception -- it will just silently return the current date/time!\n\n### clj-time.coerce\n\nThe namespace `clj-time.coerce` contains utility functions for\ncoercing Joda `DateTime` instances to and from various other types:\n\n\n```clojure\n(require '[clj-time.coerce :as c])\n```\n\nFor example, to convert a Joda `DateTime` to and from a Java `long`:\n\n```clojure\n(c/to-long (t/date-time 1998 4 25))\n=\u003e 893462400000\n```\n``` clj\n(c/from-long 893462400000)\n=\u003e #\u003cDateTime 1998-04-25T00:00:00.000Z\u003e\n```\n\nAnd by the magic of protocols you can pass in an isoformat string and\nget the unix epoch milliseconds:\n\n```clojure\n(c/to-long \"2013-08-01\")\n=\u003e 1375315200000\n```\n\nThere are also conversions to and from `java.util.Date` (`to-date` and\n`from-date`), `java.sql.Date` (`to-sql-date` and `from-sql-date`),\n`java.sql.Timestamp` (`to-sql-time` and `from-sql-time`) and several\nother types.\n\nTo support serialization to the ubiquitous\n[EDN format](https://github.com/edn-format/edn),\n`pr`, `prn` etc. will serialize Joda `DateTime` in a tagged-literal format,\nthat `clojure.edn/read` will deserialize.  There is a `data_readers.clj`\nfile, or if not loaded a `data-readers` var to use with `clojure.edn`.\n\n```clojure\n(pr-str (t/date-time 1998 4 25))\n=\u003e \"#clj-time/date-time \\\"1998-04-25T00:00:00.000Z\\\"\"\n```\n\n```clojure\n(require '[clojure.edn :as edn])\n=\u003e nil\n```\n\n```clojure\n(def x (edn/read-string {:readers c/data-readers}\n                        (pr-str (t/date-time 1998 4 25))))\n```\n\n```clojure\n(type x)\n=\u003e org.joda.time.DateTime\n```\n\n```clj\nx\n=\u003e #clj-time/date-time \"1998-04-25T00:00:00.000Z\"\n```\n\n\n### clj-time.local\n\nThe namespace `clj-time.local` contains functions for working with\nlocal time without having to shift to/from utc, the preferred time\nzone of clj-time.core.\n\n``` clj\n(require '[clj-time.local :as l])\n```\n\nGet the current local time with\n\n``` clj\n(l/local-now)\n```\n\nGet a local date-time instance retaining the time fields with\n\n``` clj\n(l/to-local-date-time obj)\n```\n\nThe following all return 1986-10-14 04:03:27.246 with the local time\nzone.\n\n``` clj\n(l/to-local-date-time (clj-time.core/date-time 1986 10 14 4 3 27 246))\n(l/to-local-date-time \"1986-10-14T04:03:27.246\")\n(l/to-local-date-time \"1986-10-14T04:03:27.246Z\")\n```\n\nThe dynamic var `*local-formatters*` contains a map of local\nformatters for parsing and printing. It is initialized with all the\nformatters in clj-time.format localized.\n\nto-local-date-time for strings uses `*local-formatters*` to parse.\n\nFormat an obj using a formatter in `*local-formatters*` corresponding\nto the format-key passed in with\n\n``` clj\n(l/format-local-time (l/local-now) :basic-date-time)\n```\n\n\n### clj-time.periodic\n\n`clj-time.periodic/periodic-seq` returns an infinite sequence of instants\nseparated by a time period starting with the given point in time:\n\n``` clj\n(require '[clj-time.periodic :as p])\n(require '[clj-time.core :as t])\n\n;; returns 10 instants starting with current time separated\n;; by 12 hours\n(take 10 (p/periodic-seq (t/now) (t/hours 12)))\n```\n\nIn particular, if you ask for a sequence of instants separated by a month, you will get dates where the month increases each time (rather than being, say, 30 days apart).\n\n### clj-time.predicates\n\n`clj-time.predicates` comes with a set of handy predicates to\ncheck for common conditions. For instance:\n\n``` clj\n(require '[clj-time.core :as t])\n(require '[clj-time.predicates :as pr])\n```\n```clojure\n(pr/monday? (t/date-time 1999 9 9))\n=\u003e false\n\n(pr/january? (t/date-time 2011 1 1))\n=\u003e true\n\n(pr/weekend? (t/date-time 2014 1 26))\n=\u003e true\n\n(pr/weekday? (t/date-time 2014 1 26))\n=\u003e false\n\n(pr/last-day-of-month? (t/date-time 2014 1 26))\n=\u003e false\n\n(pr/first-day-of-month? (t/date-time 2014 1 26))\n=\u003e false\n```\n\n### clj-time.jdbc\n\n`clj-time.jdbc` registers protocol extensions so you don’t have to use\n`clj-time.coerce` yourself to coerce to and from SQL timestamps.\n\nFrom the REPL:\n\n``` clj\n(require 'clj-time.jdbc)\n```\n\nIn your project:\n\n``` clj\n(ns my.neat.project\n  (:require [clj-time.jdbc]))\n\n; They're registered and ready to use.\n```\n\nNow you can use `org.joda.time.DateTime` objects when \"writing\" to the database\nin place of `java.sql.Timestamp` objects, and expect `org.joda.time.DateTime`\nobjects when \"reading\" where you would have previously expected\n`java.sql.Timestamp` objects.\n\n## Development\n\nRunning the tests:\n\n    $ rm -f test/readme.clj \u0026\u0026 lein test-all\n\n(assumes Leiningen 2.x)\n\n## Documentation\n\nThe complete [API documentation](http://clj-time.github.io/clj-time/doc/index.html) is also available (codox generated).\n\n## License\n\nReleased under the MIT License: \u003chttps://github.com/clj-time/clj-time/blob/master/MIT-LICENSE.txt\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclj-time%2Fclj-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclj-time%2Fclj-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclj-time%2Fclj-time/lists"}