Browse files

Add function and namespace docs for clj-time.core, fix found bugs / d…

…eficiencies.
  • Loading branch information...
1 parent 825de8b commit 4544de4061689529c127eb481f4c35ce04da3888 @mmcgrana mmcgrana committed Mar 11, 2010
Showing with 179 additions and 29 deletions.
  1. +174 −26 src/clj_time/core.clj
  2. +5 −3 test/clj_time/core_test.clj
View
200 src/clj_time/core.clj
@@ -1,4 +1,72 @@
(ns clj-time.core
+ "The core namespace for date-time operations in the clj-time library.
+
+ 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-signifigant 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 (epcoh).
+
+ 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 consturct 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
+
+ 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>
+
+ To represent the amount of time between two DateTime instances, use period.
+ The in-* functions can then be used to describe this period in terms of
+ various temporal units:
+
+ => (in-hours (period (date-time 1986 10 2) (date-time 1986 10 14)))
+ 288
+
+ An Interval is used to represent the span of time between two DateTime
+ instances. Construct one using interval, then query them using contains?,
+ overlaps?, and abuts?
+
+ => (contains? (interval (date-time 1986) (date-time 1990))
+ (date-time 1987))
+ true
+
+ Note that all functions in this namepsace 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."
(:refer-clojure :exclude (second contains?))
(:use [clojure.contrib.def :only (defvar)])
(:import
@@ -9,12 +77,20 @@
"DateTimeZone for UTC.")
(defn now []
+ "Returns a DateTime for the current instant in the UTC time zone."
(DateTime. #^DateTimeZone utc))
(defn epoch []
+ "Returns a DateTime for the begining of the Unix epoch in the UTC time zone."
(DateTime. (long 0) #^DateTimeZone utc))
(defn date-time
+ "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-signifigant components can be ommited, in which case
+ they will default to 1 or 0 as appropriate."
([year]
(date-time year 1 1 0 0 0 0))
([year month]
@@ -29,33 +105,56 @@
(date-time year month day hour minute second 0))
([#^Integer year #^Integer month #^Integer day #^Integer hour
#^Integer minute #^Integer second #^Integer millis]
- (DateTime. year month day hour minute second millis utc)))
+ (DateTime. year month day hour minute second millis #^DateTimeZone utc)))
-(defn year [#^DateTime dt]
+(defn year
+ "Return the year component of the given DateTime."
+ [#^DateTime dt]
(.getYear dt))
-(defn month [#^DateTime dt]
+(defn month
+ "Return the month-of-year component of the given DateTime. January is 1."
+ [#^DateTime dt]
(.getMonthOfYear dt))
-(defn day [#^DateTime dt]
+(defn day
+ "Return the day of month component of the given DateTime. Monday is 1 and
+ Sunday is 7."
+ [#^DateTime dt]
(.getDayOfMonth dt))
-(defn hour [#^DateTime dt]
+(defn hour
+ "Return the hour of day component of the given DateTime. A time of 12:01am
+ will have an hour component of 0."
+ [#^DateTime dt]
(.getHourOfDay dt))
-(defn minute [#^DateTime dt]
+(defn minute
+ "Return the minute of hour component of the given DateTime."
+ [#^DateTime dt]
(.getMinuteOfHour dt))
-(defn second [#^DateTime dt]
+(defn second
+ "Return the second-of-minute component of the given DateTime."
+ [#^DateTime dt]
(.getSecondOfMinute dt))
+(defn milli
+ "Return the millisecond-of-second component of the given DateTime."
+ [#^DateTime dt]
+ (.getMillisOfSecond dt))
+
(defn time-zone-for-offset
+ "Returns a DateTimeZone for the given offset, specified either in hours or
+ hours and minutes."
([hours]
(DateTimeZone/forOffsetHours hours))
([hours minutes]
(DateTimeZone/forOffsetHoursMinutes hours minutes)))
(defn time-zone-for-id [#^String id]
+ "Returns a DateTimeZone for the given ID, which must be in long form, e.g.
+ 'America/Matamoros'."
(DateTimeZone/forID id))
(defn default-time-zone []
@@ -76,70 +175,119 @@
[#^DateTime dt #^DateTimeZone tz]
(.withZoneRetainFields dt tz))
-(defn after? [#^DateTime dt-a #^DateTime dt-b]
+(defn after?
+ "Returns true if DateTime dt-a is strictly after DateTime dt-b."
+ [#^DateTime dt-a #^DateTime dt-b]
(.isAfter dt-a dt-b))
-(defn before? [#^DateTime dt-a #^DateTime dt-b]
+(defn before?
+ "Returns true if DateTime dt-a is strictly before DateTime dt-b."
+ [#^DateTime dt-a #^DateTime dt-b]
(.isBefore dt-a dt-b))
-(defn years [#^Integer n]
+(defn years
+ "Returns a Period representing the given number of years."
+ [#^Integer n]
(Period/years n))
-(defn months [#^Integer n]
+(defn months
+ "Returns a Period representing the given number of months."
+ [#^Integer n]
(Period/months n))
-(defn weeks [#^Integer n]
+(defn weeks
+ "Returns a Period representing the given number of weeks."
+ [#^Integer n]
(Period/weeks n))
-(defn days [#^Integer n]
+(defn days
+ "Returns a Period representing the given number of days."
+ [#^Integer n]
(Period/days n))
-(defn hours [#^Integer n]
+(defn hours
+ "Returns a Period representing the given number of hours."
+ [#^Integer n]
(Period/hours n))
-(defn minutes [#^Integer n]
+(defn minutes
+ "Returns a Period representing the given number of minutes."
+ [#^Integer n]
(Period/minutes n))
-(defn seconds [#^Integer n]
+(defn seconds
+ "Returns a Period representing the given number of seconds."
+ [#^Integer n]
(Period/seconds n))
(defn plus
+ "Returns a new DateTime corresponding to the given DateTime moved forwards by
+ the given Period(s)."
([#^DateTime dt #^Period p]
(.plus dt p))
([dt p & ps]
(reduce #(plus %1 %2) (plus dt p) ps)))
(defn minus
+ "Returns a new DateTime corresponding to the given DateTime moved backwards by
+ the given Period(s)."
([#^DateTime dt #^Period p]
(.minus dt p))
([dt p & ps]
(reduce #(minus %1 %2) (minus dt p) ps)))
-(defn period [#^DateTime dt-a #^DateTime dt-b]
+(defn period
+ "Returns a period corresponding to the difference between the two given
+ DateTimes."
+ [#^DateTime dt-a #^DateTime dt-b]
(Period. dt-a dt-b))
-(defn in-weeks [#^Period p]
+(defn in-weeks
+ "Returns the number of standard weeks in the given Period."
+ [#^Period p]
(.. p toStandardWeeks getWeeks))
-(defn in-days [#^Period p]
+(defn in-days
+ "Returns the number of standard days in the given Period."
+ [#^Period p]
(.. p toStandardDays getDays))
-(defn in-hours [#^Period p]
+(defn in-hours
+ "Returns the number of standard hours in the given Period."
+ [#^Period p]
(.. p toStandardHours getHours))
-(defn in-minutes [#^Period p]
+(defn in-minutes
+ "Returns the number of standard minutes in the given Period."
+ [#^Period p]
(.. p toStandardMinutes getMinutes))
-(defn in-seconds [#^Period p]
+(defn in-seconds
+ "Returns the number of standard seconds in the given Period."
+ [#^Period p]
(.. p toStandardSeconds getSeconds))
-(defn interval [#^DateTime dt-a #^DateTime dt-b]
+
+(defn interval
+ "Returns an interval representing the span between the two given DateTimes.
+ Note that intervals are closed on the left and open on the right."
+ [#^DateTime dt-a #^DateTime dt-b]
(Interval. dt-a dt-b))
-(defn contains? [#^Interval i #^DateTime dt]
+(defn contains?
+ "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."
+ [#^Interval i #^DateTime dt]
(.contains i dt))
-(defn overlaps? [#^Interval i-a #^Interval i-b]
+(defn overlaps?
+ "Returns true of the two given Intervals overlap. Note that intervals that
+ satisfy abuts? do not satisfy overlaps?"
+ [#^Interval i-a #^Interval i-b]
(.overlaps i-a i-b))
-(defn abuts? [#^Interval i-a #^Interval i-b]
+(defn abuts?
+ "Returns true if Interval i-a abuts i-b, i.e. then end of i-a is exactly the
+ beginning of i-b."
+ [#^Interval i-a #^Interval i-b]
(.abuts i-a i-b))
View
8 test/clj_time/core_test.clj
@@ -18,14 +18,16 @@
(is (= 1 (day d)))
(is (= 0 (hour d)))
(is (= 0 (minute d)))
- (is (= 0 (second d))))
- (let [d (date-time 1986 10 14 4 3 2)]
+ (is (= 0 (second d)))
+ (is (= 0 (milli d))))
+ (let [d (date-time 1986 10 14 4 3 2 1)]
(is (= 1986 (year d)))
(is (= 10 (month d)))
(is (= 14 (day d)))
(is (= 4 (hour d)))
(is (= 3 (minute d)))
- (is (= 2 (second d)))))
+ (is (= 2 (second d)))
+ (is (= 1 (milli d)))))
(deftest test-time-zone-for-offset
(is (= utc (time-zone-for-offset 0)))

0 comments on commit 4544de4

Please sign in to comment.