A Clojure wrapper for Java 8 Date-Time API.
Note: This library has no relation to Clojure's (or Java's) core team. It's naming is legacy and preserved for backwards compatibility reasons.
Main goals:
Why use Clojure.Java-Time over clj-time or Clojure.Joda-Time?
This library employs a structured and comprehensive approach to exposing the Java 8 Date-Time API to the Clojure world. It's very similar to Clojure.Joda-Time in its design goals and overall feeling, so if you ever used that you will feel at home!
Why use Clojure.Java-Time over cljc.java-time with tick?
require
over multiple onesI don't see any reasons except for aesthetical pleasure and existing knowledge to choose one over the other. However, I have neither used or benchmarked Cljc.Java-Time and Tick so my endorsement is purely on the merits of a broader feature set.
If you already used Joda Time before you might think: "What in the world could they do better?". After all, Joda-Time already provides a pretty comprehensive set of tools for dealing with time-related concepts. Turns out, it's a tad more complicated than it has to be. Also, a few concepts have faulty designs which lead to hard to fix bugs and misuse. You can see the birds-eye view of changes and some of the rationale on the author's (Stephen Colebourne) blog:
You can also take a look at a comprehensive comparison by the Time4J authors.
Add the following dependency to your deps.edn
:
clojure.java-time/clojure.java-time {:mvn/version "1.4.2"}
or to your project.clj
or build.boot
:
[clojure.java-time "1.4.2"]
The API of the Clojure.Java-Time
consists of one namespace, namely java-time.api
. For the purposes of this guide,
we will require
the main namespace:
(require '[java-time.api :as jt]
;; for REPL experimentation
'java-time.repl)
The Java Time API may seem daunting. Instead of a single java.util.Date
you have
a ZonedDateTime
, OffsetDateTime
, LocalDateTime
, Instant
, and other
types. You would be well served by reading the official documentation for the
Java Time API,
but we'll also do a quick run-through here.
LocalDate
, LocalTime
and LocalDateTime
are used to represent a date, time
and date-time respectively without an offset or a time zone. The local time entities
are used to represent human-based dates/times. They are a good fit for representing
the time of various events:
LocalDate
- birthday, holiday
jt/local-date
LocalTime
- bus schedule, opening time of a shop
jt/local-time
LocalDateTime
- start of a competition
Example usage:
(jt/local-date 2015 10)
;=> #<java.time.LocalDate 2015-10-01>
(jt/local-time 10)
;=> #<java.time.LocalTime 10:00>
(jt/local-date-time 2015 10)
;=> #<java.time.LocalDateTime 2015-10-01T00:00>
There are two types which deal with zones:
OffsetDateTime
ZonedDateTime
They do pretty much what you would expect from their name.
You can think of the Offset
time as a more concrete version of the Zoned
time. For example, the same time zone can have different offsets throughout the
year due to DST or governmental regulations.
(jt/offset-time 10)
;=> #<java.time.OffsetTime 10:00+01:00>
(jt/offset-date-time 2015 10)
;=> #<java.time.OffsetDateTime 2015-10-01T10:00+01:00>
(jt/zoned-date-time 2015 10)
;=> #<java.time.ZonedDateTime 2015-10-01T10:00+01:00[Europe/London]>
Offset/Zone times only take the offset/zone as the last arguments for the
maximum arity constructor. You can influence the zone/offset by using the
jt/with-zone
or jt/with-offset
functions, like so:
(jt/with-zone (jt/zoned-date-time 2015 10) "UTC")
;=> #<java.time.ZonedDateTime 2015-10-01T00:00Z[UTC]>
(jt/with-zone-same-instant (jt/zoned-date-time 2015 10) "UTC")
;=> #<java.time.ZonedDateTime 2015-09-30T23:00Z[UTC]>
(jt/with-clock (jt/system-clock "UTC")
(jt/zoned-date-time 2015 10))
;=> #<java.time.ZonedDateTime 2015-10-01T00:00Z[UTC]>
An Instant
is used to generate a time stamp representing machine time. It
doesn't have an offset or a time zone. You can think of it as of a number of
milliseconds since epoch (1970-01-01T00:00:00Z
). An instant is directly
analogous to java.util.Date
:
(jt/instant)
;=> #<java.time.Instant "2015-09-26T05:25:48.667Z">
(java.util.Date.)
;=> #inst "2015-09-26T05:25:50.118-00:00"
Every other date entity can be converted to an instant (local ones will require an additional zone information).
Java Time Period entities are considerably simpler than the Joda-Time periods. They are fixed containers of years, months and days. You can use them to represent any period of time with a granularity larger or equal to a single day. Duration, on the other hand, represents a standard duration less than or equal to a single standard (24-hour) day.
The current incarnation of the library is relatively slow while calling the 2-3
arity zoned-date-time/offset-time/offset-date-time
constructors for the
first time in a given Clojure runtime. If you need predictable latency at the
time of the first call in your business logic, please warm the
constructors you are going to use up by calling them beforehand, e.g.:
(defn warm-up []
(jt/zoned-date-time 2015 1 1)
(jt/zoned-date-time 2015 1)
(jt/zoned-date-time 2015))
The "constructor" here refers to an arity of a function together with its type
signature. For example, a (jt/zoned-date-time 2015)
and (jt/zoned-date-time (jt/system-clock))
are different constructors.
First, let's do a quick run through common use cases.
What is the current date?
(def now (jt/local-date))
;=> #object[java.time.LocalDate "2015-09-27"]
What's the next day?
(jt/plus now (jt/days 1))
;=> #object[java.time.LocalDate "2015-09-28"]
The previous day?
(jt/minus now (jt/days 1))
;=> #object[java.time.LocalDate "2015-09-26"]
Three days starting at now
?
(take 3 (jt/iterate jt/plus now (jt/days 1)))
;=> (#object[java.time.LocalDate "2015-09-27"]
; #object[java.time.LocalDate "2015-09-28"]
; #object[java.time.LocalDate "2015-09-29"])
When is the first Monday in month?
(jt/adjust now :first-in-month :monday)
;=> #object[java.time.LocalDate "2015-09-07"]
Date with some of its fields truncated:
(jt/truncate-to (jt/local-date-time 2015 9 28 10 15) :days)
;=> #object[java.time.LocalDateTime "2015-09-28T00:00"]
Date-time adjusted to the given hour:
(jt/adjust (jt/local-date-time 2015 9 28 10 15) (jt/local-time 6))
;=> #object[java.time.LocalDateTime "2015-09-28T06:00"]
The latest of the given dates?
(jt/max (jt/local-date 2015 9 20) (jt/local-date 2015 9 28) (jt/local-date 2015 9 1))
;=> #object[java.time.LocalDate "2015-09-28"]
The shortest of the given durations?
(jt/min (jt/duration 10 :seconds) (jt/duration 5 :hours) (jt/duration 3000 :millis))
;=> #object[java.time.Duration "PT3S"]
Get the year field out of the date:
(jt/as (jt/local-date 2015 9 28) :year)
;=> 2015
Get multiple fields:
(jt/as (jt/local-date 2015 9 28) :year :month-of-year :day-of-month)
;=> (2015 9 28)
Get the duration in a different unit:
(jt/plus (jt/hours 3) (jt/minutes 2))
;=> #object[java.time.Duration "PT3H2M"]
(jt/as *1 :minutes)
;=> 182
Format a date:
(jt/format "MM/dd" (jt/zoned-date-time 2015 9 28))
;=> "09/28"
Parse a date:
(jt/local-date "MM/yyyy/dd" "09/2015/28")
;=> #object[java.time.LocalDate "2015-09-28"]
Zoned date-times and offset date-times/times always take the zone/offset as the last argument. Offsets can be specified as float values:
(jt/zone-offset +1.5)
;=> #<java.time.ZoneOffset +01:30>
(jt/zone-offset -1.5)
;=> #<java.time.ZoneOffset -01:30>
Compare dates:
(jt/before? (jt/year 2020) (jt/year 2021))
;=> true
(jt/after? (jt/year 2021) (jt/year 2021))
;=> false
(let [expiration-date (jt/year 2010)
purchase-date (jt/year 2010)]
(jt/not-before? expiration-date purchase-date))
;=> true
(let [start-date (jt/year 2011)
cutoff-date (jt/year 2010)]
(jt/not-after? start-date cutoff-date))
;=> false
Time entities can be converted to other time entities if the target contains less information, e.g. (assuming we're in UTC time zone):
(jt/zoned-date-time (jt/offset-date-time 2015 9 28 1))
;=> #object[java.time.ZonedDateTime "2015-09-28T01:00Z"]
(jt/instant (jt/offset-date-time 2015 9 28 1))
;=> #object[java.time.Instant "2015-09-28T01:00:00Z"]
(jt/offset-time (jt/offset-date-time 2015 9 28 1))
;=> #object[java.time.OffsetTime "01:00Z"]
(jt/local-date-time (jt/offset-date-time 2015 9 28 1))
;=> #object[java.time.LocalDateTime "2015-09-28T01:00"]
(jt/local-time (jt/offset-time 1))
;=> #object[java.time.LocalTime 0x3a3cd6d5 "01:00"]
Converting an Instant to ZonedDateTime requires a time zone:
(jt/zoned-date-time (jt/instant 100) "UTC")
;=> #object[java.time.ZonedDateTime 0x291777c0 "1970-01-01T00:00:00.100Z[UTC]"]
Any date which can be converted to an instant, can also be converted to a
java.util.Date
:
(jt/java-date (jt/zoned-date-time 2015 9 28))
;=> #inst "2015-09-27T22:00:00.000-00:00"
(jt/java-date 50000)
;=> #inst "1970-01-01T00:00:50.000-00:00"
An instance of java.util.Date
serves the same purpose as the new
java.time.Instant
. It's a machine timestamp which isn't aware of the
time zone. Please, do not get confused by the way it is printed by the Clojure
printer - the UTC time zone is applied during formatting.
Sometimes you'll have to work with the legacy java.sql.{Date,Time,Timestamp}
types. The correspondence between the legacy types and the new Date-Time
entities is as follows:
java.sql.Date
<-> java.time.LocalDate
java.sql.Timestamp
<-> java.time.LocalDateTime
java.sql.Time
<-> java.time.LocalTime
(jt/sql-date 2015 9 28)
;=> #inst "2015-09-27T22:00:00.000-00:00"
(jt/sql-timestamp 2015 9 28 10 20 30 4000000)
;=> #inst "2015-09-28T09:20:30.004-00:00"
(jt/sql-time 10 20 30)
;=> #inst "1970-01-01T09:20:30.000-00:00"
The results of the above calls get printed as #inst
because all of the
java.sql.{Date,Time,Timestamp}
are subtypes of java.util.Date
.
Coincidentally, this makes it impossible to plug the java.sql.*
types into
the Clojure.Java-Time conversion graph.
Conversions to the legacy types also go the other way around:
(jt/local-date (jt/sql-date 2015 9 28))
;=> #object[java.time.LocalDate "2015-09-28"]
(jt/local-date-time (jt/sql-timestamp 2015 9 28 10 20 30 4000000))
;=> #object[java.time.LocalDateTime "2015-09-28T10:20:30.004"]
(jt/local-time (jt/sql-time 10 20 30))
;=> #object[java.time.LocalTime "10:20:30"]
If you add an optional [org.threeten/threeten-extra "1.2"]
dependency to the
project, you will get an Interval
, AmPm
, DayOfMonth
, DayOfYear
,
Quarter
and YearQuarter
data types as well as a couple more adjusters.
An interval can be constructed from two entities that can be converted to instants:
(jt/interval (jt/offset-date-time 2015 1 1) (jt/zoned-date-time 2016 1 1))
;=> #<org.threeten.extra.Interval 2015-01-01T00:00:00Z/2016-01-01T00:00:00Z>
(jt/move-start-by *1 (jt/duration 5 :days))
;=> #<org.threeten.extra.Interval 2015-01-06T00:00:00Z/2016-01-01T00:00:00Z>
(jt/move-end-by *1 (jt/duration 5 :days))
;=> #<org.threeten.extra.Interval 2015-01-06T00:00:00Z/2016-01-06T00:00:00Z>
(jt/contains? *1 (jt/offset-date-time 2015 1 1))
;=> false
Bonus! If you have Joda Time on the classpath (either directly, or via
clj-time
), you can seamlessly convert from Joda Time to Java Time types:
(java-time.repl/show-path org.joda.time.DateTime java.time.OffsetTime)
;=> {:cost 2.0,
; :path [[#<java_time.graph.Types@15e43c24 [org.joda.time.DateTime]>
; #<java_time.graph.Types@78a2235c [java.time.Instant java.time.ZoneId]>]
; [#<java_time.graph.Types@6d8ded1a [java.time.Instant java.time.ZoneId]>
; #<java_time.graph.Types@5360f6ae [java.time.OffsetTime]>]]}
(jt/offset-time (org.joda.time.DateTime/now))
;=> #<java.time.OffsetTime 22:00:00.000000000-00:00>
Clojure 1.9 added an Inst
protocol which is implemented for java.util.Date
and java.time.Instant
by
default. If you're stuck on Joda-Time, you can extend the
org.joda.time.ReadableInstant
, which includes both Instant
and DateTime
using the following:
(jt/when-joda-time-loaded
(extend-type org.joda.time.ReadableInstant
Inst (inst-ms* [inst] (.getMillis inst))))
This snippet isn't included in the Clojure.Java-Time code by default as both
the Inst
protocol and the Joda-Time types are external to the library.
Java Time introduced a concept of Clock
- a time entity which can seed the
dates, times and zones. However, there's no built-in facility which would allow
you to influence the date-times created using default constructors à la Joda's
DateTimeUtils/setCurrentMillisSystem
. Clojure.Java-Time tries to fix that with
the with-clock
macro and the corresponding with-clock-fn
function:
(jt/zone-id)
;=> #<java.time.ZoneRegion Europe/London>
(jt/with-clock (jt/system-clock "UTC")
(jt/zone-id))
;=> #<java.time.ZoneRegion UTC>
In addition to the built-in java.time
clocks, we provide a Mock clock which
can be very handy in testing:
(def clock (jt/mock-clock 0 "UTC"))
;=> #'user/clock
(jt/with-clock clock
(jt/instant))
;=> #object[java.time.Instant "1970-01-01T00:00:00Z"]
(jt/advance-clock! clock (jt/plus (jt/hours 5) (jt/minutes 20)))
;=> nil
(jt/with-clock clock
(jt/instant))
;=> #object[java.time.Instant "1970-01-01T05:20:00Z"]
(jt/set-clock! clock 0)
;=> nil
(jt/with-clock clock
(jt/instant))
;=> #object[java.time.Instant "1970-01-01T00:00:00Z"]
Clock overrides works for all of the date-time types.
Date-Time entities are composed of date fields, while Duration entities are
composed of time units. You can see all of the predefined fields and units
via the java-time.repl
ns:
(java-time.repl/show-fields)
;=> (:aligned-day-of-week-in-month
; :aligned-day-of-week-in-year
; :aligned-week-of-month
; :aligned-week-of-year
; :am-pm-of-day
; :clock-hour-of-am-pm
; ...)
(java-time.repl/show-units)
;=> (:centuries
; :days
; :decades
; :eras
; :forever
; :half-days
; ...)
You can obtain any field/unit like this:
(jt/field :year)
;=> #object[java.time.temporal.ChronoField "Year"]
(jt/unit :days)
;=> #object[java.time.temporal.ChronoUnit "Days"]
(jt/field (jt/local-date 2015) :year)
;=> #object[java.time.temporal.ChronoField "Year"]
You can obtain all of the fields/units of the temporal entity:
(jt/fields (jt/local-date))
;=> {:proleptic-month #object[java.time.temporal.ChronoField ...}
(jt/units (jt/duration))
;=> {:seconds #object[java.time.temporal.ChronoUnit "Seconds"],
; :nanos #object[java.time.temporal.ChronoUnit "Nanos"]}
By themselves the fields and units aren't very interesting. You can get the range of valid values for a field and a duration between two dates, but that's about it:
(jt/range (jt/field :year))
;=> #object[java.time.temporal.ValueRange "-999999999 - 999999999"]
(jt/range (jt/field :day-of-month))
;=> #object[java.time.temporal.ValueRange "1 - 28/31"]
(jt/time-between (jt/local-date 2015 9) (jt/local-date 2015 9 28) :days)
;=> 27
Fields and units become interesting in conjunction with properties. Java-Time doesn't support the concept of properties which is present in Joda-Time. There are reasons for that which I feel are only valid in a statically-typed API like Java's. In Clojure, properties allow expressing time entity modifications and queries uniformly across all of the entity types.
(def prop (jt/property (jt/local-date 2015 2 28) :day-of-month))
;=> #java_time.temporal.TemporalFieldProperty{...}
(jt/value prop)
;=> 28
(jt/with-min-value prop)
;=> #object[java.time.LocalDate "2015-02-01"]
(jt/with-value prop 20)
;=> #object[java.time.LocalDate "2015-02-20"]
(jt/with-max-value prop)
;=> #object[java.time.LocalDate "2015-02-28"]
(jt/properties (jt/local-date 2015 9 28))
;=> {:proleptic-month #java_time.temporal.TemporalFieldProperty{...}, ...}
Most of the temporal entity constructors with arities 1 to 3 use the conversion graph underneath. This provides for a very flexible way of defining the conversions while avoiding huge conditional statements and multiple definitions of the identical conversion logic. However, the flexibility comes with a cost:
Hopefully, the performance issue will be resolved in the future...
You can play with the conversion graph using the following helpers:
(java-time.repl/show-path org.joda.time.DateTime java.time.OffsetTime)
;=> {:cost 2.0,
; :path [[#<java_time.graph.Types@15e43c24 [org.joda.time.DateTime]>
; #<java_time.graph.Types@78a2235c [java.time.Instant java.time.ZoneId]>]
; [#<java_time.graph.Types@6d8ded1a [java.time.Instant java.time.ZoneId]>
; #<java_time.graph.Types@5360f6ae [java.time.OffsetTime]>]]}
(java-time.repl/show-graph)
;=> {1
; {org.threeten.extra.DayOfYear
; [[#object[java_time.graph.Types "[java.lang.Number]"]
; #object[java_time.graph.Conversion "Cost:1.0"]]],
; java.lang.Number
; [[#object[java_time.graph.Types "[java.time.Instant]"]
; #object[java_time.graph.Conversion "Cost:1.0"]]
; ...}}
Can you improve this documentation? These fine people already did:
Ambrose Bonnaire-Sergeant, Vadim Platonov, Vincent Cantin, Brett Rowberry, Jelle Licht, Brandon Ringe, Gert Goet, Jakub Holy & Stuart HallowayEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close