-
Notifications
You must be signed in to change notification settings - Fork 7.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
1 changed file
with
161 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,12 +1,166 @@ | ||
| This section explains operators you can use to combine multiple Observables. | ||
|
|
||
| * [**`startWith( )`**](http://reactivex.io/documentation/operators/startwith.html) — emit a specified sequence of items before beginning to emit the items from the Observable | ||
| * [**`merge( )`**](http://reactivex.io/documentation/operators/merge.html) — combine multiple Observables into one | ||
| * [**`mergeDelayError( )`**](http://reactivex.io/documentation/operators/merge.html) — combine multiple Observables into one, allowing error-free Observables to continue before propagating errors | ||
| * [**`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 | ||
| * (`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 | ||
| * [**`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 | ||
| # Outline | ||
|
|
||
| - [`combineLatest`](#combineLatest) | ||
| - [`join` and `groupJoin`](#joins) | ||
| - [`merge`](#merge) | ||
| - [`mergeDelayError`](#mergeDelayError) | ||
| - [`rxjava-joins`](#rxjava-joins) | ||
| - [`startWith`](#startWith) | ||
| - [`switchOnNext`](#switchOnNext) | ||
| - [`zip`](#zip) | ||
|
|
||
| ## startWith | ||
|
|
||
| **Available in:**  `Flowable`,  `Observable`,  `Maybe`,  `Single`,  `Completable` | ||
|
|
||
| **ReactiveX doumentation:** [http://reactivex.io/documentation/operators/startwith.html](http://reactivex.io/documentation/operators/startwith.html) | ||
|
|
||
| Emit a specified sequence of items before beginning to emit the items from the Observable. | ||
|
|
||
| #### startWith Example | ||
|
|
||
| ```java | ||
| Observable<String> names = Observable.just("Spock", "McCoy"); | ||
| names.startWith("Kirk").subscribe(item -> System.out.println(item)); | ||
|
|
||
| // prints Kirk, Spock, McCoy | ||
| ``` | ||
|
|
||
| ## merge | ||
|
|
||
| Combines multiple Observables into one. | ||
|
|
||
|
|
||
| ### merge | ||
|
|
||
| **Available in:**  `Flowable`,  `Observable`,  `Maybe`,  `Single`,  `Completable` | ||
|
|
||
| **ReactiveX doumentation:** [http://reactivex.io/documentation/operators/merge.html](http://reactivex.io/documentation/operators/merge.html) | ||
|
|
||
| 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`. | ||
|
|
||
| #### merge Example | ||
|
|
||
| ```java | ||
| Observable.just(1, 2, 3) | ||
| .mergeWith(Observable.just(4, 5, 6)) | ||
| .subscribe(item -> System.out.println(item)); | ||
|
|
||
| // prints 1, 2, 3, 4, 5, 6 | ||
| ``` | ||
|
|
||
| ### mergeDelayError | ||
|
|
||
| **Available in:**  `Flowable`,  `Observable`,  `Maybe`,  `Single`,  `Completable` | ||
|
|
||
| **ReactiveX doumentation:** [http://reactivex.io/documentation/operators/merge.html](http://reactivex.io/documentation/operators/merge.html) | ||
|
|
||
| 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. | ||
|
|
||
| #### mergeDelayError Example | ||
|
|
||
| ```java | ||
| Observable<String> observable1 = Observable.error(new IllegalArgumentException("")); | ||
| Observable<String> observable2 = Observable.just("Four", "Five", "Six"); | ||
| Observable.mergeDelayError(observable1, observable2) | ||
| .subscribe(item -> System.out.println(item)); | ||
|
|
||
| // emits 4, 5, 6 and then the IllegalArgumentException (in this specific | ||
| // example, this throws an `OnErrorNotImplementedException`). | ||
| ``` | ||
|
|
||
| ## zip | ||
|
|
||
| **Available in:**  `Flowable`,  `Observable`,  `Maybe`,  `Single`,  `Completable` | ||
|
|
||
| **ReactiveX doumentation:** [http://reactivex.io/documentation/operators/zip.html](http://reactivex.io/documentation/operators/zip.html) | ||
|
|
||
| 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. | ||
|
|
||
| #### zip Example | ||
|
|
||
| ```java | ||
| Observable<String> firstNames = Observable.just("James", "Jean-Luc", "Benjamin"); | ||
| Observable<String> lastNames = Observable.just("Kirk", "Picard", "Sisko"); | ||
| firstNames.zipWith(lastNames, (first, last) -> first + " " + last) | ||
| .subscribe(item -> System.out.println(item)); | ||
|
|
||
| // prints James Kirk, Jean-Luc Picard, Benjamin Sisko | ||
| ``` | ||
|
|
||
| ## combineLatest | ||
|
|
||
| **Available in:**  `Flowable`,  `Observable`,  `Maybe`,  `Single`,  `Completable` | ||
|
|
||
| **ReactiveX doumentation:** [http://reactivex.io/documentation/operators/combinelatest.html](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. | ||
|
|
||
| #### combineLatest Example | ||
|
|
||
| ```java | ||
| Observable<Long> newsRefreshes = Observable.interval(100, TimeUnit.MILLISECONDS); | ||
| Observable<Long> weatherRefreshes = Observable.interval(50, TimeUnit.MILLISECONDS); | ||
| Observable.combineLatest(newsRefreshes, weatherRefreshes, | ||
| (newsRefreshTimes, weatherRefreshTimes) -> | ||
| "Refreshed news " + newsRefreshTimes + " times and weather " + weatherRefreshTimes) | ||
| .subscribe(item -> System.out.println(item)); | ||
|
|
||
| // prints: | ||
| // Refreshed news 0 times and weather 0 | ||
| // Refreshed news 0 times and weather 1 | ||
| // Refreshed news 0 times and weather 2 | ||
| // Refreshed news 1 times and weather 2 | ||
| // Refreshed news 1 times and weather 3 | ||
| // Refreshed news 1 times and weather 4 | ||
| // Refreshed news 2 times and weather 4 | ||
| // Refreshed news 2 times and weather 5 | ||
| // ... | ||
| ``` | ||
|
|
||
| ## switchOnNext | ||
|
|
||
| **Available in:**  `Flowable`,  `Observable`,  `Maybe`,  `Single`,  `Completable` | ||
|
|
||
| **ReactiveX doumentation:** [http://reactivex.io/documentation/operators/switch.html](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. | ||
|
|
||
| #### switchOnNext Example | ||
|
|
||
| ```java | ||
| Observable<Observable<String>> timeIntervals = | ||
| Observable.interval(1, TimeUnit.SECONDS) | ||
| .map(ticks -> Observable.interval(100, TimeUnit.MILLISECONDS) | ||
| .map(innerInterval -> "outer: " + ticks + " - inner: " + innerInterval)); | ||
| Observable.switchOnNext(timeIntervals) | ||
| .subscribe(item -> System.out.println(item)); | ||
|
|
||
| // prints: | ||
| // outer: 0 - inner: 0 | ||
| // outer: 0 - inner: 1 | ||
| // outer: 0 - inner: 2 | ||
| // outer: 0 - inner: 3 | ||
| // outer: 0 - inner: 4 | ||
| // outer: 0 - inner: 5 | ||
| // outer: 0 - inner: 6 | ||
| // outer: 0 - inner: 7 | ||
| // outer: 0 - inner: 8 | ||
| // outer: 1 - inner: 0 | ||
| // outer: 1 - inner: 1 | ||
| // outer: 1 - inner: 2 | ||
| // outer: 1 - inner: 3 | ||
| // ... | ||
| ``` | ||
|
|
||
| ## joins | ||
|
|
||
| * [**`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 | ||
| * [**`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 | ||
|
|
||
| ## rxjava-joins | ||
|
|
||
| * (`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 | ||
|
|
||
| > (`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 |