A date and time library for ClojureScript, imitating the API of the clj-time library.
Cljs-time is an attempt at replicating the functionality and API of clj-time. This is not a drop-in clojurescript replacement for clj-time, however the goal is that over time enough functionality of the clj-time API can be replicated 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.
Artifacts
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>
The Most Recent Release
With Leiningen:
;; Stable
[com.andrewmcveigh/cljs-time "0.5.2"]
Bugs and Enhancements
Please open issues against the cljs-time repo on Github.
Note: version 0.5. follows the API of clj-time 0.11.0.*
API
Most of the clj-time API has been implemented. Some of the parts that don't make sense in clojurescript, such as Java interop, and java.sql.* have been left out. Timezone functionality in javascript is minimal, and therefore so is cljs-time's.
The majority of the tests from clj-time have been ported, and are passing.
API documentation is available.
Usage
Note: Equality in goog.date.* (and also with plain javascript dates) is not the same as in Joda/clj-time. Two date objects representing the same instant in time in goog.date.* are not equal.
If you need to test for equality use either cljs-time.core/=
, or
optionally you can require the cljs-time.extend
namespace which will
extend the goog.date.* datatypes, so that clojure.core/= works as
expected.
If you want your goog.date.* serializable with pr-str
, require
cljs-time.instant
namespace.
cljs-time.core
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 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
cljs-time.format
If you need to parse or print date-times, use cljs-time.format
:
=> (use 'cljs-time.format)
Printing and parsing 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 SSS
is milliseconds.
Once you have a formatter, parsing and printing are straight-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>
cljs-time.coerce
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 goog.date DateTime
to and from a js Number
:
=> (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
Development
Running the tests:
$ boot test-all
OR
$ boot auto-test
Getting a REPL
$ boot repl # (or jack-in from cider/etc)
boot.user> (node-repl)
clojurescript node.js repl server listening on 56950
to quit, type: :cljs/quit
nil
cljs.user> (+ 1 1)
2
Documentation
The complete API documentation is also available.
License
Copyright © 2013-2016 Andrew Mcveigh
Distributed under the Eclipse Public License, the same as Clojure.