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

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

*default-first-day-of-week* clj

If bound, this is used as the [[default-first-day-of-week]] if it was not explicitly specified.

-adjuster clj multimethod

(-adjuster adjuster-type options)

Implementation for adjuster.

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

A list of units that can be added to a temporal value.

adjuster clj

(adjuster adjuster-type)

(adjuster adjuster-type options)

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" (date/adjuster :week-of-year 2)) ;; -> #t "2019-01-06T17:26"

bucket clj

(bucket unit)

(bucket t unit)

(bucket t unit options)

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")]}

CoerceToDayOfWeek clj protocol

day-of-week clj

(day-of-week this)

Coerce this to a DayOfWeek.

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.

(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:

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

Note that this calculation is inexact, since it calculates 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 _first-day-of-week]
                   :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")}

current-locale-first-day-of-week clj

(current-locale-first-day-of-week)

Get the first day of the week for the current locale.

extract clj

(extract unit)

(extract t unit)

(extract t unit {:keys [first-day-of-week] :as _options})

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 formatter t locale)

Format temporal value t, by default as an ISO-8601 date/time/datetime string. By default t is formatted in a way that's appropriate for its type, e.g. a LocalDate is formatted as year-month-day. You can optionally pass formatter to format a different way. formatter can be:

1. A keyword name of a predefined formatter. Eval

   (keys java-time.format/predefined-formatters)

for a list of predefined formatters.

2. An instance of java.time.format.DateTimeFormatter. You can use utils in second-date.parse.builder to help create one of these formatters.

3. A format String e.g. YYYY-MM-dd

format-human-readable clj

(format-human-readable t locale)

Format a temporal value t in a human-friendly way for locale.

(format-human-readable #t "2021-04-02T14:42:09.524392-07:00[US/Pacific]" "es-MX") ;; -> "2 de abril de 2021 02:42:09 PM PDT"

format-rfc3339 clj

(format-rfc3339 t)

Format temporal value t, as an RFC3339 datetime string.

format-sql clj

(format-sql 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.

install-print-methods! clj

(install-print-methods!)

(install-print-methods! data-reader-symbol)

Add [[print-method]] and [[print-dup]] entries for various temporal classes so they print as string literals like

#second-date/t "2024-01-03T13:38:00.000"

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 s default-timezone-id)

With one arg, parse a temporal literal into a corresponding java.time class, such as LocalDate or OffsetDateTime. With a second arg, literals that do not explicitly specify a timezone are interpreted as being in timezone-id.

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 _first-day-of-week]
        :or {start :inclusive end :exclusive resolution :millisecond}
        :as options})

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]")}

Other options like :first-day-of-week are passed to truncate if it is needed.

truncate clj

(truncate unit)

(truncate t unit)

(truncate t unit {:keys [_first-day-of-week] :as options})

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.

options are passed to adjuster/-adjuster and can include things like :first-day-of-week or :first-week-of-year.

truncate-units clj

Valid date truncation units

WithTimeZoneSameInstant clj protocol

Protocol for converting a temporal value to an equivalent one in a given timezone.

with-time-zone-same-instant clj

(with-time-zone-same-instant t zone-id)

Convert a temporal value to an equivalent one in a given timezone. For local temporal values, this simply converts it to the corresponding offset/zoned type; for offset/zoned types, this applies an appropriate timezone shift.