From 3c27426b764cfcc56df56d1ea2ae2a7f1f019ccc Mon Sep 17 00:00:00 2001 From: Ahmed El-Helw Date: Sat, 4 Aug 2018 20:33:02 +0400 Subject: [PATCH] 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 --- docs/Combining-Observables.md | 168 ++++++++++++++++++++++++++++++++-- 1 file changed, 161 insertions(+), 7 deletions(-) diff --git a/docs/Combining-Observables.md b/docs/Combining-Observables.md index 2a60e64bd2..0e3796da1f 100644 --- a/docs/Combining-Observables.md +++ b/docs/Combining-Observables.md @@ -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:** ![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` + +**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 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:** ![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` + +**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:** ![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` + +**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 observable1 = Observable.error(new IllegalArgumentException("")); +Observable 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:** ![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` + +**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 firstNames = Observable.just("James", "Jean-Luc", "Benjamin"); +Observable 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:** ![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` + +**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 newsRefreshes = Observable.interval(100, TimeUnit.MILLISECONDS); +Observable 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:** ![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` + +**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> 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