Clojure Sequence API
A Clojure sequence (or seq, pronounced "seek") is a sequential collection that represents a series of values that may or may not exist yet. They may be values from a concrete collection or values that are computed as necessary. A sequence may also be empty.
Basic Sequence Operations
| Function | Description | Examples |
|---|---|---|
| (count coll) |
Returns the number of items in coll. Returns 0 when coll is nil.
|
(count [10 5 1]) ⇒ 3 (count ()) ⇒ 0 (count nil) ⇒ 0 |
| (seq coll) |
Some collections, such as lists, implement the seq API directly, so calling seq on them returns the collection itself. More often however, calling seq on a collection returns a new seq object for navigating that collection. Returns nil if coll is empty or nil.
|
(seq '(3 2 1)) ⇒ (3 2 1) (seq [3 2 1]) ⇒ (3 2 1) (seq "hello") ⇒ (\h \e \l \l \o) (seq []) ⇒ nil (seq nil) ⇒ nil |
Sequence Navigation
| Function | Description | Examples |
|---|---|---|
| (butlast coll) |
Returns a sequence with the same items as coll except the last one. Calls seq on its argument. Returns nil if coll is empty or nil.
|
(butlast [3 2 1]) ⇒ (3 2) (butlast "hello") ⇒ (\h \e \l \l) (butlast [1]) ⇒ nil (butlast []) ⇒ nil (butlast nil) ⇒ nil |
| (first coll) |
Returns the first item in coll. Calls seq on its argument. Returns nil if coll is empty or nil.
|
(first [3 2 1]) ⇒ 3 (first "hello") ⇒ \h (first []) ⇒ nil (first nil) ⇒ nil |
| (last coll) |
Returns the last item in coll. Calls seq on its argument. Returns nil if coll is empty or nil.
|
(last [3 2 1]) ⇒ 1 (last "hello") ⇒ \o (last []) ⇒ nil (last nil) ⇒ nil |
| (next coll) | Equivalent to: (seq (rest coll)) |
(next [3 2 1]) ⇒ (2 1) (next "hello") ⇒ (\e \l \l \o) (next [1]) ⇒ nil (next []) ⇒ nil (next nil) ⇒ nil |
|
(nth coll index) (nth coll index not-found) |
Returns the value in coll at the zero-based index. If index is out of bounds, throws an exception unless not-found is supplied. |
(nth '(a b c d) 0) ⇒ a (nth '(a b c d) 3) ⇒ d (nth '(a b c d) 4 'oops) ⇒ oops |
| (peek coll) |
Same as first when applied to a sequence.
|
(peek '(3 2 1)) ⇒ 3 (peek ()) ⇒ nil (peek nil) ⇒ nil |
| (pop coll) |
Similar to rest, but throws an exception when coll is empty. Returns nil if coll is nil.
|
(pop '(3 2 1)) ⇒ (2 1) (pop nil) ⇒ nil |
| (rest coll) |
Returns a sequence with the same items as coll except the first one. Calls seq on its argument. Returns an empty sequence if coll is empty or nil.
|
(rest [3 2 1]) ⇒ (2 1) (rest "hello") ⇒ (\e \l \l \o) (rest [1]) ⇒ () (rest []) ⇒ () (rest nil) ⇒ () |
Sequence Predicates
| Function | Description | Examples |
|---|---|---|
| (empty? coll) |
Returns true if coll has no items, otherwise returns false. It is equivalent to: (not (seq coll)). Use the idiom (seq x) rather than (not (empty? x)).
|
(empty? ()) ⇒ true (empty? '(a b c)) ⇒ false (empty? nil) ⇒ true |
| (every? pred coll) |
Returns true if (pred x) is true for every x in coll, otherwise returns false.
|
(every? even? [4 6 10 8 2]) ⇒ true (every? even? [4 6 5 10 8 2]) ⇒ false (every? even? []) ⇒ true |
| (seq? x) |
Returns true if x is a sequence (i.e. it implements the clojure.lang.ISeq interface), otherwise returns false.
|
(seq? '(3 2 1)) ⇒ true (seq? [3 2 1]) ⇒ false (seq? "hello") ⇒ false (seq? ()) ⇒ true (seq? nil) ⇒ false (seq? 42) ⇒ false |
| (some pred coll) |
Returns the first logical true value of (pred x) for any x in coll, otherwise returns nil.
|
(some even? [4 6 10 8 2]) ⇒ true (some odd? [4 6 5 10 8 2]) ⇒ true (some first '([] () (a b c) [])) ⇒ a (some first '([] () [])) ⇒ nil |
Creating Sequences
| Function | Description | Examples |
|---|---|---|
| (concat & colls) | Returns a lazy sequence representing the concatenation of the elements in the supplied colls. |
(concat [1 2 3] '(a b c)) ⇒ (1 2 3 a b c) (concat [1 2] [3 4 5] [6]) ⇒ (1 2 3 4 5 6) (concat) ⇒ () |
| (cons x coll) |
Returns a new sequence where x is the first element and coll is the rest. Calls seq on its argument.
|
(cons 4 [3 2 1]) ⇒ (4 3 2 1) (cons \h "ello") ⇒ (\h \e \l \l \o) (cons 1 []) ⇒ (1) (cons 1 nil) ⇒ (1) |
| (cycle coll) | Returns an infinite lazy sequence of repetitions of all the items in coll. Returns an empty sequence if coll is empty. |
(take 6 (cycle [1 2])) ⇒ (1 2 1 2 1 2) (take 10 (cycle '(a b c d))) ⇒ (a b c d a b c d a b) (cycle ()) ⇒ () |
|
(interleave coll1 coll2 & colls) |
Returns a lazy sequence composed of the first item in each coll, then the second item, and so on. It stops when any of the collections is exhausted. |
(interleave [1 2 3] '(a b c)) ⇒ (1 a 2 b 3 c) (interleave '(a b c) [1 2 3 4]) ⇒ (a 1 b 2 c 3) (interleave (range 5) "hello" '(a b c d e f)) ⇒ (0 \h a 1 \e b 2 \l c 3 \l d 4 \o e) (interleave [] [1 2 3]) ⇒ () |
| (interpose sep coll) | Returns a lazy sequence of the elements of coll separated by sep. |
((interpose 'a [1 2 3 4]) ⇒ (1 a 2 a 3 a 4) (interpose 'a []) ⇒ () |
| (iterate f x) | Returns an infinite lazy sequence composed of x, (f x), (f (f x)), and so on. f must be free of side-effects. |
(take 8 (iterate #(* % 2) 1)) ⇒ (1 2 4 8 16 32 64 128) (take 5 (iterate #(conj % 'a) [])) ⇒ ([] [a] [a a] [a a a] [a a a a]) |
|
(range) (range end) (range start end) (range start end step) |
Returns a lazy sequence of integers beginning at start (inclusive) and containing the successive results of adding step to the previous element up to end (exclusive). start defaults to 0, step to 1, and end to infinity. Returns an empty sequence if step is 0. |
(range 5) ⇒ (0 1 2 3 4) (range 10 15) ⇒ (10 11 12 13 14) (range 0 10 2) ⇒ (0 2 4 6 8) (range 20 0 -5) ⇒ (20 15 10 5) (take 5 (range)) ⇒ (0 1 2 3 4) (range 10 20 0) ⇒ () |
|
(repeat x) (repeat n x) |
Returns a lazy sequence which contains n copies of x. If n is not supplied, returns an infinite sequence. |
(repeat 3 'hello) ⇒ (hello hello hello) (repeat 0 'a) ⇒ () (take 10 (repeat 5)) ⇒ (5 5 5 5 5 5 5 5 5 5) |
| (reverse coll) | Returns a sequence of the items in coll in reverse order. Not lazy. |
(reverse '(a b c d)) ⇒ (d c b a) (reverse [1 2 [3 4 5 6] 7]) ⇒ (7 [3 4 5 6] 2 1) (reverse ()) ⇒ () (reverse nil) ⇒ () |
Filtering Sequences
| Function | Description | Examples |
|---|---|---|
| (distinct coll) | Returns a lazy sequence of the elements of coll with duplicates removed. |
(distinct '(a b b a c a)) ⇒ (a b c) (distinct ()) ⇒ () (distinct [1 2 3]) ⇒ (1 2 3) |
| (drop n coll) | Returns a lazy sequence of all but the first n items in coll. |
(drop 4 '(a b c d e f)) ⇒ (e f) (drop 10 [1 2 3]) ⇒ () (drop 0 [1 2 3]) ⇒ (1 2 3) |
| (drop-while pred coll) | Returns a lazy sequence of the items in coll starting from the first item for which (pred item) returns false. pred must be free of side-effects. |
(drop-while even? [2 10 6 3 4 9]) ⇒ (3 4 9) (drop-while pos? [-5 3 10 -1]) ⇒ (-5 3 10 -1) (drop-while neg? []) ⇒ () |
| (filter pred coll) | Returns a lazy sequence of the items in coll for which (pred item) returns a logical true value. pred must be free of side-effects. |
(filter even? [5 2 4 10 3]) ⇒ (2 4 10) (filter #(< % 10) [12 10 5 4 -1 15]) ⇒ (5 4 -1) (filter symbol? '(45 one [] true two)) ⇒ (one two) (filter list? '(45 one [] true two)) ⇒ () |
|
(partition n coll) (partition n step coll) (partition n step pad coll) |
Returns a lazy sequence of lists of n items each, at offsets step apart. step defaults to n (i.e. the partitions do not overlap). If a pad collection is supplied, use its elements as necessary to complete the last partition up to n items. In case there are not enough padding elements, return a partition with less than n items. |
(partition 2 '(a b c d e f g)) ⇒ ((a b) (c d) (e f)) (partition 3 2 '(a b c d e f g)) ⇒ ((a b c) (c d e) (e f g)) (partition 2 3 '(a b c d e f g)) ⇒ ((a b) (d e)) (partition 3 3 [1 2 3] '(a b c d e f g)) ⇒ ((a b c) (d e f) (g 1 2)) (partition 4 6 [1 2] '(a b c d e f g)) ⇒ ((a b c d) (g 1 2)) (partition 3 ()) ⇒ () |
|
(partition-all n coll) (partition-all n step coll) |
Returns a lazy sequence of lists like partition, but may include partitions with fewer than n items at the end.
|
(partition-all 2 '(a b c d e f g)) ⇒ ((a b) (c d) (e f) (g)) (partition-all 3 2 '(a b c d e f g)) ⇒ ((a b c) (c d e) (e f g) (g)) (partition-all 4 6 '(a b c d e f g)) ⇒ ((a b c d) (g)) (partition-all 3 ()) ⇒ () |
| (partition-by f coll) | Applies f to each item in coll, splitting it each time f returns a new value. Returns a lazy sequence of partitions. |
(partition-by neg? [3 -4 -5 10 1 0 -2 -1 4]) ⇒ ((3) (-4 -5) (10 1 0) (-2 -1) (4)) (partition-by first [[1] [1 2] [] [2 3] [2] [3]]) ⇒ (([1] [1 2]) ([]) ([2 3] [2]) ([3])) (partition-by even? ()) ⇒ () |
| (remove pred coll) | Returns a lazy sequence of the items in coll for which (pred item) returns a logical false value. pred must be free of side-effects. |
(remove even? [5 2 4 10 3]) ⇒ (5 3) (remove #(< % 10) [12 10 5 4 -1 15]) ⇒ (12 10 15) (remove symbol? '(45 one [] true two)) ⇒ (45 [] true) (remove list? '(45 one [] true two)) ⇒ (45 one [] true two) |
| (split-at n coll) |
Returns the vector: [(take n coll) (drop n coll)] |
(split-at 4 '(a b c d e f)) ⇒ [(a b c d) (e f)] (split-at 0 '(a b c d e f)) ⇒ [() (a b c d e f)] (split-at 100 '(a b c d e f)) ⇒ [(a b c d e f) ()] |
| (split-with pred coll) |
Returns the vector: [(take-while pred coll) (drop-while pred coll)] |
(split-with even? [2 10 6 3 4 9]) ⇒ [(2 10 6) (3 4 9)] (split-with pos? [-5 3 10 -1]) ⇒ [() (-5 3 10 -1)] (split-with neg? []) ⇒ [() ()] |
| (take n coll) |
Returns a lazy sequence of the first n items in coll, or all items if there are fewer than n. Calls seq on coll.
|
(take 3 [1 2 3 4 5]) ⇒ (1 2 3) (take 5 [1 2 3]) ⇒ (1 2 3) (take 5 "hello world") ⇒ (\h \e \l \l \o) (take 0 [1 2 3 4]) ⇒ () (take 5 []) ⇒ () |
| (take-while pred coll) | Returns a lazy sequence of successive items from coll while (pred item) returns true. pred must be free of side-effects. |
(take-while even? [2 10 6 3 4 9]) ⇒ (2 10 6) (take-while pos? [-5 3 10 -1]) ⇒ () (take-while neg? []) ⇒ () |
Transforming Sequences
| Function/Macro | Description | Examples |
|---|---|---|
| (for seq-exprs body-expr) |
Sequence comprehension. Takes a vector of one or more binding-form/collection-expression pairs, each followed by zero or more modifiers, and yields a lazy sequence of evaluations of body-expr. Collections are iterated in a nested fashion, rightmost fastest, and nested collection-expressions can refer to bindings created in prior binding-forms. Supported modifiers are:
|
(for [i [1 2 3 4 5]] (* i i)) ⇒ (1 4 9 16 25) (for [i [1 2 3 4 5] :let [x (* i i)]] x) ⇒ (1 4 9 16 25) (for [i [1 2 3 4 5] :when (even? i)] (* i i)) ⇒ (4 16) (for [i '(1 2 3 a b c 4 5 6) :while (number? i)] (* i i)) ⇒ (1 4 9) (for [i [1 2 3 4 5] :let [x (* i i)] :when (odd? x)] [i x]) ⇒ ([1 1] [3 9] [5 25]) (for [x '(a b) y [1 2 3]] [x y]) ⇒ ([a 1] [a 2] [a 3] [b 1] [b 2] [b 3]) |
| (map f coll & colls) | Returns a lazy sequence consisting of the result of applying f to the set of first items of each coll, followed by applying f to the set of second items in each coll, and so on until any one of the colls is exhausted. Any remaining items in other colls are ignored. Function f should accept n arguments, where n is the total number of colls. |
(map inc [10 -1 0 5 -4]) ⇒ (11 0 1 6 -3) (map dec ()) ⇒ () (map + [1 2 3 4 5 6] [10 20 30] [100 200 300 400]) ⇒ (111 222 333) (map pos? [4 -10 8 0 -5]) ⇒ (true false true false false) |
| (mapcat f & colls) |
Returns the result of applying concat to the result of applying map to f and colls. Thus, function f should return a collection.
|
(mapcat rest '((1 2 3 4) (5 6 7) (8 9) (10))) ⇒ (2 3 4 6 7 9) (mapcat reverse '((1 2 3) (a b c) (:x :y))) ⇒ (3 2 1 c b a :y :x) (mapcat #(list % 'x) '(1 2 3 4)) ⇒ (1 x 2 x 3 x 4 x) |
| (map-indexed f coll) | Returns a lazy sequence consisting of the result of applying f to 0 and the first item of coll, followed by applying f to 1 and the second item in coll, and so on, until coll is exhausted. Thus, function f should accept 2 arguments, index and item. |
(map-indexed vector '(a b c d)) ⇒ ([0 a] [1 b] [2 c] [3 d]) (map-indexed + [1 1 1 1]) ⇒ (1 2 3 4) |
|
(reduce f coll) (reduce f val coll) |
f should be a function of two arguments. If val is not supplied, returns the result of applying f to the first two items in coll, then applying f to that result and the third item, and so on. If coll contains no items, f must accept no arguments as well, and reduce returns the result of calling f with no arguments. If coll has only one item, it is returned and f is not called. If val is supplied, returns the result of applying f to val and the first item in coll, then applying f to that result and the second item, and so on. If coll contains no items, returns val and f is not called. |
(reduce + [1 2 3 4 5]) ⇒ 15 (reduce + []) ⇒ 0 (reduce + [42]) ⇒ 42 (reduce * 10 [1 2 3]) ⇒ 60 (reduce * 10 []) ⇒ 10 (reduce conj () [1 2 3]) ⇒ (3 2 1) |
|
(sort coll) (sort comp coll) |
Returns a sorted sequence of the items in coll.
comp is a function that takes two arguments: x and y. It should return a negative number, zero, or a positive number when x is logically "less than", "equal to", or "greater than" y, respectively. If comp is not supplied, the |
(sort [4 6 1 10 9 3 2 8 5 7]) ⇒ (1 2 3 4 5 6 7 8 9 10) (sort ()) ⇒ () (sort #(- %2 %1) [4 6 1 10 9 3 2 8 5 7]) ⇒ (10 9 8 7 6 5 4 3 2 1) |
|
(sort-by keyfn coll) (sort-by keyfn comp coll) |
Returns a sorted sequence of the items in coll, where the sort order is determined by comparing (keyfn item).
comp is a function as described in |
(sort-by #(Math/abs %) [2 5 -2 3 0 -1 4 1]) ⇒ (0 -1 1 2 -2 3 4 5) (sort-by #(Math/abs %) #(- %2 %1) [2 5 -2 3 0 -1 4 1]) ⇒ (5 4 3 2 -2 -1 1 0) (sort-by :grade [{:name "Mary" :grade 92} {:name "John" :grade 78} {:name "Jane" :grade 85}]) ⇒ ({:name "John", :grade 78} {:name "Jane", :grade 85} {:name "Mary", :grade 92}) |
Creating Lazy Sequences
| Macro | Description | Examples |
|---|---|---|
| (lazy-seq & body) |
Takes a body of expressions that returns a sequence or nil, and yields a seqable object that will invoke body only the first time seq is called, and will cache the result and return it on all subsequent seq calls.
|
(defn f [n] (lazy-seq (cons n (f n)))) (take 10 (f 0)) ⇒ (0 0 0 0 0 0 0 0 0 0) |
| (lazy-cat & colls) |
Expands to code which yields a lazy sequence of the concatenation of the supplied colls. Each coll expression is not evaluated until it is needed.
(lazy-cat a b c) ≡ |
(def x (lazy-cat (range 5) (repeat 0))) (take 10 x) ⇒ (0 1 2 3 4 0 0 0 0 0) |
Side Effect Oriented Operations
| Function/Macro | Description | Examples |
|---|---|---|
| (doall s) |
When lazy sequences are produced via functions that have
side effects, any effects other than those needed to produce the first
element in the seq s do not occur until the seq is consumed. doall
can be used to force any effects. Walks through the successive nexts of
the seq, retains the head and returns it, thus causing the entire seq
to reside in memory at one time.
|
(def m (map #(println %) (range 5))) (doall m) ;;; Prints: 0 1 2 3 4 ⇒ (nil nil nil nil nil) |
| (dorun s) |
When lazy sequences are produced via functions that have
side effects, any effects other than those needed to produce the first
element in the seq s do not occur until the seq is consumed. dorun can be used to force any effects. Walks through the successive nexts of the seq, does not retain the head and returns nil.
|
(def m (map #(println %) (range 5))) (dorun m) ;;; Prints: 0 1 2 3 4 ⇒ nil |
| (doseq seq-exprs body-expr) |
Repeatedly executes body-expr (presumably for side-effects) with bindings and filtering as provided by the for macro. Does not retain the head of the seq. Returns nil.
|
(doseq [i (range 5)] (println i)) ;;; Prints: 0 1 2 3 4 ⇒ nil |