simple-time.core documentation

+
(+)(+ datetime & timespans)(+ timespan & timespans)
Adds the specified timespans to datetime. When a datetime is involved, there
must be only one datetime.

  Example:
    (+ datetime) -> datetime
    (+ datetime & timespan*) -> datetime

    (+) -> (timespan 0)
    (+ timespan) -> timespan
    (+ timespan & timespan*) -> timespan

    (+ (datetime 2013 12 25) (days->timespan 7)) -> (datetime 2014 1 1)
    (+ (hours->timespan 1) (minutes->timespan 2)) -> (timespan 1 2 0)
Source
-
(- timespan)(- datetime datetime)(- datetime & timespans)(- timespan & timespans)
Subtracts datetimes and timespans.

Example:
  (- timespan) -> -timespan
  (- datetime datetime) -> timespan
  (- datetime & timespan*) -> datetime
  (- timespan & timespan*) -> timespan

  (- (datetime 2014 1 1) (days->timespan 7)) -> (datetime 2013 12 25)
  (- (datetime 2014 1 1) (datetime 2013 12 25)) -> (days->timespan 7)
  (- (datetime 2013 12 25) (datetime 2014 1 1)) -> (days->timespan -7)
Source
<
Tests one or more datetimes or timespans for increasing order.

Example:
  (< (datetime 2014 1 1) (datetime 2014 1 2))
Source
<=
Tests one or more datetimes or timespans for increasing order.

Example:
  (<= (datetime 2014 1 1) (datetime 2014 1 1) (datetime 2014 1 2))
Source
=
Tests one or more datetimes or timespans for equality.

Example:
  (= (datetime 2014 1 1) (datetime 2014 1 1))
Source
>
Tests one or more datetimes or timespans for decreasing order.

Example:
  (> (datetime 2014 1 2) (datetime 2014 1 1))
Source
>=
Tests one or more datetimes or timespans for decreasing order.

Example:
  (>= (datetime 2014 1 2) (datetime 2014 1 2) (datetime 2014 1 1))
Source
add-days
(add-days datetime days)
Adds the specified number of days to a datetime.

Example:
  (add-days (datetime 2014 1 1) 60) -> (datetime 2014 3 2)
Source
add-hours
(add-hours datetime hours)
Adds the specified number of hours to a datetime.

Example:
  (add-hours (datetime 2014 1 1) 42) -> (datetime 2014 1 2 18 0 0)
Source
add-milliseconds
(add-milliseconds datetime milliseconds)
Adds the specified number of milliseconds to a datetime.

Example:
  (add-milliseconds (datetime 2014 1 1) 42) -> (datetime 2014 1 1 0 0 0 42)
Source
add-minutes
(add-minutes datetime minutes)
Adds the specified number of minutes to a datetime.

Example:
  (add-minutes (datetime 2014 1 1) 42) -> (datetime 2014 1 1 0 42 0)
Source
add-months
(add-months datetime months)
Adds the specified number of months to a datetime.

Example:
  (add-months (datetime 2014 1 1) 6) -> (datetime 2014 7 1)
  (add-months (datetime 2014 1 31) 1) -> (datetime 2014 1 28)
Source
add-seconds
(add-seconds datetime seconds)
Adds the specified number of seconds to a datetime.

Example:
  (add-seconds (datetime 2014 1 1) 42) -> (datetime 2014 1 1 0 0 42)
Source
add-years
(add-years datetime years)
Adds the specified number of years to a datetime.

Example:
  (add-years (datetime 2014 1 1) 6) -> (datetime 2020 1 1)
  (add-years (datetime 2012 2 29) 1) -> (datetime 2013 2 28)
Source
datetime
(datetime)(datetime epoch)(datetime year month day)(datetime year month day hour minute second)(datetime year month day hour minute second millisecond)
Creates a new datetime.

Examples:

  (datetime) -> the current time
  (datetime 1390631873847) -> a java epoch (ms since Jan 1, 1970)
  (datetime 2014 1 2) -> just the date
  (datetime 2014 1 2 12 34 56) -> date & time
  (datetime 2014 1 2 12 34 56 789) -> date & time w/ milliseconds
Source
datetime->date
(datetime->date datetime)
Returns the date with no time component.

Example:
  (datetime->date (datetime 2014 1 2 12 34 56)) -> (datetime 2014 1 2)
Source
datetime->day
(datetime->day datetime)
Returns the day (1-31) of the specified date.

Example:
  => (datetime->day (datetime 2014 1 2))
  2
Source
datetime->day-of-week
(datetime->day-of-week datetime)
Returns the day of the week (1-7) of the specified date.

Example:
  => (datetime->day-of-week (datetime 2014 1 6)) ; Monday
  1
  => (datetime->day-of-week (datetime 2014 1 5)) ; Sunday
  7
Source
datetime->day-of-year
(datetime->day-of-year datetime)
Returns the day of the year (1-366) of the specified date.

Example:
  => (datetime->day-of-year (datetime 2014 1 1))   ; New year's day
  1
  => (datetime->day-of-year (datetime 2014 12 31)) ; New year's eve
  365
  => (datetime->day-of-year (datetime 2012 12 31)) ; Leap year
  366
Source
datetime->epoch
(datetime->epoch datetime)
Returns the java epoch (milliseconds since Jan 1, 1970) of the specified date

Source
datetime->hour
(datetime->hour datetime)
Returns the hour (0-23) of the specified date.

Example:
  => (datetime->hour (datetime 2014 1 2 12 34 56))
  12
Source
datetime->millisecond
(datetime->millisecond datetime)
Returns the milliseconds (0-999) of the specified date.

Example:
  => (datetime->millisecond (datetime 2014 1 2 12 34 56 789))
  789
Source
datetime->minute
(datetime->minute datetime)
Returns the minute (0-59) of the specified date.

Example:
  => (datetime->minute (datetime 2014 1 2 12 34 56))
  34
Source
datetime->month
(datetime->month datetime)
Returns the month (1-12) of the specified date.

Example:
  => (datetime->month (datetime 2014 1 2))
  1
Source
datetime->second
(datetime->second datetime)
Returns the second (0-59) of the specified date.

Example:
  => (datetime->second (datetime 2014 1 2 12 34 56))
  56
Source
datetime->time-of-day
(datetime->time-of-day datetime)
Returns a timespan based on the time of day.

Example:
  (datetime->time-of-day (datetime 2014 1 2 12 34 56)) -> (timespan 12 34 56))
  (datetime->time-of-day (datetime 2014 1 2 12 34 56 789)) -> (timespan 0 12 34 56 789))
Source
datetime->year
(datetime->year datetime)
Returns the year of the specified date.

Example:
  => (datetime->year (datetime 2014 1 2))
  2014
Source
datetime?
(datetime? value)
Returns whether the specified value is a datetime.

Source
days->timespan
(days->timespan days)
Returns a timespan with the specified number of days.

Example:
  (days->timespan 42) -> 42 days
Source
days-in-month
(days-in-month year month)(days-in-month datetime)
How many days are in a given month and year?

Example:
  (days-in-month 2014 1) -> 31
  (days-in-month 2014 2) -> 28
  (days-in-month 2012 2) -> 29

  (days-in-month (datetime 2014 1 15)) -> 31
Source
duration
(duration timespan)
The absolute value of a timespan.

Example:
  (duration (timespan -100)) -> (timespan 100)
Source
format
(format datetime)(format datetime format)
Formats a datetime and returns a string representation of the value.

Example:
  => (format (datetime 2014 1 2 12 34 56 789))
  "2014-01-02T12:34:56.789"

  => (format (datetime 2014 1 2 12 34 56 789) "YYYYmmDD")
  "20143402"

  => (format (datetime 2014 1 2 12 34 56 789) :medium-date-time)
  "Jan 2, 2014 12:34:56 PM"
Source
format-all
(format-all datetime)
Format a datetime using all known formatters. Useful for exploring the
built-in formatters.

  Example:
    (format-all (datetime 2014 1 2 12 34 56 789))
Source
formatter
(formatter format)
Returns a formatter based on the specified format. If a string is supplied,
creates a new, memoized formatter. If a keyword is supplied, returns a
pre-defined formatter. See format-all for the set of pre-defined formatters.
Generally, this isn't used directly - the same types can be passed to parse and
format.

  Example:
    (formatter "YYYYmmDD")
    (formatter :date-time)
Source
formatters
Source
hours->timespan
(hours->timespan hours)
Returns a timespan with the specified number of hours.

Example:
  (hours->timespan 42) -> 42 hours
Source
milliseconds->timespan
(milliseconds->timespan milliseconds)
Returns a timespan with the specified number of milliseconds.

Example:
  (milliseconds->timespan 42) -> 42 milliseconds
Source
minutes->timespan
(minutes->timespan minutes)
Returns a timespan with the specified number of minutes.

Example:
  (minutes->timespan 42) -> 42 minutes
Source
not=
Tests one or more datetimes or timespans for inequality.

Example:
  (not= (datetime 2014 1 1) (datetime 2014 1 2))
Source
now
(now)
Returns the current datetime.

Source
parse
(parse value)(parse value format)
Parses a string into a datetime based on the specified format. If no format
is provided, ISO8601 is used by default.

  Example:
    (parse "2014-01-02T12:34:56.789") -> (datetime 2014 1 2 12 34 56 789)
    (parse "20140102" "YYYYmmDD") -> (datetime 2014 1 2)
    (parse "Jan 2, 2014 12:34:56 PM" :medium-date-time) -> (datetime 2014 1 2 12 34 56)
Source
range
(range start)(range start end)(range start end step)
Returns a lazy sequence of datetimes, beginning with start (inclusive) through
end (exclusive). If end is not specified, the sequence will be infinite. The
parameter step specifies the interval. It can be a number (increase by that
number of days), a timespan (increase by that amount of time), or any function
that takes a single datetime and returns another datetime. If a function is used
to step, it must be free of side effects.

  Example:
    (->> (range (datetime 2014 1 1)) (take 4))
    (range (datetime 2014 1 1) (datetime 2014 1 4))
    (range (datetime 2014 1 1) (datetime 2014 1 4) 2)
    (range (datetime 2014 1 1) (datetime 2013 12 25) -2)
    (range (datetime 2014 1 1 0 0 0) (datetime 2014 1 1 6 0 0) (hours->timespan 2))
    (range (datetime 2013 11 1) (datetime 2014 6 1)
           (fn [dt]
             (let [dt (add-months dt 1)
                   y (datetime->year dt)
                   m (datetime->month dt)
                   d (days-in-month dt)]
             (datetime y m d))))
Source
seconds->timespan
(seconds->timespan seconds)
Returns a timespan with the specified number of seconds.

Example:
  (seconds->timespan 42) -> 42 seconds
Source
timespan
(timespan)(timespan milliseconds)(timespan hours minutes seconds)(timespan days hours minutes seconds)(timespan days hours minutes seconds milliseconds)
Creates a new timespan, which represents a duration of time.

Examples:

  (timespan) -> 0 ms
  (timespan 100) -> 100 ms
  (timespan 1 2 3) -> 1 hr, 2 min, 3 sec
  (timespan 1 2 3 4) -> 1 day, 2 hr, 3 min, 4 sec
  (timespan 1 2 3 4 5) -> 1 day, 2 hr, 3 min, 4 sec, 5 ms
Source
timespan->days
(timespan->days timespan)
Returns the days element of the specified timespan.

Example:
  => (timespan->days (timespan 1 2 3 4 5))
  1

See also: timespan->total-days
Source
timespan->hours
(timespan->hours timespan)
Returns the hours element (0-23) of the specified timespan.

Example:
  => (timespan->hours (timespan 1 2 3 4 5))
  2
  => (timespan->hours (hours->timespan 36))
  12

See also: timespan->total-hours
Source
timespan->milliseconds
(timespan->milliseconds timespan)
Returns the milliseconds element (0-999) of the specified timespan.

Example:
  => (timespan->milliseconds (timespan 1 2 3 4 5))
  5
  => (timespan->milliseconds (milliseconds->timespan 1234))
  234

See also: timespan->total-milliseconds
Source
timespan->minutes
(timespan->minutes timespan)
Returns the minutes element (0-59) of the specified timespan.

Example:
  => (timespan->minutes (timespan 1 2 3 4 5))
  3
  => (timespan->minutes (minutes->timespan 90))
  30

See also: timespan->total-minutes
Source
timespan->seconds
(timespan->seconds timespan)
Returns the seconds element (0-59) of the specified timespan.

Example:
  => (timespan->seconds (timespan 1 2 3 4 5))
  4
  => (timespan->seconds (seconds->timespan 90))
  30

See also: timespan->total-seconds
Source
timespan->total-days
(timespan->total-days timespan)
Returns the total number of days, whole and fractional, that the specified
instance represents.

  Example:
    => (timespan->total-days (timespan 1 2 3 4 5))
    2084089/1920000
    => (double *1)
    1.085463020833333

  See also: timespan->days
Source
timespan->total-hours
(timespan->total-hours timespan)
Returns the total number of hours, whole and fractional, that the specified
instance represents.

  Example:
    => (timespan->total-hours (timespan 1 2 3 4 5))
    2084089/80000
    => (double *1)
    26.0511125

  See also: timespan->hours
Source
timespan->total-milliseconds
(timespan->total-milliseconds timespan)
Returns the total number of milliseconds that the specified instance represents.

Example:
  => (timespan->total-milliseconds (timespan 1 2 3 4 5))
  93784005

See also: timespan->milliseconds
Source
timespan->total-minutes
(timespan->total-minutes timespan)
Returns the total number of minutes, whole and fractional, that the specified
instance represents.

  Example:
    => (timespan->total-minutes (timespan 1 2 3 4 5))
    6252267/4000
    => (double *1)
    1563.06675

  See also: timespan->minutes
Source
timespan->total-seconds
(timespan->total-seconds timespan)
Returns the total number of seconds, whole and fractional, that the specified
instance represents.

  Example:
    => (timespan->total-seconds (timespan 1 2 3 4 5))
    18756801/200
    => (double *1)
    93784.005

  See also: timespan->seconds
Source
timespan?
(timespan? value)
Returns whether the specified value is a timespan.

Source
today
(today)
Returns the current day with no time.

Source
total-months
(total-months start end)
EXPERIMENTAL - May change or be removed.

Calculates the total number of months between start (inclusive) and end
(exclusive). The calculation used is the sum of 1/days-in-month for each date
in the range.
Source
utc-now
(utc-now)
Returns the current datetime in the UTC time zone.

Source
with-precision
(with-precision precision)(with-precision precision datetime)
Returns a datetime or timespan with the desired precision. precision is a set
of fields to retain. If :year is not specified, returns a timespan. Available
fields are :year, :month, :day, :hour, :minute, :second, and :millisecond. When
a datetime or timespan is not specified, returns a function that takes a
datetime or timespan and returns it with the specified precision.

  Example:
    (with-precision #{:year :month} (datetime 2014 1 15)) -> (datetime 2014 1 1)
    (with-precision #{:year :month} (datetime 2014 1 15 12 34 56 789)) -> (datetime 2014 1 1)
    (with-precision #{:hour :minute :second} (datetime 2014 1 15 12 34 56 789)) -> (timespan 12 34 56)

    (def ym (with-precision #{:year :month}))
    (ym (datetime 2014 1 15)) -> (datetime 2014 1 1)

  Note: You cannot specify :month without :year
Source