purpose of clojure reduced function

Question

What is the purpose of the clojure reduced function (added in clojure 1.5, https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/reduced)

I can't find any examples for it. The doc says:

Wraps x in a way such that a reduce will terminate with the value x.

There is also a reduced? which is acquainted to it

Returns true if x is the result of a call to reduced

When I try it out, e.g with (reduce + (reduced 100)), I get an error instead of 100. Also why would I reduce something when I know the result in advance? Since it was added there is likely a reason, but googling for clojure reduced only contains reduce results.

Answer 1

reduced allows you to short circuit a reduction:

(reduce (fn [acc x]
          (if (> acc 10)
            (reduced acc)
            (+ acc x)))
        0 
        (range 100))
;= 15

(NB. the edge case with (reduced 0) passed in as the initial value doesn't work as of Clojure 1.6.)

This is useful, because reduce-based looping is both very elegant and very performant (so much so that reduce-based loops are not infrequently more performant than the "natural" replacements based on loop/recur), so it's good to make this pattern as broadly applicable as possible. The ability to short circuit reduce vastly increases the range of possible applications.

As for reduced?, I find it useful primarily when implementing reduce logic for new data structures; in regular code, I let reduce perform its own reduced? checks where appropriate.