Skip to content

Commit

Permalink
2.x: Detail distinct() & distinctUntilChanged() in JavaDoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@akarnokd
akarnokd committed Feb 2, 2018
1 parent 7e9eb4f commit 254ae70
Show file tree
Hide file tree
Showing 2 changed files with 132 additions and 10 deletions.
71 changes: 66 additions & 5 deletions src/main/java/io/reactivex/Flowable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7669,9 +7669,24 @@ public final <T2> Flowable<T2> dematerialize() {
}

/**
* Returns a Flowable that emits all items emitted by the source Publisher that are distinct.
* Returns a Flowable that emits all items emitted by the source Publisher that are distinct
* based on {@link Object#equals(Object)} comparison.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.png" alt="">
* <p>
* It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()} to provide
* meaningful comparison between items as the default Java implementation only considers reference equivalence.
* <p>
* By default, {@code distinct()} uses an internal, per Subscriber {@link java.util.HashSet} to remember
* previously seen items and uses {@link java.util.Set#add(Object)} returning {@code false} as the
* indicator for duplicates.
* <p>
* Note that this internal {@code HashSet} may grow unbounded as items won't be removed from it by
* the operator. Therefore, using very long or infinite upstream (with very distinct elements) may lead
* to {@code OutOfMemoryError}.
* <p>
* Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
* to the {@link #distinct(Function, Callable)} overload.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator doesn't interfere with backpressure which is determined by the source {@code Publisher}'s
Expand All @@ -7683,6 +7698,8 @@ public final <T2> Flowable<T2> dematerialize() {
* @return a Flowable that emits only those items emitted by the source Publisher that are distinct from
* each other
* @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
* @see #distinct(Function)
* @see #distinct(Function, Callable)
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@CheckReturnValue
Expand All @@ -7694,9 +7711,24 @@ public final Flowable<T> distinct() {

/**
* Returns a Flowable that emits all items emitted by the source Publisher that are distinct according
* to a key selector function.
* to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
* returned by the key selector function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.png" alt="">
* <p>
* It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
* meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
* <p>
* By default, {@code distinct()} uses an internal, per Subscriber {@link java.util.HashSet} to remember
* previously seen keys and uses {@link java.util.Set#add(Object)} returning {@code false} as the
* indicator for duplicates.
* <p>
* Note that this internal {@code HashSet} may grow unbounded as keys won't be removed from it by
* the operator. Therefore, using very long or infinite upstream (with very distinct keys) may lead
* to {@code OutOfMemoryError}.
* <p>
* Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
* to the {@link #distinct(Function, Callable)} overload.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator doesn't interfere with backpressure which is determined by the source {@code Publisher}'s
Expand All @@ -7711,6 +7743,7 @@ public final Flowable<T> distinct() {
* is distinct from another one or not
* @return a Flowable that emits those items emitted by the source Publisher that have distinct keys
* @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
* @see #distinct(Function, Callable)
*/
@CheckReturnValue
@BackpressureSupport(BackpressureKind.FULL)
Expand All @@ -7721,9 +7754,13 @@ public final <K> Flowable<T> distinct(Function<? super T, K> keySelector) {

/**
* Returns a Flowable that emits all items emitted by the source Publisher that are distinct according
* to a key selector function.
* to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
* returned by the key selector function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.png" alt="">
* <p>
* It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
* meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator doesn't interfere with backpressure which is determined by the source {@code Publisher}'s
Expand Down Expand Up @@ -7754,9 +7791,18 @@ public final <K> Flowable<T> distinct(Function<? super T, K> keySelector,

/**
* Returns a Flowable that emits all items emitted by the source Publisher that are distinct from their
* immediate predecessors.
* immediate predecessors based on {@link Object#equals(Object)} comparison.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.png" alt="">
* <p>
* It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()} to provide
* meaningful comparison between items as the default Java implementation only considers reference equivalence.
* Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
* in case the class {@code T} can't be overridden with custom {@code equals()} or the comparison itself
* should happen on different terms or properties of the class {@code T}.
* <p>
* Note that the operator always retains the latest item from upstream regardless of the comparison result
* and uses it in the next comparison with the next upstream item.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator doesn't interfere with backpressure which is determined by the source {@code Publisher}'s
Expand All @@ -7768,6 +7814,7 @@ public final <K> Flowable<T> distinct(Function<? super T, K> keySelector,
* @return a Flowable that emits those items from the source Publisher that are distinct from their
* immediate predecessors
* @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
* @see #distinctUntilChanged(BiPredicate)
*/
@CheckReturnValue
@BackpressureSupport(BackpressureKind.FULL)
Expand All @@ -7778,9 +7825,20 @@ public final Flowable<T> distinctUntilChanged() {

/**
* Returns a Flowable that emits all items emitted by the source Publisher that are distinct from their
* immediate predecessors, according to a key selector function.
* immediate predecessors, according to a key selector function and based on {@link Object#equals(Object)} comparison
* of those objects returned by the key selector function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.key.png" alt="">
* <p>
* It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
* meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
* Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
* in case the class {@code K} can't be overridden with custom {@code equals()} or the comparison itself
* should happen on different terms or properties of the item class {@code T} (for which the keys can be
* derived via a similar selector).
* <p>
* Note that the operator always retains the latest key from upstream regardless of the comparison result
* and uses it in the next comparison with the next key derived from the next upstream item.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator doesn't interfere with backpressure which is determined by the source {@code Publisher}'s
Expand Down Expand Up @@ -7810,6 +7868,9 @@ public final <K> Flowable<T> distinctUntilChanged(Function<? super T, K> keySele
* immediate predecessors when compared with each other via the provided comparator function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.png" alt="">
* <p>
* Note that the operator always retains the latest item from upstream regardless of the comparison result
* and uses it in the next comparison with the next upstream item.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>The operator doesn't interfere with backpressure which is determined by the source {@code Publisher}'s
Expand Down
71 changes: 66 additions & 5 deletions src/main/java/io/reactivex/Observable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7011,9 +7011,24 @@ public final <T2> Observable<T2> dematerialize() {
}

/**
* Returns an Observable that emits all items emitted by the source ObservableSource that are distinct.
* Returns an Observable that emits all items emitted by the source ObservableSource that are distinct
* based on {@link Object#equals(Object)} comparison.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.png" alt="">
* <p>
* It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()} to provide
* meaningful comparison between items as the default Java implementation only considers reference equivalence.
* <p>
* By default, {@code distinct()} uses an internal, per Subscriber {@link java.util.HashSet} to remember
* previously seen items and uses {@link java.util.Set#add(Object)} returning {@code false} as the
* indicator for duplicates.
* <p>
* Note that this internal {@code HashSet} may grow unbounded as items won't be removed from it by
* the operator. Therefore, using very long or infinite upstream (with very distinct elements) may lead
* to {@code OutOfMemoryError}.
* <p>
* Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
* to the {@link #distinct(Function, Callable)} overload.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
Expand All @@ -7022,6 +7037,8 @@ public final <T2> Observable<T2> dematerialize() {
* @return an Observable that emits only those items emitted by the source ObservableSource that are distinct from
* each other
* @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
* @see #distinct(Function)
* @see #distinct(Function, Callable)
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
Expand All @@ -7031,9 +7048,24 @@ public final Observable<T> distinct() {

/**
* Returns an Observable that emits all items emitted by the source ObservableSource that are distinct according
* to a key selector function.
* to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
* returned by the key selector function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.png" alt="">
* <p>
* It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
* meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
* <p>
* By default, {@code distinct()} uses an internal, per Subscriber {@link java.util.HashSet} to remember
* previously seen keys and uses {@link java.util.Set#add(Object)} returning {@code false} as the
* indicator for duplicates.
* <p>
* Note that this internal {@code HashSet} may grow unbounded as keys won't be removed from it by
* the operator. Therefore, using very long or infinite upstream (with very distinct keys) may lead
* to {@code OutOfMemoryError}.
* <p>
* Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
* to the {@link #distinct(Function, Callable)} overload.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
Expand All @@ -7045,6 +7077,7 @@ public final Observable<T> distinct() {
* is distinct from another one or not
* @return an Observable that emits those items emitted by the source ObservableSource that have distinct keys
* @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
* @see #distinct(Function, Callable)
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
Expand All @@ -7054,9 +7087,13 @@ public final <K> Observable<T> distinct(Function<? super T, K> keySelector) {

/**
* Returns an Observable that emits all items emitted by the source ObservableSource that are distinct according
* to a key selector function.
* to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
* returned by the key selector function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.png" alt="">
* <p>
* It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
* meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
Expand All @@ -7082,9 +7119,18 @@ public final <K> Observable<T> distinct(Function<? super T, K> keySelector, Call

/**
* Returns an Observable that emits all items emitted by the source ObservableSource that are distinct from their
* immediate predecessors.
* immediate predecessors based on {@link Object#equals(Object)} comparison.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.png" alt="">
* <p>
* It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()} to provide
* meaningful comparison between items as the default Java implementation only considers reference equivalence.
* Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
* in case the class {@code T} can't be overridden with custom {@code equals()} or the comparison itself
* should happen on different terms or properties of the class {@code T}.
* <p>
* Note that the operator always retains the latest item from upstream regardless of the comparison result
* and uses it in the next comparison with the next upstream item.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
Expand All @@ -7093,6 +7139,7 @@ public final <K> Observable<T> distinct(Function<? super T, K> keySelector, Call
* @return an Observable that emits those items from the source ObservableSource that are distinct from their
* immediate predecessors
* @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
* @see #distinctUntilChanged(BiPredicate)
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
Expand All @@ -7102,9 +7149,20 @@ public final Observable<T> distinctUntilChanged() {

/**
* Returns an Observable that emits all items emitted by the source ObservableSource that are distinct from their
* immediate predecessors, according to a key selector function.
* immediate predecessors, according to a key selector function and based on {@link Object#equals(Object)} comparison
* of those objects returned by the key selector function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.key.png" alt="">
* <p>
* It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
* meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
* Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
* in case the class {@code K} can't be overridden with custom {@code equals()} or the comparison itself
* should happen on different terms or properties of the item class {@code T} (for which the keys can be
* derived via a similar selector).
* <p>
* Note that the operator always retains the latest key from upstream regardless of the comparison result
* and uses it in the next comparison with the next key derived from the next upstream item.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
Expand All @@ -7130,6 +7188,9 @@ public final <K> Observable<T> distinctUntilChanged(Function<? super T, K> keySe
* immediate predecessors when compared with each other via the provided comparator function.
* <p>
* <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.png" alt="">
* <p>
* Note that the operator always retains the latest item from upstream regardless of the comparison result
* and uses it in the next comparison with the next upstream item.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
Expand Down

0 comments on commit 254ae70

Please sign in to comment.