Clojure Collection API
All of the Clojure collections are immutable and persistent. In particular, the Clojure collections support efficient creation of "modified" versions, by utilizing structural sharing, and make all of their performance bound guarantees for persistent use. The collections are efficient and inherently thread-safe. Collections are represented by abstractions, and there may be one or more concrete realizations. In particular, since "modification" operations yield new collections, the new collection might not have the same concrete type as the source collection, but will have the same logical (interface) type.
All the collections support count for getting the size of the collection and seq to get a sequence that can be used to traverse through all the items in the collection (see the Clojure Sequence API), though their specific behavior is slightly different for different types of collections.
Collection Predicates
| Function | Description | Examples |
|---|---|---|
| (coll? x) |
Returns true if x is a collection (i.e. it implements the clojure.lang.IPersistentCollection interface), otherwise returns false.
|
(coll? [1 2 3]) ⇒ true (coll? '(a b c)) ⇒ true (coll? ()) ⇒ true (coll? {:a 1, :b 2}) ⇒ true (coll? #{1 2 3}) ⇒ true (coll? nil) ⇒ false (coll? 42) ⇒ false |
| (list? x) |
Returns true if x is a list (i.e. it implements the clojure.lang.IPersistentList interface), otherwise returns false.
|
(list? '(a b c)) ⇒ true (list? ()) ⇒ true (list? [1 2 3]) ⇒ false (list? {:a 1 :b 2}) ⇒ false (list? #{1 2 3}) ⇒ false (list? nil) ⇒ false (list? 42) ⇒ false |
| (map? x) |
Returns true if x is a map (i.e. it implements the clojure.lang.IPersistentMap interface), otherwise returns false.
|
(map? '(a b c)) ⇒ false (map? [1 2 3]) ⇒ false (map? {:a 1 :b 2}) ⇒ true (map? {}) ⇒ true (map? #{1 2 3}) ⇒ false (map? nil) ⇒ false (map? 42) ⇒ false |
| (set? x) |
Returns true if x is a set (i.e. it implements the clojure.lang.IPersistentSet interface), otherwise returns false.
|
(set? '(a b c)) ⇒ false (set? [1 2 3]) ⇒ false (set? {:a 1 :b 2}) false (set? #{1 2 3}) ⇒ true (set? #{}) ⇒ true (set? nil) ⇒ false (set? 42) ⇒ false |
| (vector? x) |
Returns true if x is a vector (i.e. it implements the clojure.lang.IPersistentVector interface), otherwise returns false.
|
(vector? '(a b c)) ⇒ false (vector? [1 2 3]) ⇒ true (vector? []) ⇒ true (vector? {:a 1 :b 2}) ⇒ false (vector? #{1 2 3}) ⇒ false (vector? nil) ⇒ false (vector? 42) ⇒ false |
Lists
A Clojure list is a sequential collection implemented as a singly-linked list. Lists support directly all the sequence functions.
| Function | Description | Examples |
|---|---|---|
|
(conj lst item & items) |
Conjoin. Returns a new list with all the items added to the front of lst. |
(conj '(1 2 3) 4) ⇒ (4 1 2 3) (conj '(1 2 3) 4 5 6) ⇒ (6 5 4 1 2 3) (conj '() 1) ⇒ (1) (conj nil 1) ⇒ (1) |
| (list & items) | Creates a new list containing items. |
(list) ⇒ () (list 1 2 3) ⇒ (1 2 3) (list 1 [2 3] 4) ⇒ (1 [2 3] 4) |
| (list* arg & args) |
Similar to list, except that it expects its last argument to be a collection on which to prepend its other arguments (if any).
|
(list* '(a b c)) ⇒ (a b c) (list* [1 2 3]) ⇒ (1 2 3) (list* 4 5 6 [1 2 3]) ⇒ (4 5 6 1 2 3) (list* 4 5 6 nil) ⇒ (4 5 6) (list* 4 5 6 {:a 1 :b 2}) ⇒ (4 5 6 [:a 1] [:b 2]) (list* 4 5 6 #{1 2 3}) ⇒ (4 5 6 1 2 3) |
Queues
A Clojure queue is an efficient FIFO (First-In, First-Out)
collection. Clojure doesn’t have a queue reader literal. To create a
queue you must use the clojure.lang.PersistentQueue/EMPTY static member.
| Function | Description | Examples |
|---|---|---|
|
(conj q item & items) |
Conjoin. Returns a new queue with all the items added to the end of q. |
(seq (conj clojure.lang.PersistentQueue/EMPTY 1 2 3 4)) ⇒ (1 2 3 4) |
| (peek q) |
Returns the item at the front of q. Returns nil if q is empty.
|
(peek (conj clojure.lang.PersistentQueue/EMPTY 1 2 3 4)) ⇒ 1 (peek clojure.lang.PersistentQueue/EMPTY) ⇒ nil |
| (pop q) | Returns a new queue without the first item of q. Returns q if q is empty. |
(seq (pop (conj clojure.lang.PersistentQueue/EMPTY 1 2 3 4))) ⇒ (2 3 4) |
Vectors
A vector is a collection of values indexed by contiguous integers. They are similar to arrays in other languages.
Vectors can be used as functions (i.e. they implement the clojure.lang.IFn interface). If v is a vector, then:
(v index) ≡ (nth v index)
| Function | Description | Examples |
|---|---|---|
|
(assoc v index val) (assoc v index val & ivs) |
Associate. Returns a new vector based on v but containing val at index. index must be less or equal to the total amount of items in v, otherwise throws an index out of bounds exception. |
(assoc '[a b c] 0 'x) ⇒ [x b c] (assoc '[a b c] 3 'x) ⇒ [a b c x] (assoc '[a b c] 0 'x 3 'y 4 'z) ⇒ [x b c y z] (assoc [] 0 'x) ⇒ [x] |
|
(conj v item & items) |
Conjoin. Returns a new vector with all the items added at the end of v. |
(conj [1 2 3] 4) ⇒ [1 2 3 4] (conj [1 2 3] 4 5 6) ⇒ [1 2 3 4 5 6] (conj [] 1) ⇒ [1] |
|
(get v index) (get v index not-found) |
Returns the value of v at index. Returns not-found if index is out of bounds, or nil if not provided. Similar to nth, except that it doesn't throw an exception when index is out of bounds.
|
(get '[a b c] 0) ⇒ a (get '[a b c] 2) ⇒ c (get '[a b c] 3) ⇒ nil (get '[a b c] 3 'oops) ⇒ oops (get '[a b c] -1) ⇒ nil |
|
(nth v index) (nth v index not-found) |
Returns the value in v 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 v) |
Returns the last element of v. Returns nil if v is empty.
|
(peek [3 2 1])) ⇒ 1 (peek []) ⇒ nil |
| (pop v) | Returns a new vector without the last item of v. Throws an exception when v is empty. |
(pop [3 2 1]) ⇒ [3 2] (pop [3]) ⇒ [] |
|
(subvec v start) (subvec v start end) |
Returns a new vector containing the items in v from start (inclusive) to end (exclusive). If end is not supplied, defaults to the size of v. |
(subvec '[a b c d] 1) ⇒ [b c d] (subvec '[a b c d] 1 3) ⇒ [b c] (subvec '[a b c d] 0 2) ⇒ [a b] |
| (vec coll) | Creates a new vector containing the contents of coll. |
(vec '(a b c)) ⇒ [a b c] (vec [1 2 3]) ⇒ [1 2 3] (vec {:a 1 :b 2}) ⇒ [[:a 1] [:b 2]] (vec #{1 2 3}) ⇒ [1 2 3] (vec nil) ⇒ [] |
| (vector & args) | Creates a new vector containing all the args. |
(vector 1 2 3) ⇒ [1 2 3] (vector) ⇒ [] (vector nil) ⇒ [nil] |
Maps
A map is a collection that maps keys to values. Two different
map types are provided — hashed and sorted. Hash maps require keys that
are correctly supported by the hash and = functions. Sorted maps require keys that are supported by the compare function. seq applied to a map returns a sequence of map entries, which are key/value pairs.
Maps can be used as functions (i.e. they implement the clojure.lang.IFn interface). If m is a map, then:
(m key) ≡ (get m key)
(m key not-found) ≡ (get m key not-found)
| Function | Description | Examples |
|---|---|---|
|
(assoc m key val) (assoc m key val & kvs) |
Associate. Returns a new map with the same elements and of the same type (hashed/sorted) as m, but containing the key/val mappings. |
(assoc {:a 1 :b 2} :a 0) ⇒ {:a 0, :b 2} (assoc {:a 1 :b 2} :c 0) ⇒ {:c 0, :a 1, :b 2} (assoc {:a 1 :b 2} :c 3 :a 4) ⇒ {:c 3, :a 4, :b 2} (assoc {} :a 1) ⇒ {:a 1} |
|
(conj m item & items) |
Conjoin. Returns a new map with all the items added to m. It expects one or more maps as the items, and returns a new map which is the old map plus the entries from the new ones, which may overwrite entries of the old. It also accepts vectors of two items (key and value). The exact place where the items are added depends on the concrete type of m (hashed or sorted). |
(conj {:a 1 :b 2 :c 3} {:d 4}) ⇒ {:d 4, :a 1, :b 2, :c 3} (conj {:a 1 :b 2 :c 3} {:d 4} {:e 5} {:a 10 :f 6}) ⇒ {:f 6, :e 5, :d 4, :a 10, :b 2, :c 3} (conj {:a 1 :b 2 :c 3} [:d 4] [:e 5]) ⇒ {:e 5, :d 4, :a 1, :b 2, :c 3} |
| (contains? m key) |
Returns true if key is present in m, otherwise returns false.
|
(contains? {:a 1 :b 2 :c 3} :b) ⇒ true (contains? {:a 1 :b 2 :c 3} :d) ⇒ false (contains? {} :a) ⇒ false |
|
(dissoc m key) (dissoc m key & keys) |
Dissociate. Returns a new map of the same type (hashed/sorted) as m, but not containing the mappings for keys. |
(dissoc {:a 1 :b 2} :a) ⇒ {:b 2} (dissoc {:a 1 :b 2} :a :b) ⇒ {} (dissoc {:a 1 :b 2} :c) ⇒ {:a 1, :b 2} (dissoc {} :a) ⇒ {} |
| (frequencies coll) | Returns a map from distinct items in coll mapped to the number of times they appear. |
(frequencies [:a :b :a :c :b :a]) ⇒ {:a 3, :b 2, :c 1} (frequencies []) ⇒ {} |
|
(get m key) (get m key not-found) |
Returns the value contained in m mapped to key. Returns nil or not-found if key is not present.
|
(get {:a 1 :b 2} :a) ⇒ 1 (get {:a 1 :b 2} :c) ⇒ nil (get {:a 1 :b 2} :c 'oops) ⇒ oops |
| (hash-map & keyvals) | Returns a new hash map with the supplied mappings in keyvals. |
(hash-map) ⇒ {} (hash-map :x 1 :y 2 :z 3 :w 4) ⇒ {:z 3, :y 2, :x 1, :w 4} |
| (keys m) |
Returns a sequence of the keys contained in m. Returns nil if m is empty.
|
(keys {:a 1 :b 2 :c 3}) ⇒ (:a :b :c) (keys {}) ⇒ nil |
| (merge & ms) | Returns a new map that consists of the rest of ms conjoined into the first. If a key occurs in more than one map, the mapping from the latter (left-to-right) will be the mapping in the result. |
(merge {:a 1 :b 2} {:c 3 :d 4}) ⇒ {:d 4, :c 3, :a 1, :b 2} (merge {:a 1 :b 2} {:a 3 :d 4} {:a 5 :e 6}) ⇒ {:e 6, :d 4, :a 5, :b 2} |
| (select-keys m keyseq) | Returns a new map containing only those entries in m whose keys are in keyseq. |
(select-keys {:a 1 :b 2 :c 3} [:a :c]) ⇒ {:c 3, :a 1} (select-keys {:a 1 :b 2 :c 3} [:d :e]) ⇒ {} (select-keys {} [:a]) ⇒ {} |
| (sorted-map & keyvals) | Returns a new sorted map with the supplied mappings in keyvals. |
(sorted-map) ⇒ {} (sorted-map :x 1 :y 2 :z 3 :w 4) ⇒ {:w 4, :x 1, :y 2, :z 3} |
| (vals m) |
Returns a sequence of the values contained in m. Returns nil if m is empty.
|
(vals {:a 1 :b 2 :c 3}) ⇒ (1 2 3) (vals {}) ⇒ nil |
| (zipmap keys vals) | Returns a new map with the keys mapped by position to the corresponding vals. |
(zipmap [:a :b :c] [1 2 3]) ⇒ {:c 3, :b 2, :a 1} (zipmap [:a :b :c] [1 2 3 4 5]) ⇒ {:c 3, :b 2, :a 1} (zipmap [] [1 2 3 4 5]) ⇒ {} |
Sets
Sets are collections of unique values without any regard to
their order. Two different set types are provided — hashed and sorted.
Hash sets require keys that are correctly supported by the hash and = functions. Sorted sets require keys that are supported by the compare function.
Sets can be used as functions (i.e. they implement the clojure.lang.IFn interface). If s is a set, then:
(s key) ≡ (get s key)
| Function | Description | Examples |
|---|---|---|
|
(conj s item & items) |
Conjoin. Returns a new set with all the items added to s. The exact place where the items are added depends on the concrete type of s (hashed or sorted). |
(conj #{:a :b :c} :d) ⇒ #{:a :c :b :d} (conj #{:a :b :c} :d :e :f) ⇒ #{:a :c :b :f :d :e} (conj #{} :a) ⇒ #{:a} |
| (contains? s key) |
Returns true if key is present in s, otherwise returns false.
|
(contains? #{:a :b :c :d} :b) ⇒ true (contains? #{:a :b :c :d} :e) ⇒ false (contains? #{} :a) ⇒ false |
|
(disj s) (disj s key & keys) |
Disjoin. Returns a new set of the same type (hashed/sorted) as s, but not containing keys. |
(disj #{:a :b :c :d} :b) ⇒ #{:a :c :d} (disj #{:a :b :c :d}) ⇒ #{:a :c :b :d} (disj #{:a :b :c :d} :e) ⇒ #{:a :c :b :d} (disj #{:a :b :c :d} :a :c :d :e) ⇒ #{:b} (disj #{} :a) ⇒ #{} |
|
(get s key) (get s key not-found) |
Returns key if it's contained in s. Returns nil or not-found if key is not present.
|
(get #{:a :b :c} :b) ⇒ :b (get #{:a :b :c} :d) ⇒ nil (get #{:a :b :c} :d, 'oops) ⇒ oops |
| (hash-set & keys) | Returns a new hash set with the supplied keys. |
(hash-set) ⇒ #{} (hash-set :x :y :z :w) ⇒ #{:z :y :x :w} |
| (set coll) | Returns a set of the distinct elements contained in coll. |
(set [1 3 4 1 2 5 1 4]) ⇒ #{1 2 3 4 5} (set {:a 1 :b 2 :c 3}) ⇒ #{[:b 2] [:c 3] [:a 1]} (set []) ⇒ #{} |
| (sorted-set & keys) | Returns a new sorted set with the supplied keys. |
(sorted-set) ⇒ #{} (sorted-set :x :y :z :w) ⇒ #{:w :x :y :z} |
To use the set functions from the following table, first you need to load and correctly refer to the clojure.set namespace. For example:
| Function | Description | Examples |
|---|---|---|
| (difference s & sets) | Returns a new set that is s without the elements of the remaining sets. |
(difference #{:a :b :c} #{:a :c}) ⇒ #{:b} (difference #{:a :b :c} #{:a :c :d}) ⇒ #{:b} (difference #{:a :b :c} #{:a} #{:c :d} #{:e :f}) ⇒ #{:b} (difference #{} #{:a :b :c}) ⇒ #{} |
| (intersection s & sets) | Returns a new set that is the intersection of the input sets. |
(intersection #{:a :b :c} #{:b :d :e}) ⇒ #{:b} (intersection #{:a :b :c} #{:b :c :d} #{:c :e}) ⇒ #{:c} (intersection #{:a :b :c} #{:d :e} #{:f}) ⇒ #{} (intersection #{:a :b}) ⇒ #{:a :b} |
| (subset? s1 s2) |
Returns true if s1 is a subset of s2, otherwise returns false.
|
(subset? #{:b :c} #{:a :b :c :d}) ⇒ true (subset? #{} #{:a :b :c :d}) ⇒ true (subset? #{:a :b} #{:b :a}) ⇒ true (subset? #{:a :b :c :d} #{:a :b}) ⇒ false |
| (superset? s1 s2) |
Returns true if s1 is a superset of s2, otherwise returns false.
|
(superset? #{:a :b :c :d} #{:b :c}) ⇒ true (superset? #{:a :b :c :d} #{}) ⇒ true (superset? #{:a :b} #{:b :a}) ⇒ true (superset? #{:a :b} #{:a :b :c :d}) ⇒ false |
| (union & sets) | Returns a new set that is the union of all the input sets. |
(union #{:a :b} #{:a :c}) ⇒ #{:a :c :b} (union #{:a} #{:b :c} #{:c :d :e}) ⇒ #{:a :c :b :d :e} (union) ⇒ #{} |
Collection Performance Guarantees
As published in Clojure Performance Guarantees.
| Lazy Seq | List | Queue | Vector | Hash Map | Sorted Map | Hash Set | Sorted Set | |
|---|---|---|---|---|---|---|---|---|
| assoc | — | — | — | O(log32 n) | O(log32 n) | O(log2 n) | — | — |
| conj | O(1) | O(1) | O(1) | O(1) | O(log32 n) | O(log2 n) | O(log32 n) | O(log2 n) |
| count | O(n) | O(1) | O(1) | O(1) | O(1) | O(1) | O(1) | O(1) |
| disj | — | — | — | — | — | — | O(log32 n) | O(log2 n) |
| dissoc | — | — | — | — | O(log32 n) | O(log2 n) | — | — |
| get | — | — | — | O(log32 n) | O(log32 n) | O(log2 n) | O(log32 n) | O(log2 n) |
| nth | O(n) | O(n) | O(n) | O(log32 n) | — | — | — | — |
| peek | O(1) | O(1) | O(1) | O(1) | — | — | — | — |
| pop | O(1) | O(1) | O(1) | O(1) | — | — | — | — |