Clj-time 0.4.4 API documentation

A date and time library for Clojure, wrapping Joda Time.

clj-time.coerce

Utilites to coerce Joda DateTime instances to and from various other types.
For example, to convert a Joda DateTime to and from a Java long:

  => (to-long (date-time 1998 4 25))
  893462400000

  => (from-long 893462400000)
  #<DateTime 1998-04-25T00:00:00.000Z>

Public variables and functions:

clj-time.core

The core namespace for date-time operations in the clj-time library.

Create a DateTime instance with date-time (or a LocalDateTime instance with local-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>

  => (local-date-time 1986 10 14 4 3 27 456)
  #<LocalDateTime 1986-10-14T04:03:27.456>

Less-significant fields can be omitted:

  => (date-time 1986 10 14)
  #<DateTime 1986-10-14T00:00:00.000Z>

  => (local-date-time 1986 10 14)
  #<LocalDateTime 1986-10-14T00:00:00.000>

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 sec to access the
corresponding fields:

  => (hour (date-time 1986 10 14 22))
  22

  => (hour (local-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 constgruct or get DateTimeZone
instances.

The functions after? and before? determine the relative position of two
DateTime instances:

  => (after? (date-time 1986 10) (date-time 1986 9))
  true

  => (after? (local-date-time 1986 10) (local-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>

  => (plus (local-date-time 1986 10 14) (months 1) (weeks 3))
  #<LocalDateTime 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

To find the amount of time encompased by an interval, use in-secs and
in-minutes:

  => (in-minutes (interval (date-time 1986 10 2) (date-time 1986 10 14)))
  17280

Note that all functions in this namespace work with Joda objects or ints. If
you need to print or parse date-times, see clj-time.format. If you need to
ceorce date-times to or from other types, see clj-time.coerce.

Public variables and functions:

clj-time.format

Utilities for parsing and unparsing DateTimes as Strings.

Parsing and printing are controlled by formatters. You can either use one
of the built in ISO 8601 and a single RFC 822 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)

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"

By default the parse function always returns a DateTime instance with a UTC
time zone, and the unparse function always represents a given DateTime
instance in UTC. A formatter can be modified to different timezones, locales,
etc with the functions with-zone, with-locale, with-chronology, and
with-pivot-year.

Public variables and functions:

clj-time.local

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 (local-now).

 (to-local-date-time obj) returns a local date-time instance 
 retaining the time fields.

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-local-time (local-now) :basic-date-time) formats an obj using
a formatter in *local-formatters* corresponding to the  format-key
passed in.

Public variables and functions: