taoensso.encore — com.taoensso/encore 3.98.0-RC7

Extended core library for Clojure/Script that emphasizes:

• Cross-platform API
• Flexibility
• Performance
• Backwards compatibility

This lib's mostly for my own use and for advanced users that feel comfortable reading this source. Not providing much beginner-oriented documentation for this, sorry.

Common naming conventions used across my libs: foo - Dynamic var foo! - Fn with side-effects, or that should otherwise be used cautiously foo? - Truthy val or fn that returns truthy val foo!? - Fn that has side-effects (or requires caution) and that return a truthy val. Note: !?, not ?! foo$ - Fn that's notably expensive to compute (e.g. hits db) foo_ - Derefable val (e.g. atom, volatile, delay, etc.) foo__ - Derefable in a derefable (e.g. delay in an atom), etc. _ - Unnamed val _foo - Named but unused val ?foo - Optional val (emphasize that val may be nil) foo* - A variation of foo (e.g. foo* macro vs foo fn) foo' - '' -foo - Public implementation detail or intermediate (e.g. uncoerced) val

foo - Val "to foo" (e.g. >sender, >host), or fn to put/coerce/transform <foo - Val "from foo" (e.g. <sender, <host), or fn to take/coerce/transform ->foo - Fn to put/coerce/transform

Type affixes may be used for clarity: <prefix>-<name> - m-users, v-users, n-users, etc. (also nusers when unambiguous) <name>-<postfix> - users-map, users-vec, user-count, etc.

Regarding name heirarchy: When there's a significant num of syms with a meaningful hierarchy, prefer names with descending hierarchy to emphasize structure and related groups/functionality, e.g.: user-add, user-remove, user-mod vs add-user, remove-user, mod-user, etc.

Commit message tags (in priority order): [wip] - Work-in-progress (still under development)

[mod] - Modify behaviour (=> breaking), [mod!], [mod!!], etc. for attention [fix] - Fix broken behaviour (=> usu. non-breaking) [new] - Add new behaviour (=> non-breaking)

[doc] - Documentation changes besides those better labelled as [mod], [fix], or [new] [nop] - Other non-breaking changes (to implementation details, non-code changes, etc.)

[x] [y] - Single commit with multiple tags (in priority order), try avoid

Example commit messages: v1.0.0 (2022-01-27) ; Tagged release [new] [#122] Add new feature x (@contributor)

Version numbers: Ver tables: X.Y.Z (without backticks) Min ver: vX.Y.Z+ Elsewhere: vX.Y.Z

<* clj/s macro

(<* x y z)

<=* clj/s macro

(<=* x y z)

>* clj/s macro

(>* x y z)

>=* clj/s macro

(>=* x y z)

abbreviate-ns clj/s

(abbreviate-ns x)

(abbreviate-ns n-full x)

Give any nameable type (string, keyword, symbol), returns the same type with at most n-full (default 1) unabbreviated namespace parts.

Example: (abbreviate-ns 0 :foo.bar/baz) => :f.b/baz (abbreviate-ns 1 'foo.bar/baz) => 'f.bar/baz (abbreviate-ns 2 "foo.bar/baz") => "foo.bar/baz"

abs clj/s

(abs n)

after-timeout clj/s macro

(after-timeout msecs & body)

Alpha, subject to change. Returns a TimeoutFuture that will execute body after timeout. Body must be non-blocking or cheap.

ajax-call cljs

(ajax-call url
           {:keys [method params headers timeout-ms resp-type with-credentials?
                   xhr-pool xhr-cb-fn xhr-timeout-ms]
            :as opts
            :or {method :get
                 timeout-ms 10000
                 resp-type :auto
                 xhr-pool default-xhr-pool_
                 xhr-timeout-ms 2500}}
           callback-fn)

Queues a lightweight Ajax call with Google Closure's goog.net.XhrIo and returns nil, or the resulting goog.net.XhrIo instance if one was immediately available from the XHR pool:

(ajax-call "http://localhost:8080/my-post-route" ; Endpoint URL

{:method     :post ; ∈ #{:get :post :put}
 :resp-type  :text ; ∈ #{:auto :edn :json :xml :text}

 :params     {:username "Rich Hickey" :type "Awesome"} ; Request params
 :headers    {"Content-Type" "text/plain"} ; Request headers

 :timeout-ms 7000
 :with-credentials? false ; Enable if using CORS (requires xhr v2+)

 :xhr-pool       my-xhr-pool ; Optional `goog.net.XhrIoPool` instance or delay
 :xhr-cb-fn      (fn [xhr])  ; Optional fn to call with `XhrIo` from pool when available
 :xhr-timeout-ms 2500        ; Optional max msecs to wait on pool for `XhrIo`
}

(fn ajax-callback-fn [resp-map]
  (let [{:keys [success? ?status ?error ?content ?content-type]} resp-map]
    ;; ?status ; ∈ #{nil 200 404 ...}, non-nil iff server responded
    ;; ?error  ; ∈ #{nil <http-error-status-code> <exception> :timeout
                     :abort :http-error :exception :xhr-pool-depleted}
    (js/alert (str "Ajax response: " resp-map)))))

approx== clj/s

(approx== x y)

(approx== signf x y)

as-?bool clj/s

(as-?bool x)

as-?dt clj

(as-?dt x)

Returns given ?arg as java.util.Date, or nil.

as-?email clj/s

(as-?email ?s)

(as-?email max-len ?s)

as-?float clj/s

(as-?float x)

as-?inst clj/s

(as-?inst x)

Returns given ?arg as platform instant (java.time.Instant or js/Date), or nil.

as-?int clj/s

(as-?int x)

as-?kw clj/s

(as-?kw x)

as-?name clj/s

(as-?name x)

as-?nat-float clj/s

(as-?nat-float x)

as-?nat-int clj/s

(as-?nat-int x)

as-?nblank clj/s

(as-?nblank x)

as-?nblank-trim clj/s

(as-?nblank-trim x)

as-?nemail clj/s

(as-?nemail ?s)

(as-?nemail max-len ?s)

as-?nempty-str clj/s

(as-?nempty-str x)

as-?nzero clj/s

(as-?nzero x)

as-?pnum clj/s

(as-?pnum x)

as-?pos-float clj/s

(as-?pos-float x)

as-?pos-int clj/s

(as-?pos-int x)

as-?qname clj/s

(as-?qname x)

as-?rnum clj/s

(as-?rnum x)

as-?udt clj/s

(as-?udt x)

Returns given ?arg as (pos/neg) milliseconds since Unix epoch, or nil.

as-bool clj/s

(as-bool x)

as-dt clj

(as-dt x)

as-email clj/s

(as-email x)

(as-email n x)

as-float clj/s

(as-float x)

as-inst clj/s

(as-inst x)

as-int clj/s

(as-int x)

as-kw clj/s

(as-kw x)

as-name clj/s

(as-name x)

as-nat-float clj/s

(as-nat-float x)

as-nat-int clj/s

(as-nat-int x)

as-nblank clj/s

(as-nblank x)

as-nblank-trim clj/s

(as-nblank-trim x)

as-nemail clj/s

(as-nemail x)

(as-nemail n x)

as-nempty-str clj/s

(as-nempty-str x)

as-nzero clj/s

(as-nzero x)

as-pnum clj/s

(as-pnum x)

as-pnum! clj/s

(as-pnum! x)

as-pnum-complement clj/s

(as-pnum-complement x)

as-pos-float clj/s

(as-pos-float x)

as-pos-int clj/s

(as-pos-int x)

as-qname clj/s

(as-qname x)

as-rnum clj/s

(as-rnum x)

as-rnum! clj/s

(as-rnum! x)

as-udt clj/s

(as-udt x)

assert-min-encore-version clj/s

(assert-min-encore-version min-version)

Version check for dependency conflicts, etc.

assoc-nx clj/s

(assoc-nx m m-kvs)

(assoc-nx m k v)

(assoc-nx m k v & kvs)

Assocs each kv to given ?map iff its key doesn't already exist.

assoc-some clj/s

(assoc-some m m-kvs)

(assoc-some m k v)

(assoc-some m k v & kvs)

Assocs each kv to given ?map iff its value is not nil.

assoc-when clj/s

(assoc-when m m-kvs)

(assoc-when m k v)

(assoc-when m k v & kvs)

Assocs each kv to given ?map iff its val is truthy.

atom? clj/s

(atom? x)

ba->hex-str clj

(ba->hex-str ba)

Returns byte[] for given hex string.

ba-concat clj

(ba-concat ba1 ba2)

ba-hash clj

(ba-hash x)

Returns hash int of given byte[].

ba-split clj

(ba-split ba idx)

ba= clj

(ba= x y)

Returns true iff given two byte[]s with the same content.

bench clj/s macro

(bench nlaps opts & body)

bench* clj

(bench* nlaps
        {:keys [nlaps-warmup nthreads as-ns?] :or {nlaps-warmup 0 nthreads 1}}
        f)

Repeatedly executes fn and returns time taken to complete execution.

binding clj/s macro

(binding bindings & body)

For Clj: faster version of core/binding. For Cljs: identical to core/binding.

boolean? clj/s

(boolean? x)

bytes-class clj

bytes? clj

(bytes? x)

Returns true iff given byte[] argument.

cache clj/s

(cache f)

(cache {:keys [size ttl-ms gc-every] :as opts} f)

Returns a cached version of given referentially transparent function f.

Like core/memoize but:

• Often faster, depending on options.

• Prevents race conditions on writes.

• Supports cache invalidation by prepending args with:

  • :cache/del ; Delete cached item for subsequent args, returns nil.
  • :cache/fresh ; Renew cached item for subsequent args, returns new val.

• Supports options:

  • ttl-ms ; Expire cached items after <this> many msecs.

  • size ; Restrict cache size to <this> many items at the next garbage ; collection (GC).

  • gc-every ; Run garbage collection (GC) approximately once every ; <this> many calls to cached fn. If unspecified, GC rate ; will be determined automatically based on size.

See also defn-cached, fmemoize, memoize-last.

call-after-timeout clj/s

(call-after-timeout msecs f)

(call-after-timeout impl_ msecs f)

Alpha, subject to change. Returns a TimeoutFuture that will execute f after given msecs.

Does NOT do any automatic binding conveyance.

Performance depends on the provided timer implementation (impl_). The default implementation offers O(logn) add, O(1) cancel, O(1) tick.

See ITimeoutImpl for extending to arbitrary timer implementations.

can-meta? clj/s

(can-meta? x)

case-eval clj/s macro

(case-eval expr & clauses)

Like case but test expressions are evaluated for their compile-time value.

case-insensitive-str= clj/s

(case-insensitive-str= s1 s2)

Returns true iff given strings are equal, ignoring case.

catching clj/s macro

(catching try-expr)

(catching try-expr error-sym catch-expr)

(catching try-expr error-sym catch-expr finally-expr)

(catching try-expr error-type error-sym catch-expr finally-expr)

Terse, cross-platform try/catch/finally. See also try* for more flexibility.

catching-rf clj/s

(catching-rf rf)

(catching-rf error-fn rf)

Returns wrapper around given reducing function rf so that if rf throws, (error-fn <thrown-error> <contextual-data>) will be called.

The default error-fn will rethrow the original error, wrapped in extra contextual information to aid debugging.

See also catching-xform.

catching-xform clj/s

(catching-xform xform)

(catching-xform error-fn xform)

Like catching-rf, but applies to a transducer (xform).

Makes debugging transductions much easier by greatly improving the information provided in any errors thrown by xform or the reducing fn:

(transduce (catching-xform (comp (filter even?) (map inc))) ; Modified xform <reducing-fn> <...>)

chan? clj/s

(chan? x)

Returns true iff given a clojure.core.async channel.

chance clj/s

(chance prob)

Returns true with given probability ∈ ℝ[0,1].

check-all clj/s macro

(check-all test)

(check-all test & more)

Returns all logical false/throwing expressions (ids/forms), or nil.

check-some clj/s macro

(check-some test)

(check-some test & more)

Returns first logical false/throwing expression (id/form), or nil.

clamp clj/s

(clamp nmin nmax n)

clamp* clj/s macro

(clamp* nmin nmax n)

clamp-float clj/s

(clamp-float nmin nmax n)

clamp-int clj/s

(clamp-int nmin nmax n)

compile-if clj/s macro

(compile-if test then)

(compile-if test then else)

Evaluates test. If it returns logical true (and doesn't throw), expands to then, otherwise expands to else.

compile-when clj/s macro

(compile-when test & body)

compiling-cljs? clj

(compiling-cljs?)

Return truthy iff currently generating Cljs code. See also if-cljs, if-clj.

cond clj/s macro

(cond & clauses)

Supersets core/cond functionality. Like core/cond but supports implicit final else clause, and special clause keywords for advanced behaviour:

(cond :let [x "x"] ; Establish let binding/s for remaining forms :binding [x "x"] ; Establish dynamic binding/s for remaining forms :do (println (str "x value: " x)) ; Eval expr for side-effects

:if-let [y "y" z nil] "y and z were both truthy"

:if-some [y "y" z nil] "y and z were both non-nil")

:let support inspired by https://github.com/Engelberg/better-cond. Simple, flexible way to eliminate deeply-nested control flow code.

cond! clj/s macro

(cond! & clauses)

Like cond but throws on non-match like case and condp.

conj-some clj/s

(conj-some)

(conj-some coll)

(conj-some coll x)

(conj-some coll x & more)

Conjoins each non-nil value.

conj-when clj/s

(conj-when)

(conj-when coll)

(conj-when coll x)

(conj-when coll x & more)

Conjoins each truthy value.

const-ba= clj

(const-ba= ba1 ba2)

Constant-time ba=. Useful to prevent timing attacks, etc.

const-str= clj/s

(const-str= s1 s2)

Constant-time string equality checker. Useful to prevent timing attacks, etc.

contains-in? clj/s

(contains-in? coll ks)

(contains-in? coll ks k)

convey-reduced clj/s

(convey-reduced x)

count-words clj/s

(count-words s)

counter clj/s

(counter)

(counter init)

Returns a fast atomic Counter with init initial int value:

• (<counter> ) -> add 1, return old val
• (<counter> <n>) -> add n, return old val

Experimental 3-arity version takes an action: :add, :set, :set-get, :get-set, :get-add, :add-get

declare-remote clj/s macro

(declare-remote & syms)

Declares given ns-qualified symbols, preserving metadata. Clj only. Useful for circular dependencies.

def* clj/s macro

(def* sym & args)

Like core/def but supports attrs map.

defalias clj/s macro

(defalias src)

(defalias alias src)

(defalias alias src alias-attrs)

(defalias alias src alias-attrs alias-body)

Defines a local alias for the var identified by given qualified source symbol: (defalias my-map clojure.core/map), etc.

For Clj:

• Source var's metadata will be preserved (docstring, arglists, etc.).
• Changes to source var's value will also be applied to alias.

See also defaliases.

defaliases clj/s macro

(defaliases {:keys [alias src attrs body]} ...)

Bulk version of defalias. Takes source symbols or {:keys [alias src attrs body]} maps: (defaliases {:alias my-map, :src map, :attrs {:doc "My map alias"}} {:alias my-vec, :src vec, :attrs {:doc "My vec alias"}})

default-timeout-impl_ clj/s

Simple one-timeout timeout implementation provided by platform timer. O(logn) add, O(1) cancel, O(1) tick. Fns must be non-blocking or cheap. Similar efficiency to core.async timers (binary heap vs DelayQueue).

defn-cached clj/s macro

(defn-cached sym cache-opts & body)

Defines a cached function. Like (def <sym> (cache <cache-opts> <body...>)), but preserves :arglists (arity) metadata as with defn:

(defn-cached ^:private my-fn {:ttl-ms 500} "Does something interesting, caches resultes for 500 msecs" [n] (rand-int n))

defonce clj/s macro

(defonce sym & args)

Like core/defonce but supports docstring and attrs map.

defstub clj/s macro

(defstub sym)

Experimental!! Declares a stub var that can be initialized from any namespace with unstub-<stub-name>.

Decouples a var's declaration (location) and its initialization (value). Useful for defining vars in a shared ns from elsewhere (e.g. a private or cyclic ns).

deprecated clj/s macro

(deprecated & body)

Elides body when taoensso.elide-deprecated JVM property or TAOENSSO_ELIDE_DEPRECATED environment variable is ∈ #{"true" "TRUE"}.

derefable? clj/s

(derefable? x)

dissoc-in clj/s

(dissoc-in m ks)

(dissoc-in m ks dissoc-k)

(dissoc-in m ks dissoc-k & more)

distinct-elements? clj/s

(distinct-elements? x)

doto-cond clj/s macro

(doto-cond [sym x] & clauses)

Cross between doto, cond-> and as->.

editable? clj/s

(editable? x)

encore-version clj/s

ensure-set clj/s

(ensure-set x)

ensure-vec clj/s

(ensure-vec x)

error? clj/s

(error? x)

Returns true iff given platform error (Throwable or js/Error).

ex-cause clj/s

(ex-cause x)

Same as core/ex-cause (added in Clojure v1.10).

ex-data clj/s

(ex-data x)

Same as core/ex-data (added in Clojure v1.4).

ex-map clj/s

(ex-map x)

(ex-map chrono-causes? x)

Experimental, subject to change without notice! Returns ?{:keys [type msg data via]} for given platform error.

If chrono-causes? is false (default), cause chain is depth-first like Java. If chrono-causes? is true, cause chain is inverted (chronological).

(ex-map (Exception. "Ex2" (Exception. "Ex1"))) => {:msg "Ex2", :via {:msg "Ex1", ...}, ...} (ex-map :chrono (Exception. "Ex2" (Exception. "Ex1"))) => {:msg "Ex1", :via {:msg "Ex2", ...}, ...}

ex-message clj/s

(ex-message x)

Same as core/ex-message (added in Clojure v1.10).

exception? clj

(exception? x)

exp-backoff clj/s

(exp-backoff n-attempt)

(exp-backoff n-attempt {:keys [min max factor] :or {factor 1000}})

Returns binary exponential backoff value for n<=36.

explode-keyword clj/s

(explode-keyword k)

fast-merge clj/s

(fast-merge maps)

(fast-merge m1 m2)

(fast-merge m1 m2 m3)

(fast-merge m1 m2 m3 m4)

Like core/merge but faster. Doesn't support zero arity, single arity case takes a collection of maps.

file-resources-modified? clj

Returns true iff any files backing given named resources have changed since last call.

filter-keys clj/s

(filter-keys key-pred m)

Returns given ?map, retaining only keys for which (key-pred <key>) is truthy.

filter-vals clj/s

(filter-vals val-pred m)

Returns given ?map, retaining only keys for which (val-pred <val>) is truthy.

finite-num? clj/s

(finite-num? x)

Returns true iff given a number (of standard type) that is: finite (excl. NaN and infinities).

float? clj/s

(float? x)

Returns true iff given a number (of standard type) that is: a fixed-precision floating-point (incl. NaN and infinities).

fmemoize clj/s

(fmemoize f)

For Clj: fastest possible memoize. Non-racey, 0-7 arity only. For Cljs: same as core/memoize.

force-ref clj/s

(force-ref x)

Like force for refs.

force-var clj/s

(force-var x)

Like force for vars.

format clj/s

(format fmt & args)

Like core/format but:

• Returns "" when fmt is nil rather than throwing an NPE.
• Formats nil as "nil" rather than "null".
• Provides ClojureScript support via goog.string.format (this has fewer formatting options than Clojure's format!).

format* clj/s

(format* fmt args)

(format* xform fmt args)

format-query-string clj/s

(format-query-string m)

future* clj/s macro

(future* form)

(future* executor-service form)

Experimental, subject to change without notice! Like future but supports use of given custom java.util.concurrent.ExecutorService.

Will default to using JVM 21+ virtual threads when possible, otherwise an unbounded fixed daemon thread pool.

See also future-call, virtual-executor, pool-executor.

future-call* clj

(future-call* f)

(future-call* executor-service f)

Experimental, subject to change without notice! Like future-call but supports use of given custom java.util.concurrent.ExecutorService.

Will default to using JVM 21+ virtual threads when possible, otherwise an unbounded fixed daemon thread pool.

See also future, virtual-executor, pool-executor.

future-pool clj

(future-pool n-threads)

Returns a simple semaphore-limited wrapper of Clojure's standard future: (fn future-pool-fn ([f] [timeout-msecs timeout-val f] [] [timeout-msecs timeout-val]))

Arities of returned function: [f] - Blocks to acquire a future, then executes (f) on that future. [ ] - Blocks to acquire ALL futures, then immediately releases them. Useful for blocking till all outstanding work completes.

[timeout-msecs timeout-val f] - Variant of [f] with timeout
[timeout-msecs timeout-val  ] - Variant of [ ] with timeout

See also future* for fully custom pools, etc.

get* clj/s macro

(get* m k)

(get* m k not-found)

(get* m k1 k2 not-found)

(get* m k1 k2 k3 not-found)

Macro version of get that:

1. Avoids unnecessary evaluation of not-found. Useful when not-found is expensive or contains side-effects.

2. Supports multiple prioritized keys (k1, k2, etc.). Returns val for first key that exists in map. Useful for key aliases or fallbacks.

Equivalent to:

(cond (contains? m k1) (get m k1) (contains? m k2) (get m k2) ... :else not-found)

get-dynamic-assertion-data clj deprecated

(get-dynamic-assertion-data)

Prefer get-data

get-env clj/s macro

(get-env {:keys [as default return spec] :or {as :str return :value}})

(get-env {:keys [as default return]} spec)

Cross-platform util for embedding flexible environmental config during macro expansion. Used by other Taoensso libraries.

Given a const kw/string id or vector of desc-priority alternative ids, parse and return the first of the following that exists:

• JVM property value for id ("prop")
• Environment variable value for id ("env")
• Classpath resource content for id ("res")

Ids may include optional segment in <> tag (e.g. <.edn>). Ids may include <.?platform.?> tag for auto replacement, useful for supporting platform-specific config.

Search order: desc by combined [alt-index platform(y/n) optional(y/n)].

(get-env {:as :edn} [:my-app/alt1<.platform><.edn> :my-app/alt2]) will parse and return the first of the following that exists:

1. Alt1 +platform +optional (content type) 1a. my-app.alt1.clj.edn JVM property value 1b. MY_APP_ALT1_CLJ_EDN environment variable value 1c. my-app.alt1.clj.edn classpath resource content

2. Alt1 +platform -optional (content type) 2a. my-app.alt1.clj JVM property value 2b. MY_APP_ALT1_CLJ environment variable value 2c. my-app.alt1.clj classpath resource content

3. Alt1 -platform +optional (content type) 3a. my-app.alt1.edn JVM property value 3b. MY_APP_ALT1_EDN environment variable value 3c. my-app.alt1.edn classpath resource content

4. Alt1 -platform -optional (content type) 4a. my-app.alt1 JVM property value 4b. MY_APP_ALT1 environment variable value 4c. my-app.alt1 classpath resource content

5. Alt2 5a. my-app.alt2 JVM property value 5b. MY_APP_ALT2 environment variable value 5c. my-app.alt2 classpath resource content

Options: :as - Parse found value as given type ∈ #{:str :bool :edn} (default :str). :default - Fallback to return if no value found during search (default nil). :return - Return type ∈ #{:value :map :debug} (default :value). TIP: Use :debug to inspect/verify search behaviour!

Result must be something that can be safely embedded in code during macro-expansion. Symbols in edn will be evaluated during expansion.

get-file-resource-?last-modified clj

(get-file-resource-?last-modified rname)

Returns last-modified time for file backing given named resource, or nil if file doesn't exist.

get-hostname clj

(get-hostname)

(get-hostname fallback)

(get-hostname timeout-msecs timeout-val)

(get-hostname cache-msecs timeout-msecs timeout-val)

Returns local hostname string, or fallback (default nil). Can be slow, prefer 3-arity caching variant when possible.

get-pom-version clj

(get-pom-version dep-sym)

Returns POM version string for given Maven dependency, or nil.

get-source clj

(get-source macro-form macro-env)

Returns {:keys [ns line column file]} source location given a macro's compile-time &form and &env vals. See also keep-callsite.

get-substr-by-idx clj/s

(get-substr-by-idx s start-idx)

(get-substr-by-idx s start-idx end-idx)

Returns ?substring from given string.

Like subs but:

• Provides consistent clj/s behaviour.
• Never throws (snaps to valid indexes).
• Indexes may be -ive (=> indexed from end of string).

Returns nil when requested substring would be empty.

get-substr-by-len clj/s

(get-substr-by-len s start-idx)

(get-substr-by-len s start-idx sub-len)

Returns ?substring from given string. Like get-substr-by-idx, but takes a substring-length 3rd argument.

get-subvec clj/s

(get-subvec v start)

(get-subvec v start end)

Like subvec but never throws (snaps to valid start and end indexes).

get-subvector clj/s

(get-subvector v start)

(get-subvector v start length)

Like get-subvec but:

• Takes length instead of end (index).
• -ive start => index from right of vector.

get-truss-data clj/s≠

clj

(get-truss-data)

Returns current value of dynamic assertion data.

cljs

get-win-loc cljs

(get-win-loc)

Returns current window location as {:keys [href protocol hostname host pathname search hash]}.

get1 clj/s

(get1 m k)

(get1 m k not-found)

(get1 m k1 k2 not-found)

(get1 m k1 k2 k3 not-found)

Like get but returns val for first key that exists in map. Useful for key aliases or fallbacks. See also get*.

have clj/s macro

(have x)

(have pred (:in) x)

(have pred (:in) x & more-xs)

Takes a pred and one or more vals. Tests pred against each val, trapping errors. If any pred test fails, throws a detailed assertion error. Otherwise returns input val/vals for convenient inline-use/binding.

Respects assert value so tests can be elided from production for zero runtime costs.

Provides a small, simple, flexible feature subset to alternative tools like clojure.spec, core.typed, prismatic/schema, etc.

;; Will throw a detailed error message on invariant violation: (fn my-fn [x] (str/trim (have string? x)))

You may attach arbitrary debug info to assertion violations like: (have string? x :data {:my-arbitrary-debug-info "foo"})

Re: use of Truss assertions within other macro bodies: Due to CLJ-865, call site information (e.g. line number) of outer macro will unfortunately be lost.

See keep-callsite util for a workaround.

See also have?, have!.

have! clj/s macro

(have! x)

(have! pred (:in) x)

(have! pred (:in) x & more-xs)

Like have but ignores assert value (so can never be elided). Useful for important conditions in production (e.g. security checks).

have!? clj/s macro

(have!? x)

(have!? pred (:in) x)

(have!? pred (:in) x & more-xs)

Specialized cross between have? and have!. Not used often but can be handy for semantic clarification and/or to improve multi-val performance when the return vals aren't necessary.

WARNING: Do NOT use in :pre/:post conds since those are ALWAYS subject to assert, directly contradicting the intention of the bang (!) here.

have-core-async? clj/s

Is clojure.core.async present (not necessarily loaded)?

have-telemere? clj/s

Is taoensso.telemere present (not necessarily loaded)?

have? clj/s macro

(have? x)

(have? pred (:in) x)

(have? pred (:in) x & more-xs)

Like have but returns true on successful tests. In particular, this can be handy for use with :pre/:post conditions. Compare: (fn my-fn [x] {:post [(have nil? %)]} nil) ; {:post [nil]} FAILS (fn my-fn [x] {:post [(have? nil? %)]} nil) ; {:post [true]} passes as intended

hex-str->ba clj

(hex-str->ba s)

Returns hex string for given byte[].

ident-hex-str clj

(ident-hex-str obj)

Returns hex string of given Object's identityHashCode (e.g. "0x5eeb49f2").

ident? clj/s

(ident? x)

identical-kw? clj/s macro

(identical-kw? x y)

Returns true iff two keywords are identical. Portable and maximally fast. For Clj this expands to: (identical? x y) For Cljs this expands to: (keyword-identical? x y)

if-clj clj/s macro

(if-clj then & [else])

if-cljs clj/s macro

(if-cljs then & [else])

if-let clj/s macro

(if-let bindings then)

(if-let bindings then else)

Supersets core/if-let functionality. Like core/if-let but supports multiple bindings, and unconditional bindings with :let:

(if-let [x (rand-nth [:x1 :x2 false nil ]) ; Bind truthy x, or -> else :let [y (rand-nth [:y1 :y2 false nil x ])] ; Bind any y z (rand-nth [:z1 :z2 false nil x y]) ; Bind truthy z, or -> else ] [:then-clause x y z] [:else-clause])

if-not clj/s macro

(if-not test-or-bindings then)

(if-not test-or-bindings then else)

Supersets core/if-not functionality. Same as encore/if-let with then andelse` forms swapped.

if-some clj/s macro

(if-some bindings then)

(if-some bindings then else)

Supersets core/if-some functionality. Like core/if-some but supports multiple bindings, and unconditional bindings with :let:

(if-some [x (rand-nth [:x1 :x2 false nil ]) ; Bind non-nil x, or -> else :let [y (rand-nth [:y1 :y2 false nil x ])] ; Bind any y z (rand-nth [:z1 :z2 false nil x y]) ; Bind non-nil z, or -> else ] [:then-clause x y z] [:else-clause])

indexed? clj/s

(indexed? x)

inst->udt clj/s≠

(inst->udt inst)

clj

Returns given java.time.Instant as milliseconds since Unix epoch.

cljs

Returns given js/Date as milliseconds since Unix epoch.

inst? clj/s

(inst? x)

Returns true iff given platform instant (java.time.Instant or js/Date).

instance! clj/s macro

(instance! class arg)

(instance! class arg {:keys [msg context param ...]})

(instance! class arg & {:keys [msg context param ...]})

If (instance? class arg) is true, returns arg. Otherwise throws runtime ExceptionInfo with unexpected-arg!. See unexpected-arg! for more info.

int? clj/s

(int? x)

Returns true iff given a number (of standard type) that is: a fixed-precision integer.

interleave-all clj/s

(interleave-all)

(interleave-all c1)

(interleave-all c1 c2)

(interleave-all c1 c2 & colls)

Like interleave but includes all items (i.e. stops when the longest rather than shortest coll has been consumed).

interns-overview clj

(interns-overview)

(interns-overview ns)

Returns {:keys [api public private impl test no-doc]}, with each key mapped to an alphabetical list of the relevant vars in given namespace.

"impl" vars are public vars with names that begin with "-" or "_", a naming convention commonly used to indicate vars intended to be treated as private implementation details even when public.

into! clj/s

(into! to!)

(into! to! from)

(into! to! xform from)

Like core/into but assumes to! is a transient, and doesn't call persist! when done. Useful as a performance optimization in some cases.

into-all clj/s

(into-all to from)

(into-all to from & more)

Like into but supports multiple "from"s.

into-str clj/s

(into-str & xs)

Simple Hiccup-like string templating to complement Tempura.

invert-map clj/s

(invert-map m)

Returns given ?map with keys and vals inverted, dropping non-unique vals!

is! clj/s

(is! x)

(is! pred x)

(is! pred x data)

Lightweight have! that provides less diagnostic info.

ITimeoutFuture clj/s protocol

tf-cancel! clj/s

(tf-cancel! _)

Returns true iff the timeout was successfully cancelled (i.e. was previously pending).

tf-cancelled? clj/s

(tf-cancelled? _)

Returns true iff the timeout is cancelled.

tf-done? clj/s

(tf-done? _)

Returns true iff the timeout is not pending (i.e. has a completed result or is cancelled).

tf-pending? clj/s

(tf-pending? _)

Returns true iff the timeout is pending.

tf-poll clj/s

(tf-poll _)

Returns :timeout/pending, :timeout/cancelled, or the timeout's completed result.

tf-state clj/s

(tf-state _)

Returns a map of timeout's public state.

ITimeoutImpl clj/s protocol

-schedule-timeout clj/s

(-schedule-timeout _ msecs f)

java-version clj

(java-version)

(java-version version-string)

Returns Java's major version integer (8, 17, etc.).

java-version>= clj

(java-version>= n)

Returns true iff Java's major version integer is >= given integer: (if (java-version>= 21) <then> <else>)

keep-callsite clj/s macro

(keep-callsite & body)

The long-standing CLJ-865 unfortunately means that it's currently not possible for an inner macro to access the &form metadata of an outer macro.

This means that inner macros lose callsite information like the line number of the outer macro.

This util offers a workaround for macro authors:

(defmacro inner [] (meta &form)) (defmacro outer1 [] (inner)) (defmacro outer2 [] (keep-callsite(inner)))

(inner) => {:line _, :column _} (outer1) => nil (outer2) => {:line _, :column _}

keys-by clj/s

(keys-by f coll)

Returns {(f x) x} ?map for xs in coll.

ks-nnil? clj/s

(ks-nnil? ks m)

ks<= clj/s

(ks<= ks m)

ks= clj/s

(ks= ks m)

ks>= clj/s

(ks>= ks m)

lazy-seq? clj/s

(lazy-seq? x)

log cljs

logf cljs

(logf fmt & xs)

logp cljs

(logp & xs)

map-entry clj/s

(map-entry k v)

Returns a MapEntry with given key and value.

map-keys clj/s

(map-keys key-fn m)

Returns given ?map with (key-fn <key>) keys.

map-vals clj/s

(map-vals val-fn m)

Returns given ?map with (val-fn <val>) vals.

mapply clj/s

(mapply f & args)

Like apply but calls seq-kvs on final arg.

matching-error clj/s

(matching-error err)

(matching-error kind err)

(matching-error kind pattern err)

Given a platform error and criteria, returns the error if it matches all criteria. Otherwise returns nil.

kind may be:

• A predicate function, (fn match? [x]) -> bool
• A class (e.g. ArithmeticException, AssertionError, etc.)
• :all => any platform error (Throwable or js/Error, etc.)
• :common => common platform error (Exception or js/Error)
• :ex-info => an IExceptionInfo as created by ex-info
• A set of kinds as above, at least one of which must match

pattern may be:

• A string or Regex against which ex-message must match
• A map against which ex-data must match using submap?
• A set of patterns as above, at least one of which must match

When an error with (nested) causes doesn't match, a match will be attempted against its (nested) causes.

Low-level util, see also throws, throws?.

max* clj/s macro

(max* n1 n2)

max-long clj/s

memoize clj/s

(memoize f)

(memoize ttl-ms f)

(memoize size ttl-ms f)

Alternative way to call cache, provided mostly for back compatibility. See cache docstring for details.

memoize-last clj/s

(memoize-last f)

Like core/memoize but only caches the fn's most recent call. Great for Reactjs render op caching on mobile devices, etc.

merge clj/s

(merge & maps)

Like core/merge but faster, supports :merge/dissoc rvals.

merge-keywords clj/s

(merge-keywords ks)

(merge-keywords ks omit-slash?)

merge-meta clj/s

(merge-meta x m)

merge-url-with-query-string clj/s

(merge-url-with-query-string url m)

merge-with clj/s

(merge-with f & maps)

Like core/merge-with but faster, supports :merge/dissoc rvals.

min* clj/s macro

(min* n1 n2)

min-long clj/s

ms clj/s

(ms opts)

(ms & {:as opts :keys [years months weeks days hours mins secs msecs ms]})

Returns ~number of milliseconds in period defined by given args.

ms->secs clj/s

(ms->secs ms)

msecs clj/s macro

(msecs opts)

(msecs & {:as opts :keys [years months weeks days hours mins secs msecs ms]})

Macro version of ms.

name-filter clj/s

(name-filter spec)

Given filter spec, returns a compiled (fn conform? [name]) that takes any nameable type (string, keyword, symbol).

Spec may be:

• A regex pattern. Will conform on match.

• A str/kw/sym, in which "*"s act as wildcards. Will conform on match.

• A vector or set of regex patterns or strs/kws/syms. Will conform on ANY match. If you need literal "*"s, use #"*" regex instead.

• {:allow <spec> :deny <spec>} with specs as above. Will conform iff allow spec matches AND deny spec does NOT.

Resulting conform fn is useful as allowlist and/or denylist. Example inputs: namespace strings, class names, ids, etc.

Spec examples: #{}, "", "foo.bar", "foo.bar.", #{"foo" "bar."}, {:allow #{"foo" "bar."} :deny #{"foo..bar."}}, #"(foo1|foo2).bar".

name-with-attrs clj/s

(name-with-attrs sym args)

(name-with-attrs sym args attrs-merge)

Given a symbol and args, returns [<name-with-attrs-meta> <args> <attrs>] with support for defn style ?docstring and ?attrs-map.

nameable? clj/s

(nameable? x)

named? clj/s

(named? x)

nanoid clj/s

(nanoid)

(nanoid len)

Returns a random "Nano ID" of given length, Ref. https://github.com/ai/nanoid. Uses strong randomness when possible. See also uuid-str, rand-id-fn.

nat-float? clj/s

(nat-float? x)

nat-int? clj/s

(nat-int? x)

nat-num? clj/s

(nat-num? x)

nblank-str? clj/s

(nblank-str? x)

nblank? clj/s

(nblank? x)

neg-float? clj/s

(neg-float? x)

neg-int? clj/s

(neg-int? x)

neg-num? clj/s

(neg-num? x)

nempty-str? clj/s

(nempty-str? x)

nested-merge clj/s

(nested-merge & maps)

Like merge but does nested merging.

nested-merge-with clj/s

(nested-merge-with f & maps)

Like merge-with but does nested merging.

new-object clj/s macro

(new-object)

newline clj/s

Single system newline

newlines clj/s

Double system newline

nneg? clj/s

(nneg? x)

nnil clj/s

(nnil)

(nnil x)

(nnil x y)

(nnil x y z)

(nnil x y z & more)

Returns first non-nil arg, or nil.

node-paths clj/s

(node-paths m)

(node-paths node-pred m)

(node-paths node-pred m basis)

node-target? cljs

norm-str clj

(norm-str s)

(norm-str form s)

Given a Unicode string, returns the normalized de/composed form. It's often a good idea to normalize strings before exchange or storage, especially if you're going to be querying against those string.

form is ∈ #{:nfc :nfkc :nfd :nfkd <java.text.NormalizerForm>}. Defaults to :nfc as per W3C recommendation.

norm-word-breaks clj/s

(norm-word-breaks s)

Converts all word breaks of any form and length (including line breaks of any form, tabs, spaces, etc.) to a single regular space.

normalize-headers clj

(normalize-headers rreq-or-rresp)

now-dt clj

(now-dt)

Returns current system instant as java.util.Date.

now-inst clj/s≠

(now-inst)

clj

Returns current system instant as java.time.Instant.

cljs

Returns current system instant as js/Date.

now-nano clj/s≠

clj

(now-nano)

cljs

Returns current value of best-resolution time source as nanoseconds.

now-udt clj/s≠

(now-udt)

clj

Returns current system instant as milliseconds since Unix epoch.

cljs

Returns current system insant as milliseconds since Unix epoch.

nzero-num? clj/s

(nzero-num? x)

oget cljs

(oget k)

(oget o k)

(oget o k not-found)

Like get for JS objects.

oget-in cljs

(oget-in ks)

(oget-in o ks)

(oget-in o ks not-found)

Like get-in for JS objects.

or-some clj/s macro

(or-some)

(or-some x)

(or-some x & next)

Like or, but returns the first non-nil form (may be falsey).

oset cljs

(oset o k v)

Like assoc for JS objects.

oset-in cljs

(oset-in o ks v)

Experimental. Like assoc-in for JS objects.

parse-js-int cljs

(parse-js-int s)

parse-query-params clj/s

(parse-query-params s & [keywordize? encoding])

Based on ring-codec/form-decode.

parse-version clj/s

(parse-version x)

path clj/s

(path & parts)

perc clj/s

(perc n divisor)

pnum-complement clj/s

(pnum-complement pnum)

pnum? clj/s

(pnum? x)

Returns true iff given number in unsigned unit proportion interval ∈ℝ[0,1].

pool-executor clj

(pool-executor {:keys [n-threads n-min-threads n-max-threads thread-name-prefix
                       daemon-threads? keep-alive-msecs queue-type queue-size]
                :or {n-threads (+ 2 (get-num-threads [:ratio 1.0]))
                     thread-name-prefix "com.taoensso/encore-pool-"
                     daemon-threads? true
                     keep-alive-msecs 60000
                     queue-type :linked}})

Experimental, subject to change without notice! Returns new java.util.concurrent.ThreadPoolExecutor with given opts.

pos-float? clj/s

(pos-float? x)

pos-int? clj/s

(pos-int? x)

pos-num? clj/s

(pos-num? x)

pow clj/s

(pow n exp)

pr clj/s≠

clj

(pr & args)

Like core/pr but faster, and atomic (avoids interleaved content from different threads).

cljs

Identical to core/pr.

pr-edn clj/s

(pr-edn x)

Prints given arg to an edn string readable with read-edn.

pr-json clj/s≠

(pr-json x)

clj

Returns given Clj argument as JSON string.

Uses the first of the following, with its defaults:

1. metosin/jsonista, Ref. https://github.com/metosin/jsonista
2. org.clojure/clojure.data, Ref. https://github.com/clojure/data.json
3. cheshire, Ref. https://github.com/dakrone/cheshire

Throws if none of the above are available.

cljs

Returns given Cljs argument as JSON string.

pre-cache clj

(pre-cache n-capacity f)

(pre-cache n-capacity fp-or-n-threads f)

Given a nullary fn f that is non-idempotent and free of side-effects, returns a wrapped version of f that asynchronously maintains a cache of up to n-capacity pre-computed return values of (f).

Useful when f is expensive & may be called in a spikey fashion, e.g. ideal for cryptographic key generators.

pred clj/s

(pred pred-fn)

Experimental, subject to change without notice! Wraps given predicate fn to return Pred for use with submap?, etc. Arity of predicate fn depends on context in which it'll be used. See also pred-fn.

pred-fn clj/s

(pred-fn pred)

Experimental, subject to change without notice! Returns unwrapped predicate fn when given Pred, otherwise returns nil. See also pred.

preserve-reduced clj/s

(preserve-reduced rf)

Public version of core/preserving-reduced.

print clj/s≠

clj

(print & args)

Like core/print but faster, and atomic (avoids interleaved content from different threads).

cljs

Identical to core/print.

println clj/s≠

clj

(println & args)

Like core/println but faster, and atomic (avoids interleaved content from different threads).

cljs

Identical to core/println.

prn clj/s≠

clj

(prn & args)

Like core/prn but faster, and atomic (avoids interleaved content from different threads).

cljs

Identical to core/prn.

pull-val! clj/s

(pull-val! atom_ k)

(pull-val! atom_ k not-found)

Removes and returns value mapped to key: (let [a (atom {:k :v})] [(pull-val! a :k) @a]) => [:v {}]

qb clj/s macro

(qb spec form)

(qb spec form & more)

Simple util to benchmark/compare runtime of given form/s.

Runs sets of laps for each given form, recording the total runtime of each set. Returns the the total runtime in msecs of the fastest set of laps for each form.

(quick-bench [<num-sets> <num-laps>] <form1> <form2> <...>) => [<total runtime msecs of fastest set of laps for form1> <total runtime msecs of fastest set of laps for form2> <...>]

Total number of runs for each form is: num-sets * num-laps

If omitted, the default num-sets is 6 (to include warmup): (quick-bench <num-laps> <form1> <form2> <...>)

Example (comparing runtime of first and nth against vector): (let [v [:a]] (quick-bench 1e6 (first v) (nth v 0))) => [67.43 39.05]

qualified-ident? clj/s

(qualified-ident? x)

qualified-keyword? clj/s

(qualified-keyword? x)

qualified-symbol? clj/s

(qualified-symbol? x)

queue clj/s

(queue)

(queue coll)

Returns a new PersistentQueue.

queue* clj/s

(queue* & items)

Returns a new PersistentQueue given items.

queue? clj/s

(queue? x)

Returns true iff given a PersistentQueue.

quick-bench clj/s macro

(quick-bench spec form)

(quick-bench spec form & more)

Simple util to benchmark/compare runtime of given form/s.

Runs sets of laps for each given form, recording the total runtime of each set. Returns the the total runtime in msecs of the fastest set of laps for each form.

(quick-bench [<num-sets> <num-laps>] <form1> <form2> <...>) => [<total runtime msecs of fastest set of laps for form1> <total runtime msecs of fastest set of laps for form2> <...>]

Total number of runs for each form is: num-sets * num-laps

If omitted, the default num-sets is 6 (to include warmup): (quick-bench <num-laps> <form1> <form2> <...>)

Example (comparing runtime of first and nth against vector): (let [v [:a]] (quick-bench 1e6 (first v) (nth v 0))) => [67.43 39.05]

rand-id-fn clj/s

(rand-id-fn {:keys [chars len rand-bytes-fn]
             :or {chars :nanoid len 21 rand-bytes-fn secure-rand-bytes}})

Returns a (fn rand-id []) that returns random id strings. Uses strong randomness when possible.

Options include: :chars - ∈ #{<string> :nanoid :alphanumeric :no-look-alikes ...} :len - Length of id strings to generate :rand-bytes-fn - Optional (fn [size]) to return random byte array of given size

See also uuid-str, nano-id.

rate-limiter clj/s

(rate-limiter spec)

(rate-limiter opts spec)

Takes a map spec of form {<limit-id> [<n-max-reqs> <msecs-window>]}, and returns a basic stateful (fn rate-limiter [req-id] [command req-id]).

Call fn with a single request id (e.g. username) by which to count/limit. Will return:

• nil when all limits pass for that id, or
• [<worst-limit-id> <worst-backoff-msecs> {<limit-id> <backoff-msecs>}] when any limits fail for that id.

Or call fn with an additional command argument: :rl/peek <req-id> - Check limits w/o incrementing count. :rl/reset <req-id> - Reset all limits for given req-id.

Example:

(defonce my-rate-limiter (rate-limiter {"1 per sec" [1 1000] "10 per min" [10 60000]}))

(defn send-message! [username msg-content] (if-let [fail (my-rate-limiter username)] (throw (ex-info "Sorry, rate limited!" {:fail fail})) <send message>))

rcompare clj/s

(rcompare x y)

Reverse comparator.

re-pattern? clj/s

(re-pattern? x)

read-edn clj/s≠

clj

(read-edn s)

(read-edn {:keys [readers default]
           :as opts
           :or {readers clojure.core/*data-readers*
                default clojure.core/*default-data-reader-fn*}})

cljs

(read-edn s)

(read-edn {:keys [readers default]
           :as opts
           :or {readers (clojure.core/deref cljs.reader/*tag-table*)
                default (clojure.core/deref
                          cljs.reader/*default-data-reader-fn*)}})

Reads given edn string to return a Clj/s object.

reassoc-some clj/s

(reassoc-some m m-kvs)

(reassoc-some m k v)

(reassoc-some m k v & kvs)

Assocs each kv to given ?map if its value is nil, otherwise dissocs it.

reduce-indexed clj/s

(reduce-indexed rf init coll)

Like reduce but takes (rf [acc idx in]) with idx as in map-indexed. As reduce-kv against vector coll, but works on any seqable coll type.

reduce-interleave-all clj/s

(reduce-interleave-all rf init colls)

Reduces sequence of elements interleaved from given colls. (reduce-interleave-all conj [] [[:a :b] [1 2 3]]) => [:a 1 :b 2 3]

reduce-iterator! clj

(reduce-iterator! rf init iterator)

Reduces given java.util.Iterator, mutating it. Note that most colls providing iterators implement java.lang.Iterable, so support seq directly.

reduce-kvs clj/s

(reduce-kvs rf init kvs)

Like reduce-kv but takes a flat sequence of kv pairs.

reduce-multi clj/s

(reduce-multi rf init coll)

(reduce-multi rf1 init1 rf2 init2 coll)

(reduce-multi rf1 init1 rf2 init2 rf3 init3 coll)

Like reduce but supports separate simultaneous accumulators as a micro-optimisation when reducing a large collection multiple times.

reduce-n clj/s

(reduce-n rf init end)

(reduce-n rf init start end)

(reduce-n rf init start end step)

reduce-obj cljs

(reduce-obj f init o)

Like reduce-kv but for JavaScript objects.

reduce-top clj/s

(reduce-top n rf init coll)

(reduce-top n keyfn rf init coll)

(reduce-top n keyfn cmp rf init coll)

Reduces the top n items from coll of N items. Clj impln is O(N.logn) vs O(N.logN) for (take n (sort-by ...)).

reduce-zip clj/s

(reduce-zip rf init xs ys)

Reduces given sequential xs and ys as pairs (e.g. key-val pairs). Calls (rf acc x y) for each sequential pair.

Useful, among other things, as a more flexible version of zipmap.

remove-keys clj/s

(remove-keys key-pred m)

Returns given ?map, removing keys for which (key-pred <key>) is truthy.

remove-vals clj/s

(remove-vals val-pred m)

Returns given ?map, removing keys for which (val-pred <val>) is truthy.

rename-keys clj/s

(rename-keys replacements m)

Returns a map like the one given, replacing keys using given {<old-new> <new-key>} replacements. O(min(n_replacements, n_m)).

repeatedly-into clj/s

(repeatedly-into coll n f)

Like repeatedly but faster and conjs items into given collection.

require-telemere-if-present clj/s macro

(require-telemere-if-present)

Experimental, subject to change without notice! Requires Telemere if it's present, otherwise no-ops. For Cljs: needs ClojureScript >= v1.9.293, and must be placed at top of file. Used in cooperation with signal!.

reset!? clj/s

(reset!? atom_ val)

Atomically swaps value of atom_ to val and returns true iff the atom's value changed. See also reset-in!?.

reset-in! clj/s

(reset-in! atom_ val)

(reset-in! atom_ ks val)

(reset-in! atom_ ks not-found val)

Like reset! but supports update-in semantics, returns <old-key-val>.

reset-in!? clj/s

(reset-in!? atom_ val)

(reset-in!? atom_ ks val)

(reset-in!? atom_ ks not-found val)

Like reset-in! but returns true iff the atom's value changed.

reset-val! clj/s

(reset-val! atom_ k val)

(reset-val! atom_ k not-found val)

Like reset-in! but optimized for single-key case.

reset-val!? clj/s

(reset-val!? atom_ k new-val)

Like reset-in!? but optimized for single-key case.

resolve-sym clj

(resolve-sym sym)

(resolve-sym macro-env sym)

(resolve-sym macro-env sym may-require-ns?)

Returns resolved qualified Clj/s symbol, or nil.

revery-kv? clj/s

(revery-kv? pred coll)

revery? clj/s

(revery? pred coll)

(revery? xform pred coll)

rfirst clj/s

(rfirst pred coll)

(rfirst xform pred coll)

rfirst-kv clj/s

(rfirst-kv pred coll)

ring-default-headers clj

(ring-default-headers headers rresp)

ring-merge-headers clj

(ring-merge-headers headers rresp)

ring-redirect-resp clj

(ring-redirect-resp url)

(ring-redirect-resp kind url)

(ring-redirect-resp kind url flash)

ring-resp-map clj

(ring-resp-map x)

ring-set-body clj

(ring-set-body body rresp)

ring-set-headers clj

(ring-set-headers headers rresp)

ring-set-status clj

(ring-set-status code rresp)

rnum? clj/s

(rnum? x)

Returns true iff given number in signed unit proportion interval ∈ℝ[-1,1].

rolling-counter clj/s

(rolling-counter msecs)

Experimental. Returns a RollingCounter that you can:

• Invoke to increment count in last msecs window and return RollingCounter.
• Deref to return count in last msecs window.

rolling-list clj

(rolling-list nmax)

(rolling-list nmax {:keys [init-val]})

Returns a stateful fn of 2 arities: (fn [ ]) => Returns current array in O(n). (fn [x]) => Adds x to right of list, maintaining length <~ nmax. Returns nil. Very fast (faster than rolling-vector).

Useful for maintaining limited-length histories, etc. See also rolling-vector.

rolling-vector clj/s

(rolling-vector nmax)

(rolling-vector nmax {:keys [gc-every init-val] :or {gc-every 16000.0}})

Returns a stateful fn of 2 arities: (fn [ ]) => Returns current sub/vector in O(1). (fn [x]) => Adds x to right of sub/vector, maintaining length <= nmax. Returns current sub/vector.

Useful for maintaining limited-length histories, etc. See also rolling-list (Clj only).

round* clj/s

(round* n)

(round* kind n)

(round* kind precision n)

round0 clj/s

(round0 n)

round1 clj/s

(round1 n)

round2 clj/s

(round2 n)

roundn clj/s

(roundn precision n)

rsome clj/s

(rsome pred coll)

(rsome xform pred coll)

rsome-kv clj/s

(rsome-kv pred coll)

run! clj/s

(run! proc coll)

run-kv! clj/s

(run-kv! proc m)

run-kvs! clj/s

(run-kvs! proc kvs)

run-obj! cljs

(run-obj! proc obj)

runner clj

(runner {:keys [mode buffer-size n-threads thread-name daemon-threads?]
         :as opts
         :or {mode :dropping buffer-size 1024 n-threads 1}})

Experimental, subject to change without notice!!

Returns a new stateful "runner" such that:

(runner f) Requests runner to execute given nullary fn according to runner's opts. Returns: - true if runner accepted fn for execution without back pressure. - false if runner experienced back-pressure (fn may/not execute). - nil if runner has stopped accepting new execution requests.

(runner) Instructs runner to permanently stop accepting new execution requests. Returns true iff runner's status changed with this call.

Runners provide ~similar capabilities to agents, but:

• Take nullary fns rather than unary fns of state.
• Have no validators or watches.
• Have (configurable) back pressure.
• May execute fns in non-sequential order when n-threads > 1.

These properties make them useful as configurable async workers, etc.

Options include: mode - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}. buffer-size - Size of buffer before back-pressure mechanism is engaged. n-threads - Number of threads for asynchronously executing fns. NB execution order may be non-sequential when n > 1.

satisfies! clj/s macro

(satisfies! protocol arg)

(satisfies! protocol arg {:keys [msg context param ...]})

(satisfies! protocol arg & {:keys [msg context param ...]})

If (satisfies? protocol arg) is true, returns arg. Otherwise throws runtime ExceptionInfo with unexpected-arg!. See unexpected-arg! for more info.

satisfies? clj/s macro

(satisfies? protocol x)

Faster satisfies? to work around CLJ-1814 until a proper upstream fix. May cache, so possibly inappropriate for dynamic work.

sayf cljs

(sayf fmt & xs)

sayp cljs

(sayp & xs)

sb-append clj/s

(sb-append str-builder x)

(sb-append str-builder x & more)

Appends given string/s to given string builder. See also str-builder.

secs clj/s

(secs opts)

(secs & {:as opts :keys [years months weeks days hours mins secs msecs ms]})

Returns ~number of seconds in period defined by given args.

secs->ms clj/s

(secs->ms secs)

secure-rand-bytes clj/s

(secure-rand-bytes size)

Returns a random byte array of given size. Uses strong randomness when possible.

secure-rng clj

(secure-rng)

Returns a an auto-reseeding thread-local java.security.SecureRandom. Favours security over performance. May block while waiting on entropy!

secure-rng-mock!!! clj

(secure-rng-mock!!! long-seed)

Returns INSECURE java.security.SecureRandom mock instance backed by a seeded deterministic java.util.Random. Useful for testing, etc.

select-nested-keys clj/s

(select-nested-keys src-map key-spec)

Like select-keys but supports nested key spec:

(select-nested-keys {:a :A :b :B :c {:c1 :C1 :c2 :C2} :d :D} ; src-map [:a {:c [:c1], :d [:d1 :d2]}]) ; key-spec

=> {:a :A, :c {:c1 :C1}, :d :D}

Note that as with the {:d [:d1 :d2]} spec in the example above, if spec expects a nested map but the actual value is not a map, the actual value will be included in output as-is.

Has the same behaviour as select-keys when key-spec is a simple vector of keys.

seq-kvs clj/s

(seq-kvs {:a :A}) => (:a :A).

session-swap clj

(session-swap rreq rresp f & args)

Util to help correctly update Ring sessions (something easy to get wrong!).

Given a Ring request (rreq) and Ring response (rresp), returns a new Ring response with the response session updated to be (f <old-session>) or (apply f <old-session> args).

set-var-root! clj/s macro

(set-var-root! var-sym root-val)

Sets root binding (value) of the var identified by given symbol, and returns the new value. Cross-platform. See also update-var-root!.

signal! clj/s macro

(signal! {:as opts
          :keys [fallback elidable? location instant uid middleware sample-rate
                 kind ns id level when rate-limit ctx parent trace? do let data
                 msg error run & extra-kvs]})

Experimental, subject to change without notice! Expands to taoensso.telemere/signal! call if Telemere is present, otherwise expands to fallback.

MUST be used with require-telemere-if-present:

(ns my-ns (:require [taoensso.encore :as enc])) (encore/require-telemere-if-present) ; At top of file, just below ns form

(encore/signal! {<signal-opts> :fallback (println "Prints iff Telemere not present")})

For more info, see:

• Telemere signal! docstring, Ref. https://tinyurl.com/telemere-signal
• Telemere documentation, Ref. https://tinyurl.com/telemere-docs

simple-date-format clj

(simple-date-format pattern & [{:keys [locale timezone] :as opts}])

Returns a thread-local java.text.SimpleDateFormat.

simple-date-format* clj

(simple-date-format* pattern locale timezone)

simple-ident? clj/s

(simple-ident? x)

simple-keyword? clj/s

(simple-keyword? x)

simple-symbol? clj/s

(simple-symbol? x)

slurp-file-resource clj

Like slurp-resource but caches slurps against file's last-modified udt.

slurp-resource clj

(slurp-resource rname)

Returns slurped named resource on classpath, or nil when resource not found.

some= clj/s

(some= x y)

(some= x y & more)

some? clj/s

(some? x)

Same as core/some? (added in Clojure v1.6).

sortv clj/s

(sortv coll)

(sortv comparator coll)

(sortv ?keyfn comparator coll)

Like core/sort but:

• Returns a vector.
• comparator can be :asc, :desc, or an arbitrary comparator.
• An optional keyfn may be provided, as in core/sort-by.

str->utf8-ba clj

(str->utf8-ba s)

str-?index clj/s

(str-?index s substr)

(str-?index s substr start-idx)

(str-?index s substr start-idx last?)

Returns (first/last) ?index of substring if it exists within given string.

str-builder clj/s

(str-builder)

(str-builder init)

Returns a new stateful string builder:

• java.lang.StringBuilder for Clj
• goog.string.StringBuffer for Cljs

See also sb-append.

str-builder? clj/s

(str-builder? x)

str-contains? clj/s

(str-contains? s substr)

str-ends-with? clj/s

(str-ends-with? s substr)

str-join clj/s

(str-join xs)

(str-join separator xs)

(str-join separator xform xs)

Faster generalization of clojure.string/join with transducer support.

str-join-once clj/s

(str-join-once separator coll)

Like string/join but skips nils and duplicate separators.

str-replace clj/s

(str-replace s match replacement)

Like str/replace but provides consistent clj/s behaviour.

Workaround for http://dev.clojure.org/jira/browse/CLJS-794, http://dev.clojure.org/jira/browse/CLJS-911.

Note that ClojureScript 1.7.145 introduced a partial fix for CLJS-911. A full fix could unfortunately not be introduced w/o breaking compatibility with the previously incorrect behaviour. CLJS-794 also remains unresolved.

str-rf clj/s

(str-rf)

(str-rf acc)

(str-rf acc in)

String builder reducing fn.

str-starts-with? clj/s≠

clj

cljs

(str-starts-with? s substr)

stringy? clj/s

(stringy? x)

submap? clj/s

(submap? m sub)

Returns true iff sub is a (possibly nested) submap of m, i.e. iff every (nested) value in sub has the same (nested) value in m. Uses stack recursion so supports only limited nesting.

swap-in! clj/s

(swap-in! atom_ f)

(swap-in! atom_ ks f)

(swap-in! atom_ ks not-found f)

Like swap! but supports update-in semantics and swapped. Returns <new-key-val> or <swapped-return-val>: (swap-in! (atom {:k1 {:k2 5}}) [:k1 :k2] inc) => 6 (swap-in! (atom {:k1 {:k2 5}}) [:k1 :k2] (fn [old] (swapped (inc old) old))) => 5

swap-val! clj/s

(swap-val! atom_ k f)

(swap-val! atom_ k not-found f)

Like swap-in! but optimized for single-key case: (swap-val! (atom {:k 5}) :k inc) => 6 (swap-val! (atom {:k 5}) :k (fn [old] (swapped (inc old) old))) => 5

swapped clj/s

(swapped new-val return-val)

For use within the swap functions of swap-in! and swap-val!.

Allows the easy decoupling of new and returned values. Compare: (let [a (atom 0)] [(core/swap! a (fn [old] (inc old) )) @a]) [1 1] ; new=1, return=1 (let [a (atom 0)] [(swap-in! a (fn [old] (swapped (inc old) old))) @a]) [0 1] ; new=1, return=0

Faster and much more flexible than core/swap-vals!, etc. Especially useful when combined with the update-in semantics of swap-in!, etc.

swapped? clj/s

(swapped? x)

Returns true iff given Swapped argument.

takev clj/s

(takev n coll)

test-fixtures clj/s

(test-fixtures fixtures-map)

Given a {:before ?(fn []) :after ?(fn [])} map, returns cross-platform test fixtures for use by both clojure.test and cljs.test:

(let [f (test-fixtures {:before (fn [] (test-setup))})] (clojure.test/use-fixtures :once f) (cljs.test/use-fixtures :once f))

thread-local clj/s macro

(thread-local & body)

Given a body that returns an initial value for the current thread, returns a ThreadLocal proxy that can be derefed to get the current thread's current value.

Commonly used to achieve thread safety during Java interop. In the common case, body will be a call to some Java constructor that returns a non-thread-safe instance.

Example: (def thread-local-simple-date-format_ "Deref to return a thread-local SimpleDateFormat" (thread-local (SimpleDateFormat. "yyyy-MM-dd")))

(.format @thread-local-simple-date-format_ (Date.)) => "2023-01-24"

NB: don't pass the derefed value to other threads!

thread-local* clj

(thread-local* init-val-fn)

Low-level, see thread-local instead.

thread-local-proxy clj/s macro

(thread-local-proxy & body)

Low-level, see thread-local instead.

throwable? clj

(throwable? x)

throws clj/s macro

(throws form)

(throws kind form)

(throws kind pattern form)

Evals form and if it throws an error that matches given criteria using matching-error, returns the matching error. Otherwise returns nil.

See also matching-error, throws?.

throws? clj/s macro

(throws? form)

(throws? kind form)

(throws? kind pattern form)

Evals form and if it throws an error that matches given criteria using matching-error, returns true. Otherwise returns false.

Useful for unit tests, e.g.: (is (throws? {:a :b} (throw (ex-info "Test" {:a :b :c :d}))))

See also matching-error, throws.

time-ms clj/s macro

(time-ms & body)

Returns number of milliseconds it took to execute body.

time-ns clj/s macro

(time-ns & body)

Returns number of nanoseconds it took to execute body.

timeout-future? clj/s

(timeout-future? x)

top clj/s

(top n coll)

(top n keyfn coll)

(top n keyfn cmp coll)

Returns a sorted vector of the top n items from coll using reduce-top.

top-into clj/s

(top-into to n coll)

(top-into to n keyfn coll)

(top-into to n keyfn cmp coll)

Conjoins the top n items from coll into to using reduce-top.

transient? clj/s

(transient? x)

try* clj/s macro

(try* expr catch-clause-or-clauses ?finally-clause)

Like try, but catch clause classnames can be the special keywords :any or :common for cross-platform catching. Addresses CLJ-1293.

try-eval clj/s macro

(try-eval form)

If form can be successfully evaluated at macro-expansion time, expands to form. Otherwise expands to nil.

udt->inst clj/s≠

(udt->inst msecs-since-epoch)

clj

Returns given milliseconds since Unix epoch as java.time.Instant.

cljs

Returns given milliseconds since Unix epoch as js/Date.

udt? clj/s

(udt? x)

unexpected-arg! clj/s

(unexpected-arg! arg)

(unexpected-arg! arg {:keys [msg context param expected ...]})

(unexpected-arg! arg & {:keys [msg context param expected ...]})

Throws runtime ExceptionInfo to indicate an unexpected argument. Takes optional kvs for merging into exception's data map.

(let [mode :unexpected] (case mode :read (do <...>) :write (do <...>) (unexpected-arg! mode :context `my-function :param 'mode :expected #{:read :write}))) =>

Unexpected argument: :unexpected {:arg {:value :unexpected, :type clojure.lang.Keyword}, :context 'taoensso.encore/my-function :param 'mode :expected #{:read :write}}

update-in clj/s

(update-in m ks f)

(update-in m ks not-found f)

Like core/update-in but:.

• Empty ks will return (f m), not act like [nil] ks.
• Adds support for not-found.
• Adds support for special return vals: :update/dissoc, :update/abort.

update-var-root! clj/s macro

(update-var-root! var-sym update-fn)

Updates root binding (value) of the var identified by given symbol, and returns the new value: (update-var-root! my-var (fn [old-root-val] <new-root-val>)) => <new-root-val>

Similar to alter-var-root but cross-platform and takes a symbol rather than a var. See also set-var-root!.

uri? clj

(uri? x)

url-decode clj/s

(url-decode s & [encoding])

Stolen from http://goo.gl/99NSR1.

url-encode clj/s≠

clj

(url-encode s & [encoding])

cljs

(url-encode s)

Based on https://goo.gl/fBqy6e.

utf8-ba->str clj

(utf8-ba->str ba)

uuid clj/s

(uuid)

For Clj: returns a random java.util.UUID. For Cljs: returns a random UUID string.

Uses strong randomness when possible. See also uuid-str, nanoid, rand-id-fn.

uuid-str clj/s

(uuid-str)

(uuid-str max-len)

Returns a random UUID string of given length (max 36). Uses strong randomness when possible. See also uuid, nanoid, rand-id-fn.

vec2? clj/s

(vec2? x)

vec3? clj/s

(vec3? x)

vinterleave-all clj/s

(vinterleave-all colls)

(vinterleave-all c1 c2)

(vinterleave-all c1 c2 c3)

(vinterleave-all c1 c2 c3 & colls)

Like interleave, but:

• Returns a vector rather than lazy seq (=> greedy).
• Includes all items (i.e. stops when the longest rather than shortest coll has been consumed).

Single-arity version takes a coll of colls.

virtual-executor clj

(virtual-executor)

Experimental, subject to change without notice! Returns new virtual java.util.concurrent.ThreadPerTaskExecutor when possible (JVM 21+), otherwise returns nil.

vnext clj/s

(vnext v)

vrest clj/s

(vrest v)

vsplit-first clj/s

(vsplit-first v)

vsplit-last clj/s

(vsplit-last v)

when clj/s macro

(when test-or-bindings & body)

Supersets core/when and core/when-let functionality. When test-or-bindings is a vector, same as encore/when-let. Otherwise same as core/when.

when-let clj/s macro

(when-let bindings & body)

Supersets core/when-let functionality. Like core/when-let but supports multiple bindings, and unconditional bindings with :let:

(when-let [x (rand-nth [:x1 :x2 false nil ]) ; Bind truthy x, or -> nil :let [y (rand-nth [:y1 :y2 false nil x ])] ; Bind any y z (rand-nth [:z1 :z2 false nil x y]) ; Bind truthy z, or -> nil ] [:body x y z])

when-not clj/s macro

(when-not test-or-bindings & body)

Supersets core/when-not functionality. Same as encore/if-let with body as else form.

when-some clj/s macro

(when-some test-or-bindings & body)

Supersets core/when-some functionality. Like core/when-some but supports multiple bindings, and unconditional bindings with :let:

(when-some [x (rand-nth [:x1 :x2 false nil ]) ; Bind non-nil x, or -> else :let [y (rand-nth [:y1 :y2 false nil x ])] ; Bind any y z (rand-nth [:z1 :z2 false nil x y]) ; Bind non-nil z, or -> else ] [:body x y z])

when? clj/s

(when? pred x)

with-dynamic-assertion-data clj/s macro deprecated

(with-dynamic-assertion-data data & body)

Prefer with-data

with-truss-data clj/s macro

(with-truss-data data & body)

Executes body with dynamic assertion data bound to given value. This data will be included in any violation errors thrown by body.

without-meta clj/s

(without-meta x)

xdistinct clj/s

(xdistinct)

(xdistinct keyfn)

Returns a stateful transducer like (core/distinct) that supports an optional key function. Retains only items with distinct (keyfn <item>).

zero-num? clj/s

(zero-num? x)