second-date.core — metabase/second-date 1.0.0

Replacement for metabase.util.date that consistently uses java.time instead of a mix of java.util.Date, java.sql.*, and Joda-Time.

add clj

(add unit amount)

(add t unit amount)

Return a temporal value relative to temporal value t by adding (or subtracting) a number of units. Returned value will be of same class as t.

(add (t/zoned-date-time "2019-11-05T15:44-08:00[US/Pacific]") :month 2) -> (t/zoned-date-time "2020-01-05T15:44-08:00[US/Pacific]")

add-units clj

Units supported by the add function.

adjuster clj multimethod

(adjuster k & args)

Get the custom TemporalAdjuster named by k.

;; adjust 2019-12-10T17:26 to the second week of the year (t/adjust #t "2019-12-10T17:26" (u.date/adjuster :week-of-year 2)) ;; -> #t "2019-01-06T17:26"

bucket clj

(bucket unit)

(bucket t unit)

Perform a truncation or extraction unit on temporal value t. (These two operations are collectively known as 'date bucketing' in Metabase code and MBQL, e.g. for date/time columns in MBQL :breakout (SQL GROUP BY)).

You can combine this function with group-by to do some date/time bucketing in Clojure-land:

(group-by #(bucket % :quarter-of-year) (map t/local-date ["2019-01-01" "2019-01-02" "2019-01-04"])) ;; -> {1 [(t/local-date "2019-01-01") (t/local-date "2019-01-02")], 2 [(t/local-date "2019-01-04")]}

compare-period-durations clj

(compare-period-durations d1 d2)

With two args: Compare two periods/durations. Returns a negative value if d1 is shorter than d2, zero if they are equal, or positive if d1 is longer than d2.

(u.date/compare-period-durations "P1Y" "P11M") ; -> 1 (i.e., 1 year is longer than 11 months)

You can combine this with period-duration to compare the duration between two temporal values against another duration:

(u.date/compare-period-durations (u.date/period-duration #t "2019-01-01" #t "2019-07-01") "P11M") ; -> -1

Note that this calculation is inexact, since it calclates relative to a fixed point in time, but should be sufficient for most if not all use cases.

comparison-range clj

(comparison-range unit comparison-type)

(comparison-range t unit comparison-type)

(comparison-range t
                  unit
                  comparison-type
                  {:keys [start end resolution]
                   :or {start :inclusive end :exclusive resolution :millisecond}
                   :as options})

Generate an range that of instants that when bucketed by unit would be =, <, <=, >, or >= to the value of an instant t bucketed by unit. (comparison-type is one of :=, :<, :<=, :>, or :>=.) By default, the start of the resulting range is inclusive, and the end exclusive; this can be tweaked by passing options.

;; Generate range off instants that have the same MONTH as Nov 18th (comparison-range (t/local-date "2019-11-18") :month := {:resolution :day}) ;; -> {:start (t/local-date "2019-11-01"), :end (t/local-date "2019-12-01")}

extract clj

(extract unit)

(extract t unit)

Extract a field such as :minute-of-hour from a temporal value t.

(extract (t/zoned-date-time "2019-11-05T15:44-08:00[US/Pacific]") :day-of-month) ;; -> 5

Values are returned as numbers (currently, always and integers, but this may change if we add support for :fraction-of-second in the future.)

extract-units clj

Units which return a (numerical, periodic) component of a date.

format clj

(format t)

(format formatter t)

Format any of the main java.time temporal instant classes as a String. Uses ISO-8601 by default, but formatter can be a java.time.format.DateTimeFormatter or keywords naming static formatters as understood by clojure.java-time. Check the value of java-time.format/predefined-formatters for all supported predefined formatters.

(second-date/format (t/zoned-date-time "2020-04-01T15:01-07:00[US/Pacific]")) ;; -> "2020-04-01T16:01:00-07:00"

(second-date/format (t/offset-date-time "2020-04-01T15:01-07:00")) ;; -> "2020-04-01T16:01:00-07:00"

(second-date/format (t/local-date-time "2020-04-01T15:01")) ;; -> "2020-04-01T15:01:00"

;; with a different formatter (second-date/format :basic-iso-date (t/local-date-time "2020-04-01T15:01")) ;; -> "20200401"

;; it even handles Instants (second-date/format :iso-week-date (t/instant "2020-04-01T15:01:00-07:00")) ;; "2020-W14-3Z"

format-sql clj

(format-sql t)

(format-sql formatter t)

Format a temporal value t as a SQL-style literal string (for most SQL databases). This is the same as ISO-8601 but uses a space rather than of a T to separate the date and time components.

greater-than-period-duration? clj

(greater-than-period-duration? d1 d2)

True if period/duration d1 is longer than period/duration d2.

less-than-period-duration? clj

(less-than-period-duration? d1 d2)

True if period/duration d1 is shorter than period/duration d2.

older-than? clj

(older-than? t duration)

True if temporal value t happened before some period/duration ago, compared to now. Prefer this over using t/before? to compare times to now because it is incredibly fussy about the classes of arguments it is passed.

;; did t happen more than 2 months ago? (older-than? t (t/months 2))

parse clj

(parse s)

(parse formatter s)

Parse almost any temporal literal String to a java.time object.

(second-date/parse "2020-04") ;; -> #object[java.time.LocalDate 0x1998e54f "2020-04-01"]

(second-date/parse "2020-04-01") ;; -> #object[java.time.LocalDate 0x1998e54f "2020-04-01"]

(second-date/parse "2020-04-01T15:01") ;; -> #object[java.time.LocalDateTime 0x121829b7 "2020-04-01T15:01"]

(second-date/parse "2020-04-01T15:01-07:00") ;; -> #object[java.time.OffsetDateTime 0x7dc126b0 "2020-04-01T15:01-07:00"]

(second-date/parse "2020-04-01T15:01-07:00[US/Pacific]") ;; -> #object[java.time.ZonedDateTime 0x351fb7c8 "2020-04-01T15:01-07:00[US/Pacific]"]

period-duration clj

(period-duration s)

(period-duration period)

(period-duration duration)

(period-duration period duration)

(period-duration start end)

Return the Duration between two temporal values x and y.

range clj

(range unit)

(range t unit)

(range t
       unit
       {:keys [start end resolution]
        :or {start :inclusive end :exclusive resolution :millisecond}})

Get a start (by default, inclusive) and end (by default, exclusive) pair of instants for a unit span of time containing t. e.g.

(range (t/zoned-date-time "2019-11-01T15:29:00Z[UTC]") :week) -> {:start (t/zoned-date-time "2019-10-27T00:00Z[UTC]") :end (t/zoned-date-time "2019-11-03T00:00Z[UTC]")}

truncate clj

(truncate unit)

(truncate t unit)

Truncate a temporal value t to the beginning of unit, e.g. :hour or :day. Not all truncation units are supported on all subclasses of Temporal — for example, you can't truncate a LocalTime to :month, for obvious reasons.

truncate-units clj

Valid date trucation units