You're working with a collection in Clojure and need to iterate over it. You reach for... wait, which one?
In my experience, while the official documentation exists, it's often unclear when to use each construct. This guide breaks down the differences with practical examples, so you can make the right choice every time.
TLDR: Always use run! and doseq for side-effects, and map and for for lazy data transformations
Purpose: Transform each element of a collection into something else.
Returns: A lazy sequence of transformed values.
When to use:
You want to convert one collection into another
You're applying a transformation function
You need the result for further processing
Characteristics:
Lazy - only computes values when needed
Returns a sequence - the transformed collection
Pure - no side effects expected
(map #(* % %) [1 2 3 4])
(map :user-id users)
(map str/upper-case ["hello" "world"])
When NOT to use map:
The key insight is that map is lazy, so side effects inside map can lead to surprising results.
If you're doing side effects, you probably want doseq or run! instead.
(def squares (map #(do (println "Computing" %)
(* % %))
[1 2 3]))
(doall squares)
2. for - List Comprehensions
Purpose: Build a collection with complex iteration logic (filters, multiple bindings, let bindings).
Returns: A lazy sequence.
When to use:
You need complex iteration with multiple sequences
You want to filter while iterating
You need let bindings inside the iteration
You're translating a mathematical set notation
Characteristics:
Lazy - only computes when realized
Returns a sequence - the generated collection
Declarative - reads like "for each X in Y, produce Z"
(for [x [1 2 3]
y [4 5 6]
:when (even? (+ x y))]
[x y])
(for [user users
:let [email (:email user)
domain (second (str/split email #"@"))]
:when (= domain "example.com")]
(:name user))
(for [feed feeds
item (:items feed)]
(process-item feed item))
(def suits #{:hearts :diamonds :clubs :spades})
(def ranks ["2" "3" "4" "5" "6" "7" "8" "9" "10" "J" "Q" "K" "A"])
(defn make-deck
"Create a 52-card deck"
[]
(shuffle
(for [suit suits
rank ranks]
{:suit suit :rank rank})))
Rule of thumb: Use for when you need :when, :let, or multiple sequences. Use map for simple one-to-one transformations.
Generally, follow the same rules as map Don’t use this when you need to generate side effects.
(for [user users]
(:email user))
(map :email users)
=> (doall (map println [1 2 3]))
1
2
3
(nil nil nil)
3. doseq - Imperative Iteration for Side Effects
Purpose: Execute side effects for each element in a collection.
Returns: nil (you're not using the return value).
When to use:
You're doing I/O (printing, file writes, network calls)
You're mutating state (atoms, databases)
You need multiple operations per item
You need destructuring or complex bindings
Characteristics:
Eager - executes immediately
Returns nil - signals "I'm doing side effects"
Imperative - like a for loop in other languages
(doseq [{:keys [name email role]} users]
(when (= role "admin")
(send-admin-notification name email)))
(doseq [order orders]
(send-confirmation-email order)
(update-inventory order)
(log-transaction order))
(doseq [feed feeds]
(println "Processing" (:feed-id feed))
(doseq [item (:items feed)]
(save-to-db item)))
4. run! - Concise Side Effects
Purpose: Apply a single side-effecting function to each element.
Returns: nil.
When to use:
Characteristics:
Eager - executes immediately
Returns nil - signals side effects
Concise - one-liner for simple cases
run! is more concise for when you're just calling a single function
(doseq [alert alerts]
(println alert))
(run! println alerts)
(run! send-email users)
(run! save-to-db documents)
(run! #(.close %) connections)
When You Shouldn’t Use run!
(doseq [user users]
(send-email user)
(log-activity user)
(update-db user))
(run! (fn [{:keys [name email]}]
(send-email name email))
users)
(doseq [{:keys [name email]} users]
(send-email name email))
(run! (fn [user]
(when (active? user)
(send-notification user)))
users)
(doseq [user users]
(when (active? user)
(send-notification user)))
Summary
| Construct | Returns | Eager/Lazy | Primary Use | Side Effects? |
map | Transformed sequence | Lazy | Transform data | ❌ No (pure) |
for | Generated sequence | Lazy | Complex collection building | ❌ No (pure) |
doseq | nil | Eager | Multiple side effects per item | ✅ Yes |
run! | nil | Eager | Single function call per item | ✅ Yes |
Understanding the different iteration constructs in Clojure is crucial for writing efficient and effective code.
Use map and for when transforming data with lazy evaluation and pure functions. For producing side effects, doseq and run! are better suited, providing eager execution and clear intent for side-effecting operations.
I hope this helps on your Clojure journey. It has definitely helped in mine.
Further Reading Resources:
