diff --git a/dev/src/repl.clj b/dev/src/repl.clj index 6f289d2..fcb45b5 100644 --- a/dev/src/repl.clj +++ b/dev/src/repl.clj @@ -6,6 +6,10 @@ [tick.core :as t]) (:import (java.util TimeZone))) +(comment + (remove-ns 'repl) + ) + (clojure.tools.namespace.repl/set-refresh-dirs "src" "test") (set! *warn-on-reflection* true) diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md index 7a8c788..a10fc29 100644 --- a/docs/cheatsheet.md +++ b/docs/cheatsheet.md @@ -1,8 +1,9 @@ # Need to know -* Understand [the entities of java.time](https://github.com/juxt/tick#javatime) * a `temporal` is an entity that relates to the timeline (LocalDate, Instant, ZonedDateTime etc) -* a `temporal-amount` is a quantity of time - either a Duration or a Period +* a `temporal-amount` is an entity representing a quantity of time - either a Duration or a Period +* a basic understanding of [the main entities of java.time](https://github.com/juxt/tick#javatime) is required to use tick +* Where tick doesn’t provide the API you need, drop to [cljc.java-time](https://github.com/henryw374/cljc.java-time) # Naming (compared to java.time) @@ -22,28 +23,29 @@ All functions relating to `temporals` have names in the singular, whereas functi ## Construction -### Now +### Now + +zero-arity function for the required type ```clojure (t/date), (t/zoned-date-time), (t/instant), (t/...) ``` -temporarily change what clock is used to get the `now` or `where` information with `with-clock` +Temporarily change what clock is used to get the `now` or `where` information with `with-clock` ```clojure -(t/with-clock - ; the given 'clock' could be also be a zone, or a zoned-date-time etc - (t/instant "2023-08-23T15:49:21.941342Z") +(t/with-clock + (t/zoned-date-time "2023-08-23T20:00-10:00[Pacific/Honolulu]") (t/date)) ; => returns (t/date "2023-08-23") ``` -### Extraction - -for example, get the date part out of a zdt +### Extraction / Conversion ```clojure (t/date (t/zoned-date-time)) +(t/hour (t/zoned-date-time)) +(t/inst (t/zoned-date-time)) ``` set hours and smaller to zero @@ -60,6 +62,9 @@ set hours and smaller to zero (-> (t/time "10:10") (t/on (t/date))) + +; 'set' or 'adjust' a specific field +(t/with (t/date) (t/year 3030)) ``` ### from/to Strings @@ -120,7 +125,7 @@ round-trip to/from epoch millis ## Arithmetic ```clojure -(t/+ (t/of-minutes 5) (t/of-minutes 5) (t/of-minutes 5)) +(t/+ (t/of-minutes 5) (t/of-minutes 5) (t/of-minutes 5), ...) (t/- ...) ``` @@ -140,16 +145,17 @@ t/<, t/<=, t/=, ... t/max, t/max-by, t/min, t/min-by ``` -## contains +## contains/coincidence ```clojure -(t/coincident? {:tick/beginning x :tick/end y} z ) +(t/coincident? temporal-start temporal-end a-temporal)) ``` # Type Predicates ```clojure (t/date-time? x) +(t/...? x) ``` # Units @@ -159,6 +165,9 @@ t/APRIL, t/DECEMBER ... t/FRIDAY, t/MONDAY... + +(keys t/unit-map) => :nanos :days :seconds ... + ``` diff --git a/src/tick/core.cljc b/src/tick/core.cljc index 736f589..a16915c 100644 --- a/src/tick/core.cljc +++ b/src/tick/core.cljc @@ -1074,8 +1074,8 @@ (defn hence "current instant shifted forward by duration 'dur'" [dur] (p/forward-duration (now) dur)) -(defn midnight? [^Temporal t] - (cljc.java-time.duration/is-zero (cljc.java-time.duration/between t (beginning (p/date t))))) +(defn midnight? [t] + (clojure.core/= cljc.java-time.local-time/midnight (p/time t))) ;; Predicates (defn clock? "true if v is a clock?" [v] (cljc.java-time.extn.predicates/clock? v)) @@ -1391,24 +1391,17 @@ (if (> x y) x y)) (defn coincident? - "Does the span of time contain the given event? If the given event - is itself a span, then t must wholly contain the beginning and end - of the event." - [interval event] - (and - (<= (beginning interval) (beginning event)) - (>= (end interval) (end event)))) - -(comment - (require '[tick.core :as t]) - - (compare (t/instant "2020-02-05T00:00:00Z") (t/instant "2020-02-04T00:00:00Z")) - - (let [(def event {:tick/beginning (t/instant "2020-02-02T00:00:00Z") - :tick/end (t/instant "2020-02-04T00:00:00Z")})] - (t/coincident? (t/instant "2020-02-03T00:00:00Z") interval)) - - ) + "for the 2-arity ver, Does containing-interval wholly contain the given contained-interval? + + for the 3-arity, does the event lie within the span of time described by start and end" + ([containing-interval contained-interval] + (and + (<= (beginning containing-interval) (beginning contained-interval)) + (>= (end containing-interval) (end contained-interval)))) + ([start end event] + (and + (<= start event) + (>= end event)))) (defn max "Find the latest of the given arguments. Callers should ensure that no diff --git a/test/tick/api_test.cljc b/test/tick/api_test.cljc index caf8ae5..6d83ff0 100644 --- a/test/tick/api_test.cljc +++ b/test/tick/api_test.cljc @@ -365,11 +365,15 @@ (is (t/coincident? interval int-end)) (is (t/coincident? interval interval)) (is (not (t/coincident? interval (-> interval - (update :tick/end #(t/>> % (t/of-nanos 1))))))) - - - )) - + (update :tick/end #(t/>> % (t/of-nanos 1)))))))) + (testing "non-interval coincidence" + (doseq [[start-f new-amount] [[t/date t/of-days] [t/date-time t/of-hours]]] + (let [start (start-f) + end (t/>> start (new-amount 2))] + (is (t/coincident? start end (t/>> start (new-amount 1)))) + (is (not (t/coincident? start end (t/<< start (new-amount 1))))) + (is (t/coincident? start end start)) + (is (t/coincident? start end end)))))) (deftest day-of-week (let [days (fn [strings] (map t/day-of-week strings))]