0
# Observable Filtering
1

2
Operators for filtering observable sequences including filter, take, skip, distinct, and debounce operations.
3

4
## Capabilities
5

6
### Filter/Where
7

8
Filters elements based on a predicate function.
9

10
```javascript { .api }
11
/**
12
 * Filters elements based on a predicate function
13
 * @param {function} predicate - Function to test each element
14
 * @param {*} [thisArg] - Object to use as this when executing predicate
15
 * @returns {Observable} Observable sequence containing filtered elements
16
 */
17
observable.filter = function(predicate, thisArg);
18
observable.where = function(predicate, thisArg); // Alias for filter
19
```
20

21
**Usage Example:**
22

23
```javascript
24
var source = Rx.Observable.range(1, 10);
25
var evens = source.filter(function(x) { return x % 2 === 0; });
26
// Emits: 2, 4, 6, 8, 10
27
```
28

29
### Take
30

31
Takes the first specified number of elements.
32

33
```javascript { .api }
34
/**
35
 * Takes the first count elements from an observable sequence
36
 * @param {number} count - Number of elements to take
37
 * @param {Scheduler} [scheduler] - Scheduler to use for the subscription
38
 * @returns {Observable} Observable sequence containing the first count elements
39
 */
40
observable.take = function(count, scheduler);
41
```
42

43
### Take While
44

45
Takes elements while a predicate is true.
46

47
```javascript { .api }
48
/**
49
 * Takes elements from start of sequence while predicate is true
50
 * @param {function} predicate - Function to test each element
51
 * @param {*} [thisArg] - Object to use as this when executing predicate
52
 * @returns {Observable} Observable sequence containing elements while predicate is true
53
 */
54
observable.takeWhile = function(predicate, thisArg);
55
```
56

57
### Take Last
58

59
Takes the last specified number of elements.
60

61
```javascript { .api }
62
/**
63
 * Takes the last count elements from an observable sequence
64
 * @param {number} count - Number of elements to take from the end
65
 * @returns {Observable} Observable sequence containing the last count elements
66
 */
67
observable.takeLast = function(count);
68
```
69

70
### Take Last Buffer
71

72
Takes the last elements and returns them as an array.
73

74
```javascript { .api }
75
/**
76
 * Takes the last count elements and returns them as a single array
77
 * @param {number} count - Number of elements to take from the end
78
 * @returns {Observable} Observable sequence containing array of last count elements
79
 */
80
observable.takeLastBuffer = function(count);
81
```
82

83
### Take Until
84

85
Takes elements until another observable emits.
86

87
```javascript { .api }
88
/**
89
 * Takes elements until the other observable sequence emits a value
90
 * @param {Observable} other - Observable sequence that terminates propagation
91
 * @returns {Observable} Observable sequence taking elements until other emits
92
 */
93
observable.takeUntil = function(other);
94
```
95

96
**Usage Example:**
97

98
```javascript
99
var source = Rx.Observable.interval(100);
100
var stopSignal = Rx.Observable.timer(500);
101
var result = source.takeUntil(stopSignal);
102
// Emits: 0, 1, 2, 3, 4 (stops after 500ms)
103
```
104

105
### Skip
106

107
Skips the first specified number of elements.
108

109
```javascript { .api }
110
/**
111
 * Skips the first count elements from an observable sequence
112
 * @param {number} count - Number of elements to skip
113
 * @returns {Observable} Observable sequence skipping the first count elements
114
 */
115
observable.skip = function(count);
116
```
117

118
### Skip While
119

120
Skips elements while a predicate is true.
121

122
```javascript { .api }
123
/**
124
 * Skips elements from start of sequence while predicate is true
125
 * @param {function} predicate - Function to test each element
126
 * @param {*} [thisArg] - Object to use as this when executing predicate
127
 * @returns {Observable} Observable sequence skipping elements while predicate is true
128
 */
129
observable.skipWhile = function(predicate, thisArg);
130
```
131

132
### Skip Last
133

134
Skips the last specified number of elements.
135

136
```javascript { .api }
137
/**
138
 * Skips the last count elements from an observable sequence
139
 * @param {number} count - Number of elements to skip from the end
140
 * @returns {Observable} Observable sequence skipping the last count elements
141
 */
142
observable.skipLast = function(count);
143
```
144

145
### Skip Until
146

147
Skips elements until another observable emits.
148

149
```javascript { .api }
150
/**
151
 * Skips elements until the other observable sequence emits a value
152
 * @param {Observable} other - Observable sequence that starts propagation
153
 * @returns {Observable} Observable sequence skipping elements until other emits
154
 */
155
observable.skipUntil = function(other);
156
```
157

158
### Distinct
159

160
Filters out duplicate values from the sequence.
161

162
```javascript { .api }
163
/**
164
 * Returns distinct elements from an observable sequence
165
 * @param {function} [keySelector] - Function to compute comparison key for each element
166
 * @param {function} [comparer] - Function to compare keys for equality
167
 * @returns {Observable} Observable sequence containing distinct elements
168
 */
169
observable.distinct = function(keySelector, comparer);
170
```
171

172
**Usage Example:**
173

174
```javascript
175
var source = Rx.Observable.fromArray([1, 2, 2, 3, 1, 4]);
176
var distinct = source.distinct();
177
// Emits: 1, 2, 3, 4
178
```
179

180
### Distinct Until Changed
181

182
Filters out consecutive duplicate values.
183

184
```javascript { .api }
185
/**
186
 * Returns distinct contiguous elements from an observable sequence
187
 * @param {function} [keySelector] - Function to compute comparison key for each element
188
 * @param {function} [comparer] - Function to compare keys for equality
189
 * @returns {Observable} Observable sequence with consecutive duplicates removed
190
 */
191
observable.distinctUntilChanged = function(keySelector, comparer);
192
```
193

194
**Usage Example:**
195

196
```javascript
197
var source = Rx.Observable.fromArray([1, 1, 2, 2, 2, 3, 3, 1]);
198
var distinct = source.distinctUntilChanged();
199
// Emits: 1, 2, 3, 1
200
```
201

202
### Ignore Elements
203

204
Ignores all elements and only propagates completion or error.
205

206
```javascript { .api }
207
/**
208
 * Ignores all elements in an observable sequence leaving only termination messages
209
 * @returns {Observable} Observable sequence with all elements ignored
210
 */
211
observable.ignoreElements = function();
212
```
213

214
### Default If Empty
215

216
Provides a default value if the sequence is empty.
217

218
```javascript { .api }
219
/**
220
 * Returns elements from sequence, or default value if sequence is empty
221
 * @param {*} [defaultValue] - Default value to return if sequence is empty
222
 * @returns {Observable} Observable sequence with default value if empty
223
 */
224
observable.defaultIfEmpty = function(defaultValue);
225
```
226

227
**Usage Example:**
228

229
```javascript
230
var empty = Rx.Observable.empty();
231
var withDefault = empty.defaultIfEmpty('No data');
232
// Emits: 'No data'
233
```
234

235
### Element At
236

237
Returns the element at a specified index.
238

239
```javascript { .api }
240
/**
241
 * Returns the element at the specified index in the sequence
242
 * @param {number} index - Zero-based index of element to retrieve
243
 * @returns {Observable} Observable sequence containing element at specified index
244
 */
245
observable.elementAt = function(index);
246
```
247

248
### Element At Or Default
249

250
Returns the element at a specified index or a default value.
251

252
```javascript { .api }
253
/**
254
 * Returns element at specified index or default value if index is out of range
255
 * @param {number} index - Zero-based index of element to retrieve
256
 * @param {*} [defaultValue] - Default value if index is out of range
257
 * @returns {Observable} Observable sequence containing element or default value
258
 */
259
observable.elementAtOrDefault = function(index, defaultValue);
260
```
261

262
### Single
263

264
Returns the only element of a sequence or throws an error.
265

266
```javascript { .api }
267
/**
268
 * Returns the only element of a sequence, or throws error if not exactly one element
269
 * @param {function} [predicate] - Function to test each element
270
 * @param {*} [thisArg] - Object to use as this when executing predicate
271
 * @returns {Observable} Observable sequence containing the single element
272
 */
273
observable.single = function(predicate, thisArg);
274
```
275

276
### Single Or Default
277

278
Returns the only element of a sequence or a default value.
279

280
```javascript { .api }
281
/**
282
 * Returns the only element of a sequence or default value
283
 * @param {function} [predicate] - Function to test each element
284
 * @param {*} [defaultValue] - Default value if no element or more than one element
285
 * @param {*} [thisArg] - Object to use as this when executing predicate
286
 * @returns {Observable} Observable sequence containing the single element or default
287
 */
288
observable.singleOrDefault = function(predicate, defaultValue, thisArg);
289
```
290

291
### Find
292

293
Searches for an element that matches the conditions and returns the first occurrence.
294

295
```javascript { .api }
296
/**
297
 * Searches for an element that matches the conditions and returns the first occurrence
298
 * @param {function} predicate - Function to test each element
299
 * @param {*} [thisArg] - Object to use as this when executing predicate
300
 * @returns {Observable} Observable sequence containing the first matching element or undefined
301
 */
302
observable.find = function(predicate, thisArg);
303
```
304

305
### FindIndex
306

307
Searches for an element that matches the conditions and returns the index.
308

309
```javascript { .api }
310
/**
311
 * Searches for an element that matches the conditions and returns the zero-based index
312
 * @param {function} predicate - Function to test each element
313
 * @param {*} [thisArg] - Object to use as this when executing predicate
314
 * @returns {Observable} Observable sequence containing the index or -1 if not found
315
 */
316
observable.findIndex = function(predicate, thisArg);
317
```
318

319
### IndexOf
320

321
Returns the index of the first occurrence of a value.
322

323
```javascript { .api }
324
/**
325
 * Returns the index of the first occurrence of a value in the sequence
326
 * @param {*} searchElement - Element to locate
327
 * @param {number} [fromIndex] - Index to start the search at
328
 * @returns {Observable} Observable sequence containing the index or -1 if not found
329
 */
330
observable.indexOf = function(searchElement, fromIndex);
331
```
332

333
### LastIndexOf
334

335
Returns the index of the last occurrence of a value.
336

337
```javascript { .api }
338
/**
339
 * Returns the index of the last occurrence of a value in the sequence
340
 * @param {*} searchElement - Element to locate
341
 * @param {number} [fromIndex] - Index to start the search at
342
 * @returns {Observable} Observable sequence containing the index or -1 if not found
343
 */
344
observable.lastIndexOf = function(searchElement, fromIndex);
345
```
346

347
### Includes
348

349
Determines whether the sequence includes a certain element.
350

351
```javascript { .api }
352
/**
353
 * Determines whether the sequence includes a certain element
354
 * @param {*} searchElement - Element to search for
355
 * @param {number} [fromIndex] - Index to start the search at
356
 * @returns {Observable} Observable sequence containing boolean result
357
 */
358
observable.includes = function(searchElement, fromIndex);
359
```
360

361
### Slice
362

363
Returns elements from start index to end index.
364

365
```javascript { .api }
366
/**
367
 * Returns elements from start index to end index
368
 * @param {number} start - Zero-based index at which to begin extraction
369
 * @param {number} [end] - Zero-based index at which to end extraction
370
 * @returns {Observable} Observable sequence containing sliced elements
371
 */
372
observable.slice = function(start, end);
373
```
374

375
### TakeLast
376

377
Returns a specified number of contiguous elements from the end.
378

379
```javascript { .api }
380
/**
381
 * Returns a specified number of contiguous elements from the end of sequence
382
 * @param {number} count - Number of elements to take from end
383
 * @returns {Observable} Observable sequence containing the last elements
384
 */
385
observable.takeLast = function(count);
386
```
387

388
### SkipLast
389

390
Bypasses a specified number of elements at the end.
391

392
```javascript { .api }
393
/**
394
 * Bypasses a specified number of elements at the end of sequence
395
 * @param {number} count - Number of elements to skip from end
396
 * @returns {Observable} Observable sequence bypassing the last elements
397
 */
398
observable.skipLast = function(count);
399
```
400

401
### TakeLastBuffer
402

403
Returns the last elements as a single array emission.
404

405
```javascript { .api }
406
/**
407
 * Returns the last elements as a single array emission
408
 * @param {number} count - Number of elements to take from end
409
 * @returns {Observable} Observable sequence containing array of last elements
410
 */
411
observable.takeLastBuffer = function(count);
412
```
413

414
### TakeLastWithTime
415

416
Returns elements within a specified time window from the end.
417

418
```javascript { .api }
419
/**
420
 * Returns elements within a specified time window from the end
421
 * @param {number} duration - Maximum time interval between values
422
 * @param {Scheduler} [scheduler] - Scheduler to run timers on
423
 * @returns {Observable} Observable sequence containing time-windowed elements
424
 */
425
observable.takeLastWithTime = function(duration, scheduler);
426
```
427

428
### SkipLastWithTime
429

430
Skips elements within a specified time window from the end.
431

432
```javascript { .api }
433
/**
434
 * Skips elements within a specified time window from the end
435
 * @param {number} duration - Maximum time interval between values
436
 * @param {Scheduler} [scheduler] - Scheduler to run timers on
437
 * @returns {Observable} Observable sequence skipping time-windowed elements
438
 */
439
observable.skipLastWithTime = function(duration, scheduler);
440
```
441

442
### TakeWithTime
443

444
Takes elements for the specified duration.
445

446
```javascript { .api }
447
/**
448
 * Takes elements for the specified duration from the start of sequence
449
 * @param {number} duration - Duration to take elements for
450
 * @param {Scheduler} [scheduler] - Scheduler to run timers on
451
 * @returns {Observable} Observable sequence containing elements within time window
452
 */
453
observable.takeWithTime = function(duration, scheduler);
454
```
455

456
### SkipWithTime
457

458
Skips elements for the specified duration.
459

460
```javascript { .api }
461
/**
462
 * Skips elements for the specified duration from the start of sequence
463
 * @param {number} duration - Duration to skip elements for
464
 * @param {Scheduler} [scheduler] - Scheduler to run timers on
465
 * @returns {Observable} Observable sequence skipping elements within time window
466
 */
467
observable.skipWithTime = function(duration, scheduler);
468
```