Skip to content

Commit 3c27426

Browse files
ahmedreakarnokd
ahmedre
authored and
akarnokd
committed
Initial clean up for Combining Observables docs (#6135)
* Initial clean up for Combining Observables docs This patch updates the style of the combining observables documentation to be similar to that of #6131 and adds examples for most of the operators therein. Refs #6132. * Address comments
1 parent a58c491 commit 3c27426

File tree

1 file changed

+161
-7
lines changed

1 file changed

+161
-7
lines changed

‎docs/Combining-Observables.md

+161-7
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,166 @@
11
This section explains operators you can use to combine multiple Observables.
22

3-
* [**`startWith( )`**](http://reactivex.io/documentation/operators/startwith.html) — emit a specified sequence of items before beginning to emit the items from the Observable
4-
* [**`merge( )`**](http://reactivex.io/documentation/operators/merge.html) — combine multiple Observables into one
5-
* [**`mergeDelayError( )`**](http://reactivex.io/documentation/operators/merge.html) — combine multiple Observables into one, allowing error-free Observables to continue before propagating errors
6-
* [**`zip( )`**](http://reactivex.io/documentation/operators/zip.html) — combine sets of items emitted by two or more Observables together via a specified function and emit items based on the results of this function
7-
* (`rxjava-joins`) [**`and( )`, `then( )`, and `when( )`**](http://reactivex.io/documentation/operators/and-then-when.html) — combine sets of items emitted by two or more Observables by means of `Pattern` and `Plan` intermediaries
8-
* [**`combineLatest( )`**](http://reactivex.io/documentation/operators/combinelatest.html) — when an item is emitted by either of two Observables, combine the latest item emitted by each Observable via a specified function and emit items based on the results of this function
3+
# Outline
4+
5+
- [`combineLatest`](#combineLatest)
6+
- [`join` and `groupJoin`](#joins)
7+
- [`merge`](#merge)
8+
- [`mergeDelayError`](#mergeDelayError)
9+
- [`rxjava-joins`](#rxjava-joins)
10+
- [`startWith`](#startWith)
11+
- [`switchOnNext`](#switchOnNext)
12+
- [`zip`](#zip)
13+
14+
## startWith
15+
16+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
17+
18+
**ReactiveX doumentation:** [http://reactivex.io/documentation/operators/startwith.html](http://reactivex.io/documentation/operators/startwith.html)
19+
20+
Emit a specified sequence of items before beginning to emit the items from the Observable.
21+
22+
#### startWith Example
23+
24+
```java
25+
Observable<String> names = Observable.just("Spock", "McCoy");
26+
names.startWith("Kirk").subscribe(item -> System.out.println(item));
27+
28+
// prints Kirk, Spock, McCoy
29+
```
30+
31+
## merge
32+
33+
Combines multiple Observables into one.
34+
35+
36+
### merge
37+
38+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Completable`
39+
40+
**ReactiveX doumentation:** [http://reactivex.io/documentation/operators/merge.html](http://reactivex.io/documentation/operators/merge.html)
41+
42+
Combines multiple Observables into one. Any `onError` notifications passed from any of the source observables will immediately be passed through to through to the observers and will terminate the merged `Observable`.
43+
44+
#### merge Example
45+
46+
```java
47+
Observable.just(1, 2, 3)
48+
.mergeWith(Observable.just(4, 5, 6))
49+
.subscribe(item -> System.out.println(item));
50+
51+
// prints 1, 2, 3, 4, 5, 6
52+
```
53+
54+
### mergeDelayError
55+
56+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Completable`
57+
58+
**ReactiveX doumentation:** [http://reactivex.io/documentation/operators/merge.html](http://reactivex.io/documentation/operators/merge.html)
59+
60+
Combines multiple Observables into one. Any `onError` notifications passed from any of the source observables will be withheld until all merged Observables complete, and only then will be passed along to the observers.
61+
62+
#### mergeDelayError Example
63+
64+
```java
65+
Observable<String> observable1 = Observable.error(new IllegalArgumentException(""));
66+
Observable<String> observable2 = Observable.just("Four", "Five", "Six");
67+
Observable.mergeDelayError(observable1, observable2)
68+
.subscribe(item -> System.out.println(item));
69+
70+
// emits 4, 5, 6 and then the IllegalArgumentException (in this specific
71+
// example, this throws an `OnErrorNotImplementedException`).
72+
```
73+
74+
## zip
75+
76+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
77+
78+
**ReactiveX doumentation:** [http://reactivex.io/documentation/operators/zip.html](http://reactivex.io/documentation/operators/zip.html)
79+
80+
Combines sets of items emitted by two or more Observables together via a specified function and emit items based on the results of this function.
81+
82+
#### zip Example
83+
84+
```java
85+
Observable<String> firstNames = Observable.just("James", "Jean-Luc", "Benjamin");
86+
Observable<String> lastNames = Observable.just("Kirk", "Picard", "Sisko");
87+
firstNames.zipWith(lastNames, (first, last) -> first + " " + last)
88+
.subscribe(item -> System.out.println(item));
89+
90+
// prints James Kirk, Jean-Luc Picard, Benjamin Sisko
91+
```
92+
93+
## combineLatest
94+
95+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
96+
97+
**ReactiveX doumentation:** [http://reactivex.io/documentation/operators/combinelatest.html](http://reactivex.io/documentation/operators/combinelatest.html)
98+
99+
When an item is emitted by either of two Observables, combine the latest item emitted by each Observable via a specified function and emit items based on the results of this function.
100+
101+
#### combineLatest Example
102+
103+
```java
104+
Observable<Long> newsRefreshes = Observable.interval(100, TimeUnit.MILLISECONDS);
105+
Observable<Long> weatherRefreshes = Observable.interval(50, TimeUnit.MILLISECONDS);
106+
Observable.combineLatest(newsRefreshes, weatherRefreshes,
107+
(newsRefreshTimes, weatherRefreshTimes) ->
108+
"Refreshed news " + newsRefreshTimes + " times and weather " + weatherRefreshTimes)
109+
.subscribe(item -> System.out.println(item));
110+
111+
// prints:
112+
// Refreshed news 0 times and weather 0
113+
// Refreshed news 0 times and weather 1
114+
// Refreshed news 0 times and weather 2
115+
// Refreshed news 1 times and weather 2
116+
// Refreshed news 1 times and weather 3
117+
// Refreshed news 1 times and weather 4
118+
// Refreshed news 2 times and weather 4
119+
// Refreshed news 2 times and weather 5
120+
// ...
121+
```
122+
123+
## switchOnNext
124+
125+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
126+
127+
**ReactiveX doumentation:** [http://reactivex.io/documentation/operators/switch.html](http://reactivex.io/documentation/operators/switch.html)
128+
129+
Convert an Observable that emits Observables into a single Observable that emits the items emitted by the most-recently emitted of those Observables.
130+
131+
#### switchOnNext Example
132+
133+
```java
134+
Observable<Observable<String>> timeIntervals =
135+
Observable.interval(1, TimeUnit.SECONDS)
136+
.map(ticks -> Observable.interval(100, TimeUnit.MILLISECONDS)
137+
.map(innerInterval -> "outer: " + ticks + " - inner: " + innerInterval));
138+
Observable.switchOnNext(timeIntervals)
139+
.subscribe(item -> System.out.println(item));
140+
141+
// prints:
142+
// outer: 0 - inner: 0
143+
// outer: 0 - inner: 1
144+
// outer: 0 - inner: 2
145+
// outer: 0 - inner: 3
146+
// outer: 0 - inner: 4
147+
// outer: 0 - inner: 5
148+
// outer: 0 - inner: 6
149+
// outer: 0 - inner: 7
150+
// outer: 0 - inner: 8
151+
// outer: 1 - inner: 0
152+
// outer: 1 - inner: 1
153+
// outer: 1 - inner: 2
154+
// outer: 1 - inner: 3
155+
// ...
156+
```
157+
158+
## joins
159+
9160
* [**`join( )` and `groupJoin( )`**](http://reactivex.io/documentation/operators/join.html) — combine the items emitted by two Observables whenever one item from one Observable falls within a window of duration specified by an item emitted by the other Observable
10-
* [**`switchOnNext( )`**](http://reactivex.io/documentation/operators/switch.html) — convert an Observable that emits Observables into a single Observable that emits the items emitted by the most-recently emitted of those Observables
161+
162+
## rxjava-joins
163+
164+
* (`rxjava-joins`) [**`and( )`, `then( )`, and `when( )`**](http://reactivex.io/documentation/operators/and-then-when.html) — combine sets of items emitted by two or more Observables by means of `Pattern` and `Plan` intermediaries
11165

12166
> (`rxjava-joins`) — indicates that this operator is currently part of the optional `rxjava-joins` package under `rxjava-contrib` and is not included with the standard RxJava set of operators

0 commit comments

Comments
 (0)