d-core.libs.time — org.clojars.cinguilherme/d-core-std 0.3.1

*clock* clj

Dynamic Clock used by 0-arity now and since. Defaults to UTC system clock (A3c, D10).

advance-clock! clj

(advance-clock! dur)

(advance-clock! clock dur)

(advance-clock! clock amount unit)

Advances a manual-clock (or dynamic *clock*) by dur (Duration, map, millis number, or literal like "5m"). Returns the new Instant.

after? clj

(after? a b)

Returns true if instant a is after instant b.

before? clj

(before? a b)

Returns true if instant a is before instant b.

between? clj

(between? instant start end)

Returns true if instant is within [start, end] inclusive.

bucket clj

(bucket inst width)

Floors an instant to an arbitrary-width boundary, measured from the epoch.

Epoch arithmetic rather than ChronoUnit/truncatedTo, which cannot express widths like 5 or 7 minutes:

(bucket inst (duration 5 :minutes))   ;; => Instant floored to a 5-minute boundary

coerce-clock clj

(coerce-clock clock-or-opts)

Coerces a Clock instance or clock options map into a java.time.Clock.

compare-instants clj

(compare-instants a b)

Compares two instants (or maps/epoch values). Returns -1, 0, or 1.

ControllableClock clj protocol

advance-clock* clj

(advance-clock* this dur)

Advances a controllable clock by duration and returns the new Instant.

set-clock* clj

(set-clock* this inst)

Sets a controllable clock to the given Instant and returns it.

dur clj macro

(dur value)

Creates a java.time.Duration from a literal or expression. When given a string or number literal at compile time, validates it immediately and expands to (java.time.Duration/ofMillis <ms>).

duration clj

(duration value)

(duration amount unit)

Creates a Duration. Accepts a map like {:seconds 1 :millis 250}, a Duration instance, a human duration string like "15m", a number (milliseconds), or an amount + unit.

duration->map clj

(duration->map d)

Converts a Duration to a map with a :millis key.

fixed-clock clj

(fixed-clock instant)

(fixed-clock instant zone)

Creates a fixed Clock at instant (accepts Instant, ISO-8601 string, Date, or epoch-ms) in zone (defaults to UTC).

format-duration clj

(format-duration d)

Formats a Duration as a compact literal, the inverse of parse-duration.

(format-duration (Duration/ofMinutes 90))  ;; => "1h30m"
(format-duration (Duration/ofMillis 500))  ;; => "500ms"

Units are emitted largest-first, skipping zero components; a whole zero duration is "0s".

format-instant clj

(format-instant inst)

Formats an instant as ISO-8601 UTC, preserving sub-second precision.

instant clj

(instant value)

Coerces value (Instant, ISO-8601 string, epoch-ms long, Date, or instant map) into a java.time.Instant.

instant->map clj deprecated

(instant->map inst)

(instant->map inst zone)

Deprecated: use d-core.temporal/->wire instead. Converts an Instant into a time map.

The map uses {:epoch-ms <long>} and optionally a :zone string.

instant-map? clj deprecated

(instant-map? value)

Deprecated: use d-core.temporal and java.time.Instant instead. Returns true if the value looks like an instant map.

Supported shapes:

• {:epoch-ms <long>}
• {:epoch-second <long> :nano <int>}

instant= clj

(instant= a b)

Returns true if both instants represent the same moment.

instant? clj

(instant? value)

Returns true if the value is a java.time.Instant.

manual-clock clj

(manual-clock)

(manual-clock instant)

(manual-clock instant zone)

Creates a mutable java.time.Clock (implementing ControllableClock) for deterministic testing. Defaults to the current UTC instant (or epoch 0 if passed nil explicitly, or the given instant).

map->instant clj deprecated

(map->instant m)

Deprecated: use d-core.temporal/->instant instead. Converts a time map into an Instant.

minus clj

(minus value dur)

(minus value unit amount)

Subtracts a duration from a Clock, Instant, or time map.

nano-span->ms clj

(nano-span->ms nanos)

Converts a nanosecond span (e.g. from System/nanoTime) to milliseconds.

nano-span->seconds clj

(nano-span->seconds nanos)

Converts a nanosecond span (e.g. from System/nanoTime) to seconds.

new-clock clj

(new-clock)

(new-clock {:keys [type zone instant clock offset tick] :or {type :system}})

Creates a java.time.Clock. Defaults to UTC.

Options:

• {:type :system :zone "UTC"}
• {:type :fixed :instant <instant|string|map|epoch-ms> :zone "UTC"}
• {:type :manual :instant <instant|string|map|epoch-ms> :zone "UTC"}
• {:type :offset :clock <clock|opts> :offset <duration|map>}
• {:type :tick :clock <clock|opts> :tick <duration|map>}

now clj

(now)

(now clock)

Returns the current Instant for the provided Clock (or dynamic *clock*).

now-map clj deprecated

(now-map)

(now-map clock)

Deprecated: use now and d-core.temporal instead. Returns a time map for now, optionally including the clock zone.

now-ms clj

(now-ms)

(now-ms clock)

Returns the current epoch milliseconds for the provided Clock (or dynamic *clock*).

parse-duration clj

(parse-duration value)

Parses a human duration literal into a Duration.

(parse-duration "15m")     ;; => #object[java.time.Duration "PT15M"]
(parse-duration "2h30m")   ;; => 2.5 hours
(parse-duration "nonsense") ;; => {:error :invalid-duration :input "nonsense" :at 0}
(parse-duration 1500)        ;; => 1500 millis, matching the platform's epoch-ms habit

Total by design: invalid input returns an error map rather than throwing, so an ingest path can skip a poison config value. Use parse-duration! when a malformed literal is a programming error.

parse-duration! clj

(parse-duration! value)

Throwing variant of parse-duration for call sites where a bad literal is a bug.

parse-instant clj

(parse-instant value)

Parses an ISO-8601 instant string. Total: returns an error map on failure.

parse-instant! clj

(parse-instant! value)

Throwing variant of parse-instant.

parse-instant-safe clj

(parse-instant-safe value)

Returns the parsed instant or nil, so it composes with some->.

plus clj

(plus value dur)

(plus value unit amount)

Adds a duration to a Clock, Instant, or time map.

When called with a Clock, uses now as the base. When called with a map, returns a map.

set-clock! clj

(set-clock! instant)

(set-clock! clock instant)

Sets a manual-clock (or dynamic *clock*) to instant. Returns the new Instant.

since clj

(since instant)

(since clock instant)

Returns a Duration between an instant (or map) and now.

truncate clj

(truncate inst unit)

(truncate inst unit opts)

Floors an instant to the start of the containing unit.

(truncate inst :minute)                 ;; => Instant floored to the minute (UTC)
(truncate inst :day {:zone "America/Sao_Paulo"})  ;; => start of that local day, as a UTC Instant

Returns an Instant (UTC) in every case: the zone parameter only decides where the local day boundary falls. Defaults to UTC, never the JVM default zone.

window clj

(window inst unit)

(window inst unit opts)

Returns the half-open [start, end) window containing an instant.

(window inst :hour)                      ;; => {:start .. :end ..}
(window inst :day {:zone "America/New_York"})  ;; a DST day is 23 or 25 hours

Both bounds are UTC Instants. A zone only positions the boundary, so a day window across a DST transition is correctly 23 or 25 hours long rather than a naive 24.

with-clock clj macro

(with-clock clock-or-opts & body)

Evaluates body with *clock* bound to clock-or-opts (a Clock, options map, or fixed instant). Explicit Clock arguments passed to (now clock) still take precedence (A3c).