0
# Data Structures and Collections
1

2
Immutable, persistent data structures including vectors, maps, sets, and their manipulation functions. Clojure's data structures are designed for functional programming with structural sharing for efficiency.
3

4
## Capabilities
5

6
### Map Operations
7

8
Functions for working with key-value mappings.
9

10
```clojure { .api }
11
(get map key)
12
(get map key not-found)
13
;; Returns value for key, or not-found/nil if key not present
14
;; Returns: Object
15

16
(get-in m ks)
17
(get-in m ks not-found)
18
;; Returns value in nested associative structure
19
;; ks is sequence of keys: (get-in {:a {:b 2}} [:a :b]) => 2
20
;; Returns: Object
21

22
(assoc map key val)
23
(assoc map key val & kvs)
24
;; Returns new map with key-value associations
25
;; Returns: clojure.lang.IPersistentMap
26

27
(assoc-in m ks v)
28
;; Returns new nested structure with value at key sequence
29
;; Returns: clojure.lang.IPersistentMap
30

31
(dissoc map & keys)
32
;; Returns new map without specified keys
33
;; Returns: clojure.lang.IPersistentMap
34

35
(update m k f & args)
36
;; Returns new map with (f (get m k) args) at key k
37
;; Returns: clojure.lang.IPersistentMap
38

39
(update-in m ks f & args)  
40
;; Returns new nested structure with f applied at key sequence
41
;; Returns: clojure.lang.IPersistentMap
42

43
(merge & maps)
44
;; Returns map with all key-value pairs from maps (right wins)
45
;; Returns: clojure.lang.IPersistentMap
46

47
(merge-with f & maps)
48
;; Like merge but uses f to combine values for duplicate keys
49
;; Returns: clojure.lang.IPersistentMap
50

51
(select-keys map keyseq)
52
;; Returns map containing only entries with keys in keyseq
53
;; Returns: clojure.lang.IPersistentMap
54

55
(keys map)
56
;; Returns sequence of map's keys
57
;; Returns: clojure.lang.ISeq
58

59
(vals map)
60
;; Returns sequence of map's values  
61
;; Returns: clojure.lang.ISeq
62

63
(find map key)
64
;; Returns MapEntry for key, or nil if not found
65
;; Returns: clojure.lang.MapEntry or nil
66

67
(contains? coll key)
68
;; Returns true if key is present in collection
69
;; For maps, tests for key presence; for vectors, tests valid indices
70
;; Returns: boolean
71
```
72

73
### Vector Operations
74

75
Functions specific to vectors (indexed collections).
76

77
```clojure { .api }
78
(vec coll)
79
;; Creates vector from collection
80
;; Returns: clojure.lang.IPersistentVector
81

82
(subvec v start)
83
(subvec v start end)
84
;; Returns subvector from start (inclusive) to end (exclusive)
85
;; Returns: clojure.lang.IPersistentVector
86

87
(rseq rev)
88
;; Returns reverse sequence of reversible collection
89
;; Works efficiently with vectors  
90
;; Returns: clojure.lang.ISeq
91

92
(peek coll)
93
;; Returns last item of vector, first item of list/seq
94
;; Returns: Object
95

96
(pop coll)
97
;; Returns new collection without last item (vector) or first item (list)
98
;; Returns: same type as coll
99
```
100

101
### Set Operations
102

103
Functions for working with sets (collections of unique values).
104

105
```clojure { .api }
106
(disj set & keys)
107
;; Returns new set without specified keys
108
;; Returns: clojure.lang.IPersistentSet
109

110
(clojure.set/union & sets)
111
;; Returns set that is union of input sets
112
;; Returns: clojure.lang.IPersistentSet
113

114
(clojure.set/intersection & sets)
115
;; Returns set that is intersection of input sets  
116
;; Returns: clojure.lang.IPersistentSet
117

118
(clojure.set/difference s1 & sets)
119
;; Returns set that is s1 without elements of remaining sets
120
;; Returns: clojure.lang.IPersistentSet
121

122
(clojure.set/subset? set1 set2)
123
;; Returns true if set1 is subset of set2
124
;; Returns: boolean
125

126
(clojure.set/superset? set1 set2)
127
;; Returns true if set1 is superset of set2
128
;; Returns: boolean
129

130
(clojure.set/select pred set)
131
;; Returns set of elements for which pred is true
132
;; Returns: clojure.lang.IPersistentSet
133

134
(clojure.set/project rel keys)
135
;; Returns set of maps with only specified keys from relation
136
;; Returns: clojure.lang.IPersistentSet
137

138
(clojure.set/rename-keys map kmap)
139
;; Returns map with keys renamed according to kmap
140
;; Returns: clojure.lang.IPersistentMap
141

142
(clojure.set/rename rel kmap)
143
;; Returns set of maps with keys renamed in each map
144
;; Returns: clojure.lang.IPersistentSet
145

146
(clojure.set/index rel keys)
147
;; Returns map indexed by specified keys from relation
148
;; Returns: clojure.lang.IPersistentMap
149

150
(clojure.set/map-invert m)
151
;; Returns map with keys and values swapped
152
;; Returns: clojure.lang.IPersistentMap
153

154
(clojure.set/join rel1 rel2)
155
(clojure.set/join rel1 rel2 km)
156
;; Returns natural join of relations, optionally with key map
157
;; Returns: clojure.lang.IPersistentSet
158
```
159

160
### Collection Conversion
161

162
Functions for converting between collection types.
163

164
```clojure { .api }
165
(into to from)
166
(into to xform from)
167
;; Returns new collection with from items added to to
168
;; Optional transducer xform transforms items during insertion
169
;; Returns: same type as to
170

171
(vec coll)
172
;; Returns vector of collection items
173
;; Returns: clojure.lang.IPersistentVector
174

175
(set coll)
176
;; Returns set of collection items  
177
;; Returns: clojure.lang.IPersistentSet
178

179
(seq coll)
180
;; Returns seq of collection items, nil if empty
181
;; Returns: clojure.lang.ISeq or nil
182

183
(lazy-seq & body)
184
;; Creates lazy sequence from body
185
;; Body should return nil or sequence
186
;; Returns: clojure.lang.LazySeq
187
```
188

189
### Collection Predicates
190

191
Functions for testing collection properties and types.
192

193
```clojure { .api }
194
(empty? coll)
195
;; Returns true if collection has no items
196
;; Returns: boolean
197

198
(not-empty coll)
199
;; Returns coll if not empty, nil otherwise  
200
;; Returns: coll or nil
201

202
(distinct? & xs)
203
;; Returns true if no two arguments are equal
204
;; Returns: boolean
205

206
(sorted? coll)
207
;; Returns true if collection is sorted
208
;; Returns: boolean
209

210
(reversible? coll)
211
;; Returns true if collection implements Reversible
212
;; Returns: boolean
213

214
(indexed? coll)
215
;; Returns true if collection supports efficient random access
216
;; Returns: boolean
217
```
218

219
### Sequence Creation
220

221
Functions for creating sequences and ranges.
222

223
```clojure { .api }
224
(range)
225
(range end)
226
(range start end)  
227
(range start end step)
228
;; Returns lazy sequence of numbers
229
;; Default: infinite from 0, or 0 to end, or start to end by step
230
;; Returns: clojure.lang.LongRange or clojure.lang.LazySeq
231

232
(repeat x)
233
(repeat n x)
234
;; Returns lazy infinite sequence of x, or sequence of n x's
235
;; Returns: clojure.lang.Repeat or clojure.lang.LazySeq
236

237
(repeatedly f)
238
(repeatedly n f)
239
;; Returns lazy sequence of calls to f (no args)
240
;; Returns: clojure.lang.LazySeq
241

242
(cycle coll)
243
;; Returns lazy infinite sequence that cycles through coll
244
;; Returns: clojure.lang.LazySeq
245

246
(iterate f x)
247
;; Returns lazy infinite sequence of x, (f x), (f (f x)), ...
248
;; Returns: clojure.lang.LazySeq
249
```
250

251
### Destructuring
252

253
Clojure supports destructuring in let, fn parameters, and other binding forms.
254

255
```clojure { .api }
256
;; Vector destructuring
257
[a b c] ; binds first three elements
258
[a b & rest] ; binds first two, rest gets remaining as seq
259
[a _ c] ; underscore ignores second element  
260
[a b :as all] ; :as binds entire vector
261

262
;; Map destructuring  
263
{:keys [name age]} ; binds name and age from map keys
264
{name :name, age :age} ; explicit key mapping
265
{:keys [name age] :as person} ; :as binds entire map
266
{:keys [name age] :or {age 0}} ; :or provides defaults
267
```
268

269
**Usage Examples:**
270

271
```clojure
272
;; Map operations
273
(def person {:name "Alice" :age 30 :city "NYC"})
274
(get person :name)                    ; => "Alice"  
275
(assoc person :email "alice@ex.com")  ; => {:name "Alice" :age 30 :city "NYC" :email "alice@ex.com"}
276
(dissoc person :city)                 ; => {:name "Alice" :age 30}
277
(update person :age inc)              ; => {:name "Alice" :age 31 :city "NYC"}
278

279
;; Nested operations
280
(def data {:users [{:name "Alice" :age 30} {:name "Bob" :age 25}]})
281
(get-in data [:users 0 :name])        ; => "Alice"
282
(assoc-in data [:users 0 :age] 31)    ; => {:users [{:name "Alice" :age 31} {:name "Bob" :age 25}]}
283

284
;; Vector operations  
285
(def v [1 2 3 4 5])
286
(peek v)        ; => 5
287
(pop v)         ; => [1 2 3 4]
288
(subvec v 1 3)  ; => [2 3]
289

290
;; Set operations
291
(def s1 #{1 2 3})
292
(def s2 #{3 4 5})
293
(clojure.set/union s1 s2)        ; => #{1 2 3 4 5}
294
(clojure.set/intersection s1 s2) ; => #{3}
295

296
;; Collection conversion
297
(into [] (range 5))   ; => [0 1 2 3 4]
298
(into #{} [1 2 2 3])  ; => #{1 2 3} 
299
(vec (range 5))       ; => [0 1 2 3 4]
300

301
;; Destructuring
302
(let [[a b c] [1 2 3 4 5]]
303
  [a b c])            ; => [1 2 3]
304

305
(let [{:keys [name age]} {:name "Alice" :age 30}]
306
  [name age])         ; => ["Alice" 30]
307

308
;; Sequence creation
309
(take 5 (range))           ; => (0 1 2 3 4)
310
(take 3 (repeat "hello"))  ; => ("hello" "hello" "hello")  
311
(take 5 (cycle [1 2]))     ; => (1 2 1 2 1)
312
(take 4 (iterate inc 0))   ; => (0 1 2 3)
313
```