A date and time library for ClojureScript, immitating the clj-time library.
This is my crude and naïve attempt at replicating some of the functionality in clj-time. This is in no way a drop-in clojurescript replacement for clj-time, however the goal is that over time I can hopefully replicate enough of the clj-time API and functionality to make this library "good enough" for other projects.
This library is currently leaning on the Google Closure goog.date library for basic date/time functionality. The date objects in this library are mutable, however any operations that alter a date object return a copy, leaving the referenced date object alone. In the future, immutable date objects will be preferred.
cljs-time
artifacts are released to Clojars.
If you are using Maven, add the following repository definition to your pom.xml
:
<repository>
<id>clojars.org</id>
<url>http://clojars.org/repo</url>
</repository>
With Leiningen:
[com.andrewmcveigh/cljs-time "0.1.2"]
With Maven:
<dependency>
<groupId>com.andrewmcveigh</groupId>
<artifactId>cljs-time</artifactId>
<version>0.1.2</version>
</dependency>
Please open issues against the cljs-time repo on Github.
Note: version 0.1.2 follows the API of clj-time 0.6.0.
So far, most of the clj-time API has been implemented, apart from the bits that deal with local time(s). Some of the parts that don't make sense in clojurescript, such as Java interop, have been left out.
The majority of the tests from clj-time (that don't deal with local-time) have been copied over, and are passing.
API documentation is available.
The main namespace for date-time operations in the cljs-time
library is cljs-time.core
.
=> (use 'cljs-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 (epoch)
.
Once you have a date-time, use accessors like hour
and second
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
:
=> (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
:
=> (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 time-zone-for-id
and default-time-zone
functions and the utc
Var to construct or get DateTimeZone
instances.
If you only want a date with no time component, consider using the local-date
and today
functions.
These return 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>
The functions after?
and before?
determine the relative position of two
DateTime instances:
=> (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>
An Interval
is used to represent the span of time between two DateTime
instances. Construct one using interval
, then query them using within?
,
overlaps?
, and abuts?
=> (within? (interval (date-time 1986) (date-time 1990))
(date-time 1987))
true
The in-seconds
and 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 cljs-time.format
:
=> (use 'cljs-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:
=> (show-formatters)
Remember that 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")
#<20100311T000000>
=> (unparse custom-formatter (date-time 2010 10 3))
"20101003"
cljs-time.core/today-at
returns a moment in time at the given hour, minute and second
on the current date:
=> (today-at 12 00)
#<20130329T120000>
=> (today-at 12 00 05)
#<20130329T120005>
The namespace cljs-time.coerce
contains utility functions for coercing Google Closure DateTime
instances to and from various other types:
=> (use 'cljs-time.coerce)
For example, to convert a Joda DateTime
to and from a Java long
:
=> (to-long (date-time 1998 4 25))
893462400000
=> (from-long 893462400000)
#<19980425T000000>
And by the magic of protocols you can pass in an isoformat string and get the unix epoch milliseconds:
=> (to-long "2013-08-01")
1375315200000
Running the tests:
$ lein test-all
(assumes Leiningen 2.x)
The complete API documentation is also available (marginalia generated).
Copyright © 2013 Andrew Mcveigh
Distributed under the Eclipse Public License, the same as Clojure.