cljs-time.core
### The core namespace for date-time operations in the cljs-time library.
Create a DateTime instance with date-time (or a local DateTime 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)
#<DateTime 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)
#<DateTime 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 second to access the
corresponding fields:
=> (hour (date-time 1986 10 14 22))
22
=> (hour (local-date-time 1986 10 14 22))
22
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))
#<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
To find the amount of time encompased by an interval, use in-seconds 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 cljs-time.format. If you need to
ceorce date-times to or from other types, see cljs-time.coerce.
=
**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.
abuts?
(abuts? {start-a :start, end-a :end} {start-b :start, end-b :end})
Returns true if Interval a abuts b, i.e. then end of a is exactly the
beginning of b.
ago
(ago period)
Returns a DateTime a supplied period before the present.
e.g. `(-> 5 years ago)`
at-midnight
(at-midnight datetime)
conversion-error
(conversion-error from to)
date-midnight
(date-midnight year)(date-midnight year month)(date-midnight year month day)
Constructs and returns a new DateTime at midnight in UTC.
Specify the year, month of year, day of month. Note that month and day are
1-indexed. Any number of least-significant components can be ommited, in
which case they will default to 1.
date-time
(date-time year)(date-time year month)(date-time year month day)(date-time year month day hour)(date-time year month day hour minute)(date-time year month day hour minute second)(date-time year month day hour minute second millis)
Constructs and returns a new DateTime in UTC.
Specify the year, month of year, day of month, hour of day, minute if hour,
second of minute, and millisecond of second. Note that month and day are
1-indexed while hour, second, minute, and millis are 0-indexed.
Any number of least-significant components can be ommited, in which case
they will default to 1 or 0 as appropriate.
DateTimeProtocol
protocol
Interface for various date time functions
members
minute
(minute this)
Return the minute of hour component of the given date/time.
after?
(after? this that)
Returns true if DateTime 'this' is strictly after date/time 'that'.
hour
(hour this)
Return the hour of day component of the given date/time. A time of 12:01am will have an hour component of 0.
day
(day this)
Return the day of month component of the given date/time.
second
(second this)
Return the second of minute component of the given date/time.
plus-
(plus- this period)
Returns a new date/time corresponding to the given date/time moved forwards by the given Period(s).
day-of-week
(day-of-week this)
Return the day of week component of the given date/time. Monday is 1 and Sunday is 7
last-day-of-the-month-
(last-day-of-the-month- this)
Returns the last day of the month
month
(month this)
Return the month component of the given date/time.
equal?
(equal? this that)
Returns true if DateTime 'this' is strictly equal to date/time 'that'.
before?
(before? this that)
Returns true if DateTime 'this' is strictly before date/time 'that'.
year
(year this)
Return the year component of the given date/time.
week-number-of-year
(week-number-of-year this)
Returs the number of weeks in the year
minus-
(minus- this period)
Returns a new date/time corresponding to the given date/time moved backwards by the given Period(s).
sec
(sec this)
Return the second of minute component of the given date/time.
first-day-of-the-month-
(first-day-of-the-month- this)
Returns the first day of the month
milli
(milli this)
Return the millisecond of second component of the given date/time.
days
(days)(days n)
Given a number, returns a Period representing that many days.
Without an argument, returns a Period representing only days.
days?
(days? val)
Returns true if the given value is an instance of Days
default-ms-fn
(default-ms-fn)
default-time-zone
(default-time-zone)
Returns the default timezone map for the current environment.
deprecated
(deprecated message)
do-at*
(do-at* base-date-time body-fn)
earliest
(earliest dt1 dt2)(earliest dts)
Returns the earliest of the supplied DateTimes
end
(end in)
Returns the end DateTime of an Interval.
epoch
(epoch)
Returns a DateTime for the begining of the Unix epoch in the UTC time zone.
extend
(extend in & by)
Returns an Interval with an end DateTime the specified Period after the end
of the given Interval
first-day-of-the-month
(first-day-of-the-month dt)(first-day-of-the-month year month)
floor
(floor dt dt-fn)
Floors the given date-time dt to the given time unit dt-fn,
e.g. (floor (now) hour) returns (now) for all units
up to and including the hour
from-default-time-zone
(from-default-time-zone dt)
Assuming `dt` is in the UTC timezone, returns a DateTime
corresponding to the same point in calendar time as the given
DateTime, but for a correspondingly different absolute instant in
time in the default (local) timezone.
Note: This implementation uses the ECMAScript 5.1 implementation which
trades some historical daylight savings transition accuracy for simplicity.
see http://es5.github.io/#x15.9.1.8
from-now
(from-now period)
Returns a DateTime a supplied period after the present.
e.g. `(-> 30 minutes from-now)`
from-utc-time-zone
(from-utc-time-zone dt)
Assuming `dt` is in the local timezone, returns a UtcDateTime
corresponding to the same point in calendar time as the given
DateTime, but for a correspondingly different absolute instant in
time in the UTC timezone.
Note: This implementation uses the ECMAScript 5.1 implementation which
trades some historical daylight savings transition accuracy for simplicity.
see http://es5.github.io/#x15.9.1.8
hours
(hours)(hours n)
Given a number, returns a Period representing that many hours.
Without an argument, returns a Period representing only hours.
hours?
(hours? val)
Returns true if the given value is an instance of Hours
interval
(interval start end)
Returns an Interval representing the span between the two given DateTime.
Note that intervals are closed on the left and open on the right.
InTimeUnitProtocol
protocol
Interface for in-<time unit> functions
members
in-months
(in-months this)
Return the time in months
in-seconds
(in-seconds this)
Return the time in seconds.
in-minutes
(in-minutes this)
Return the time in minutes.
in-hours
(in-hours this)
Return the time in hours.
in-millis
(in-millis this)
Return the time in milliseconds.
last-day-of-the-month
(last-day-of-the-month dt)(last-day-of-the-month year month)
latest
(latest dt1 dt2)(latest dts)
Returns the latest of the supplied DateTimes
local-date
(local-date year month day)
Constructs and returns a new local DateTime.
Specify the year, month, and day. Does not deal with timezones.
local-date-time
(local-date-time year)(local-date-time year month)(local-date-time year month day)(local-date-time year month day hour)(local-date-time year month day hour minute)(local-date-time year month day hour minute second)(local-date-time year month day hour minute second millis)
Constructs and returns a new local DateTime.
Specify the year, month of year, day of month, hour of day, minute of hour,
second of minute, and millisecond of second. Note that month and day are
1-indexed while hour, second, minute, and millis are 0-indexed.
Any number of least-significant components can be ommited, in which case
they will default to 1 or 0 as appropriate.
millis
(millis)(millis n)
Given a number, returns a Period representing that many milliseconds.
Without an argument, returns a Period representing only milliseconds.
minus
(minus dt p)(minus dt p & ps)
Returns a new date/time object corresponding to the given date/time
moved backwards by the given Period(s).
minutes
(minutes)(minutes n)
Given a number, returns a Period representing that many minutes.
Without an argument, returns a Period representing only minutes.
minutes?
(minutes? val)
Returns true if the given value is an instance of Minutes
months
(months)(months n)
Given a number, returns a Period representing that many months.
Without an argument, returns a Period representing only months.
months?
(months? val)
Returns true if the given value is an instance of Months
now
(now)
Returns a DateTime for the current instant in the UTC time zone.
number-of-days-in-the-month
(number-of-days-in-the-month dt)(number-of-days-in-the-month year month)
offset-ms-fn
(offset-ms-fn offset)
overlap
(overlap i-a i-b)
Returns an Interval representing the overlap of the specified Intervals.
Returns nil if the Intervals do not overlap.
The first argument must not be nil.
If the second argument is nil then the overlap of the first argument
and a zero duration interval with both start and end times equal to the
current time is returned.
overlaps?
(overlaps? {start-a :start, end-a :end} {start-b :start, end-b :end})(overlaps? start-a end-a start-b end-b)
With 2 arguments: Returns true of the two given Intervals overlap.
Note that intervals that satisfy abuts? do not satisfy overlaps?
With 4 arguments: Returns true if the range specified by start-a and end-a
overlaps with the range specified by start-b and end-b.
period
(period period value)(period p1 v1 & kvs)
period-type?
(period-type? type x)
plus
(plus dt p)(plus dt p & ps)
Returns a new date/time corresponding to the given date/time moved
forwards by the given Period(s).
seconds
(seconds)(seconds n)
Given a number, returns a Period representing that many seconds.
Without an argument, returns a Period representing only seconds.
seconds?
(seconds? val)
Returns true if the given value is an instance of Seconds
start
(start in)
Returns the start DateTime of an Interval.
static-ms-fn
(static-ms-fn ms)
time-now
(time-now)
Returns a local DateTime for the current instant without date or time zone
in the current time zone.
time-zone-for-offset
(time-zone-for-offset hours)(time-zone-for-offset hours minutes)
Returns a timezone map for the given offset, specified either in hours or
hours and minutes.
to-default-time-zone
(to-default-time-zone dt)
Assuming `dt` is in the UTC timezone, returns a DateTime
corresponding to the same absolute instant in time as the given
DateTime, but with calendar fields corresponding to in the default
(local) timezone.
to-utc-time-zone
(to-utc-time-zone dt)
Assuming `dt` is in the Local timezone, returns a UtcDateTime
corresponding to the same absolute instant in time as the given
DateTime, but with calendar fields corresponding to in the UTC
timezone.
today
(today)
Constructs and returns a new local DateTime representing today's date.
local DateTime objects do not deal with timezones at all.
today-at
(today-at hours minutes seconds millis)(today-at hours minutes seconds)(today-at hours minutes)
today-at-midnight
(today-at-midnight)
Returns a DateTime for today at midnight in the UTC time zone.
weeks
(weeks)(weeks n)
Given a number, returns a Period representing that many weeks.
Without an argument, returns a Period representing only weeks.
weeks?
(weeks? val)
Returns true if the given value is an instance of Weeks
within?
(within? {:keys [start end]} date)(within? start end date)
With 2 arguments: Returns true if the given Interval contains the given
DateTime. Note that if the DateTime is exactly equal to the
end of the interval, this function returns false.
With 3 arguments: Returns true if the start DateTime is
equal to or before and the end DateTime is equal to or after the test
DateTime.
years
(years)(years n)
Given a number, returns a Period representing that many years.
Without an argument, returns a Period representing only years.
years?
(years? val)
Returns true if the given value is an instance of Years
yesterday
(yesterday)
Returns a DateTime for yesterday relative to now