tupelo.java-time — tupelo 23.03.17

*zone-id* clj

->field-strs clj

(->field-strs temporal)

Inputs: [temporal :- Temporal] Returns: #:s{Keyword s/Str}

Given an Temporal value, returns a map with string values for the component fields.

(->field-strs (Instant/parse '2037-07-14t01:02:03.012345678Z')) =>
  {:year-4   '2037'
   :year-2   '37'
   :month-2  '07'
   :day-2    '14'
   :hour-2   '01'
   :min-2    '02'
   :sec-2    '03'
   :micros-6 '012345'
   :millis-3 '012'
   :nanos-9  '012345678'
   }

->Instant clj

(->Instant arg)

Coerces an Instant, ZonedDateTime, or org.joda.time.ReadableInstant => Instant

->LocalDate clj

(->LocalDate arg)

Inputs: [arg] Returns: LocalDate

->str-HHMMSS clj

(->str-HHMMSS temporal)

Inputs: [temporal :- Temporal] Returns: s/Str

Given an Instant like '2037-07-14t11:22:33.123456789Z', returns a string with the HHMMSS format like '112233'

->str-iso clj

(->str-iso temporal)

Inputs: [temporal :- Temporal] Returns: s/Str

Given an Instant or ZonedDateTime, returns a ISO 8601 datetime string like 2018-09-05T23:05:19.123Z

->str-iso-nice clj

(->str-iso-nice temporal)

Inputs: [temporal :- Temporal] Returns: s/Str

Given an Instant or ZonedDateTime, returns an ISO date-time string like 2018-09-05 23:05:19.123Z (with a space instead of T)

->str-YYYY-MM-DD clj

(->str-YYYY-MM-DD temporal)

Inputs: [temporal :- Temporal] Returns: s/Str

Given an Instant or ZonedDateTime, returns a string like 2018-09-05

->str-YYYYMMDD clj

(->str-YYYYMMDD temporal)

Inputs: [temporal :- Temporal] Returns: s/Str

Given an Instant or ZonedDateTime, returns a compact date-time string like 2018-09-05 23:05:19.123Z => 20180905

->str-YYYYMMDD-HHMMSS clj

(->str-YYYYMMDD-HHMMSS temporal)

Inputs: [temporal :- Temporal] Returns: s/Str

Given an Instant or ZonedDateTime, returns a compact date-time string like 2018-09-05 23:05:19.123Z => 20180905-230519

->year-quarter clj

(->year-quarter arg)

Inputs: [arg] Returns: tsk/Quarter

Given a date-ish value (e.g. LocalDate, et al), returns the quarter of the year as one of #{ :Q1 :Q2 :Q3 :Q4 }

->ZonedDateTime clj

(->ZonedDateTime arg)

Coerces a org.joda.time.ReadableInstant to java.time.ZonedDateTime

between->units clj

(between->units chrono-unit t1 t2)

Inputs: [chrono-unit :- ChronoUnit t1 :- Temporal t2 :- Temporal] Returns: s/Int

Returns the integer number of ChronoUnit values between two temporal values, truncating any fraction. Example:

  (let [i1      (->Instant "1987-11-22t01:30:00z")
        i2      (->Instant "1987-11-22t03:29:00z")
        delta   (between ChronoUnit/HOURS i1 i2) ]  ...)

yields delta=1 since 1hr 59min is truncated to 1 hour.

fixed-point? clj

(fixed-point? it)

Returns true iff arg represents a fixed point in time. Examples:

[java.time ZonedDateTime Instant] [org.joda.time DateTime Instant ReadableInstant]

increasing-or-equal? clj

(increasing-or-equal? t1 t2 t3)

Inputs: [t1 :- IncreasingComparable t2 :- IncreasingComparable t3 :- IncreasingComparable] Returns: s/Bool

Returns true iff times [t1 t2 t3] is in strictly increasing order (closed interval)

increasing? clj

(increasing? t1 t2 t3)

Inputs: [t1 :- IncreasingComparable t2 :- IncreasingComparable t3 :- IncreasingComparable] Returns: s/Bool

Returns true iff times [t1 t2 t3] is in strictly increasing order (open interval)

IncreasingComparable clj

Instant-str? clj

(Instant-str? s)

Inputs: [s :- s/Str] Returns: s/Bool

Returns true if string matches a Instant (ISO 8601) pattern like '1999-12-31T11:22:33Z'

Instant? clj

(Instant? it)

Returns true iff arg is an instance of java.time.Instant

iso-str-nice-str? clj

(iso-str-nice-str? s)

Inputs: [s :- s/Str] Returns: s/Bool

Returns true if string matches a 'nice' ISO 8601 pattern like '1999-12-31 11:22:33Z'

joda-instant? clj

(joda-instant? it)

Returns true iff arg is an instance of org.joda.time.ReadableInstant

LocalDate->tagval clj

(LocalDate->tagval ld)

Inputs: [ld :- LocalDate] Returns: {:LocalDate s/Str}

Converts a java.time.LocalDate object to a tagval

LocalDate-interval->days clj

(LocalDate-interval->days interval)

Inputs: [interval :- Interval] Returns: s/Int

Returns the duration in days from the start to the end of a LocalDate Interval

LocalDate-str? clj

(LocalDate-str? s)

Inputs: [s :- s/Str] Returns: s/Bool

Returns true if string matches a LocalDate pattern like '1999-12-31'

LocalDate? clj

(LocalDate? arg)

Inputs: [arg] Returns: s/Bool

Returns true iff arg is of type LocalDate

localdates->day-idxs clj

(localdates->day-idxs ld-vals)

Inputs: [ld-vals :- [LocalDate]] Returns: [s/Int]

Converts a sequence of LocalDate objects into an integer series like [0 1 2 ...], relative to the first value. Assumes LocalDate's are in ascending order.

LocalDateTime-str? clj

(LocalDateTime-str? s)

Inputs: [s :- s/Str] Returns: s/Bool

Returns true if string matches a LocalDateTime pattern like '1999-12-31T11:22:33'

millis->Instant clj

(millis->Instant millis)

Wrapper for java.time.Instant/ofEpochMilli

now->Date clj

(now->Date)

Returns the current time as a java.util.Date

now->Instant clj

(now->Instant)

Returns the current time as a java.lang.Instant

now->ZonedDateTime clj

(now->ZonedDateTime)

Returns the current time as a java.lang.ZonedDateTime (UTC)

parse-iso-str->Instant clj

(parse-iso-str->Instant iso-datetime-str)

Inputs: [iso-datetime-str :- s/Str] Returns: Instant

Convert an ISO 8601 string to epoch milliseconds. Will collapse excess whitespace.

parse-iso-str->millis clj

(parse-iso-str->millis iso-datetime-str)

Inputs: [iso-datetime-str :- s/Str] Returns: s/Int

Convert an ISO 8601 string to epoch milliseconds. Will collapse excess whitespace.

parse-iso-str->sql-timestamp clj

(parse-iso-str->sql-timestamp iso-datetime-str)

Inputs: [iso-datetime-str :- s/Str]

Convert an ISO 8601 string to a java.sql.Timestamp

parse-iso-str-nice->Instant clj

(parse-iso-str-nice->Instant iso-str)

Inputs: [iso-str :- s/Str] Returns: Instant

Parse a near-iso string like '2019-09-19 18:09:35Z' (it is missing the 'T' between the date & time fields) into an Instant. Will collapse excess whitespace.

parse-sql-timestamp-str->Instant-utc clj

(parse-sql-timestamp-str->Instant-utc sql-timestamp-str)

Inputs: [sql-timestamp-str :- s/Str] Returns: Instant

Parse a near-Timestamp string like ' 2019-09-19 18:09:35 ' (sloppy spacing) into an Instant. Assumes UTC timezone. Will collapse excess whitespace.

Period? clj

(Period? it)

Returns true iff arg is an instance of Period.

previous-or-same clj

(previous-or-same temporal tgt-dow)

Inputs: [temporal :- Temporal tgt-dow :- DayOfWeek] Returns: Temporal

Given a temporal value and a target such as DayOfWeek/SUNDAY, makes the minimal change to previous or same day of week. Example:

  (previous-or-same t DayOfWeek/SUNDAY)

pseudo-Temporal clj

same-instant? clj

(same-instant? & temporals)

Inputs: [& temporals :- [pseudo-Temporal]] Returns: s/Bool

Returns true iff two Instant/ZonedDateTime objects (or similar) represent the same instant of time, regardless of time zone. A thin wrapper over ZonedDateTime/isEqual

slice clj

(slice start-inst stop-inst step-dur)

Inputs: [start-inst :- Temporal stop-inst :- Temporal step-dur :- TemporalAmount] Returns: [Temporal]

Returns a vector of instants in the half-open interval [start stop) (both instants) with increment <step> (a period). Not lazy. Example:

 (range (zoned-date-time 2018 9 1)
        (zoned-date-time 2018 9 5)
        (Duration/ofDays 1)))  => <vector of 4 ZonedDateTime's from 2018-9-1 thru 2018-9-4>

str->Instant clj

(str->Instant s)

Inputs: [s :- s/Str] Returns: Instant

Parse a string into a java.time.Instant. Valid formats include:

1999-12-31                          ; LocalDate (assumes utc & start-of-day (00:00:00)
1999-12-31 11:22:33                 ; sql timestamp (assumes utc)
1999-12-31T11:22:33                 ; LocalDateTime (assumes utc)
1999-12-31T11:22:33.123             ; LocalDateTime (assumes utc)
1999-12-31T11:22:33z                ; Instant (ISO 8601)
1999-12-31 11:22:33Z                ; ISO 8601 'nice' format
1999-12-31T11:22:33.123z            ; Instant
1999-12-31T11:22:33+00:00           ; ZonedDateTime
1999-12-31T11:22:33.123+00:00[UTC]  ; ZonedDateTime

tagval->LocalDate clj

(tagval->LocalDate ldtv)

Inputs: [ldtv :- {:LocalDate s/Str}] Returns: LocalDate

Parses a tagval into a java.time.LocalDate

Temporal? clj

(Temporal? it)

Returns true iff arg is an instance of java.time.temporal.Temporal

Timestamp-str? clj

(Timestamp-str? s)

Inputs: [s :- s/Str] Returns: s/Bool

Returns true if string matches a SQL Timestamp pattern like '1999-12-31 11:22:33'

truncated-to clj

(truncated-to temporal chrono-unit)

Inputs: [temporal :- Temporal chrono-unit :- ChronoUnit]

Returns a Temporal truncated to corresponding ChronoUnit. Example:

  (truncated-to t ChronoUnit/HOURS)

tuid-str clj

(tuid-str)

Inputs: [] Returns: s/Str

Returns a 'Time Unique ID' (TUID), a human-readable UUID-cousin (44-char string) based on the current java.time.Instant. From MSB->LSB, it is composed of a 38-bit epoch second field (valid years: 1970-9999), a 30-bit (9-digit) nanosecond field, and a 64-bit random field.

  128 bits total:  <34-bit-unix-sec> + <30 bit nanos> + <64 bits rand>
  Format:  YYYY-MMDD-HHMMSS-nanosec*9-rndhex*8-rndhex*8  ; string format
  Sample:  2021-0714-191716-123456789-da39a3ee-5e6b4b0d  ; sample value

For 2 TUIDs constructed at random on the same day, there are approx 110 bits of randomness: seconds ~ 16 bits, nanosec ~ 30 bits, rndhex = 64 bits.

For 2 TUIDS constructed at random in the same second, there are still ~94 bits of randomness.

tuid-str? clj

(tuid-str? s)

Inputs: [s :- s/Str] Returns: s/Bool

Returns true if a string is a valid TUID regex pattern

walk-LocalDate->tagval clj

(walk-LocalDate->tagval data)

with-zoneid clj macro

(with-zoneid zone-id & forms)

year-quarter? clj

(year-quarter? arg)

Inputs: [arg] Returns: s/Bool

Returns true iff arg is indicates a (financial) quarter in the year.

year-quarters clj

zoned-date-time clj

(zoned-date-time)

(zoned-date-time year)

(zoned-date-time year month)

(zoned-date-time year month day)

(zoned-date-time year month day hour)

(zoned-date-time year month day hour minute)

(zoned-date-time year month day hour minute second)

(zoned-date-time year month day hour minute second nanos)

(zoned-date-time year month day hour minute second nanos zone-id)

Returns a java.time.ZonedDateTime with the specified parameters and truncated values (day/month=1, hour/minute/sec=0) for all other date/time components. Assumes time zone is UTC unless the maximum-arity constructor is used. Usage:

; Assumes UTC time zone (zoned-date-time) => current time (zoned-date-time year) (zoned-date-time year month) (zoned-date-time year month day) (zoned-date-time year month day hour) (zoned-date-time year month day hour minute) (zoned-date-time year month day hour minute second) (zoned-date-time year month day hour minute second nanos)

; Explicit time zone (zoned-date-time year month day hour minute second nanos zone-id)

; Explicit time zone alternate shortcut arities. (with-zoneid zoneid-us-eastern (zoned-date-time year month day ...)) ; any arity w/o zone-id

ZonedDateTime-str? clj

(ZonedDateTime-str? s)

Inputs: [s :- s/Str] Returns: s/Bool

Returns true if string matches a Instant pattern like '1999-12-31T11:22:33-08:00Z'

ZonedDateTime? clj

(ZonedDateTime? it)

Returns true iff arg is an instance of java.time.ZonedDateTime

zoneid-us-alaska clj

zoneid-us-aleutian clj

zoneid-us-central clj

zoneid-us-eastern clj

zoneid-us-hawaii clj

zoneid-us-mountain clj

zoneid-us-pacific clj

zoneid-utc clj