Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

2.x: Detail distinct() & distinctUntilChanged() in JavaDoc #5837

Merged
merged 2 commits into from
Feb 3, 2018
Merged

2.x: Detail distinct() & distinctUntilChanged() in JavaDoc #5837

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d043b2
2.x: Detail distinct() & distinctUntilChanged() in JavaDoc
akarnokd Feb 2, 2018
b1867be
Address feedback
akarnokd Feb 2, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 66 additions & 5 deletions src/main/java/io/reactivex/Flowable.java
View file
Open in desktop
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we use HashSet internally, we should probably recommend properly overriding hasCode() as well

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same below

* 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

supernit: could be phrased like that By default, {@code distinct()} uses an internal {@link java.util.HashSet} per Subscriber to remember

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same below

* 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
Open in desktop
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 Observer {@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 Observer {@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