A date and time library for Clojure, wrapping the Joda Time library.
clj-time artifacts are released to Clojars.
If you are using Maven, add the following repository definition to your
<repository> <id>clojars.org</id> <url>http://clojars.org/repo</url> </repository>
The Most Recent Release
<dependency> <groupId>clj-time</groupId> <artifactId>clj-time</artifactId> <version>0.5.1</version> </dependency>
Bugs and Enhancements
Please open issues against the official clj-time repo on Github.
The main namespace for date-time operations in the
clj-time library is
=> (use 'clj-time.core)
Create a DateTime instance with date-time, specifying the year, month, day, hour, minute, second, and millisecond:
=> (date-time 1986 10 14 4 3 27 456) #<DateTime 1986-10-14T04:03:27.456Z>
Less-significant fields can be omitted:
=> (date-time 1986 10 14) #<DateTime 1986-10-14T00:00:00.000Z>
Get the current time with
(now) and the start of the Unix epoch with
Once you have a date-time, use accessors like
sec to access the corresponding fields:
=> (hour (date-time 1986 10 14 22)) 22
The date-time constructor always returns times in the UTC time zone. If you want a time with the specified fields in a different time zone, use
=> (from-time-zone (date-time 1986 10 22) (time-zone-for-offset -2)) #<DateTime 1986-10-22T00:00:00.000-02:00>
If on the other hand you want a given absolute instant in time in a different time zone, use
=> (to-time-zone (date-time 1986 10 22) (time-zone-for-offset -2)) #<DateTime 1986-10-21T22:00:00.000-02:00>
In addition to
time-zone-for-offset, you can use the
default-time-zone functions and the
utc Var to construct or get
If you only want a date with no time component, consider using the
LocalDate instances that do not have time components (and thus don't suffer from timezone-related shifting).
=> (local-date 2013 3 20) #<LocalDate 2013-03-20>
before? determine the relative position of two
=> (after? (date-time 1986 10) (date-time 1986 9)) true
Often you will want to find a date some amount of time from a given date. For example, to find the time 1 month and 3 weeks from a given date-time:
=> (plus (date-time 1986 10 14) (months 1) (weeks 3)) #<DateTime 1986-12-05T00:00:00.000Z>
Interval is used to represent the span of time between two
instances. Construct one using
interval, then query them using
=> (within? (interval (date-time 1986) (date-time 1990)) (date-time 1987)) true
in-minutes functions can be used to describe intervals in the corresponding temporal units:
=> (in-minutes (interval (date-time 1986 10 2) (date-time 1986 10 14))) 17280
If you need to parse or print date-times, use
=> (use 'clj-time.format)
Printing and printing are controlled by formatters. You can either use one of the built in ISO8601 formatters or define your own, e.g.:
(def built-in-formatter (formatters :basic-date-time)) (def custom-formatter (formatter "yyyyMMdd"))
To see a list of available built-in formatters and an example of a date-time printed in their format:
mm is minutes,
MM is months,
ss is seconds and
SS is milliseconds.
Once you have a formatter, parsing and printing are strait-forward:
=> (parse custom-formatter "20100311") #<DateTime 2010-03-11T00:00:00.000Z> => (unparse custom-formatter (date-time 2010 10 3)) "20101003"
To parse dates in multiple formats and format dates in just one format, you can do this:
=> (def multi-parser (formatter (default-time-zone) "YYYY-MM-dd" "YYYY/MM/dd")) => (unparse multi-parser (parse multi-parser "2012-02-01")) "2012-02-01" => (unparse multi-parser (parse multi-parser "2012/02/01")) "2012-02-01"
clj-time.core/today-at returns a moment in time at the given hour, minute and second
on the current date:
=> (today-at 12 00) #<DateTime 2013-03-29T12:00:00.000Z> => (today-at 12 00 05) #<DateTime 2013-03-29T12:00:05.000Z>
clj-time.coerce contains utility functions for coercing Joda
DateTime instances to and from various other types:
=> (use 'clj-time.coerce)
For example, to convert a Joda
DateTime to and from a Java
=> (to-long (date-time 1998 4 25)) 893462400000 => (from-long 893462400000) #<DateTime 1998-04-25T00:00:00.000Z>
There are also conversions to and from
from-sql-time) and several other types.
clj-time.local contains functions for working with local time without having to shift to/from utc,
the preferred time zone of clj-time.core.
Get the current local time with
Get a local date-time instance retaining the time fields with
=> (to-local-date-time obj)
The following all return 1986-10-14 04:03:27.246 with the local time zone.
(to-local-date-time (clj-time.core/date-time 1986 10 14 4 3 27 246)) (to-local-date-time "1986-10-14T04:03:27.246") (to-local-date-time "1986-10-14T04:03:27.246Z")
The dynamic var *local-formatters* contains a map of local formatters for parsing and printing. It is initialized with all the formatters in clj-time.format localized.
to-local-date-time for strings uses *local-formatters* to parse.
Format an obj using a formatter in *local-formatters* corresponding to the format-key passed in with
=> (format-local-time (local-now) :basic-date-time)
clj-time.periodic/periodic-seq returns an infinite sequence of instants
separated by a time period starting with the given point in time:
(use 'clj-time.periodic) (use 'clj.time.core) ;; returns 10 instants starting with current time separated ;; by 12 hours (take 10 (periodic-seq (now) (hours 12)))
Running the tests:
$ lein test-all
(assumes Leiningen 2.x)
The complete API documentation is also available (codox generated).
Released under the MIT License: https://github.com/clj-time/clj-time/blob/master/MIT-LICENSE.txt