3.x: disambiguate startWith+1 to startWithItem & startWithIterable (#6530)

Author: akarnokd

src/main/java/io/reactivex/Flowable.java

@@ -14598,20 +14598,23 @@ public final Flowable<T> sorted(Comparator<? super T> sortFunction) {
      *  is expected to honor backpressure as well. If it violates this rule, it <em>may</em> throw an
      *  {@code IllegalStateException} when the source {@code Publisher} completes.</dd>
      *  <dt><b>Scheduler:</b></dt>
-     *  <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
+     *  <dd>{@code startWithIterable} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      *
      * @param items
      *            an Iterable that contains the items you want the modified Publisher to emit first
      * @return a Flowable that emits the items in the specified {@link Iterable} and then emits the items
      *         emitted by the source Publisher
      * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
+     * @see #startWithArray(Object...)
+     * @see #startWithItem(Object)
+     * @since 3.0.0
      */
     @SuppressWarnings("unchecked")
     @CheckReturnValue
     @BackpressureSupport(BackpressureKind.FULL)
     @SchedulerSupport(SchedulerSupport.NONE)
-    public final Flowable<T> startWith(Iterable<? extends T> items) {
+    public final Flowable<T> startWithIterable(Iterable<? extends T> items) {
         return concatArray(fromIterable(items), this);
     }
 
@@ -14656,23 +14659,26 @@ public final Flowable<T> startWith(Publisher<? extends T> other) {
      *  is expected to honor backpressure as well. If it violates this rule, it <em>may</em> throw an
      *  {@code IllegalStateException} when the source {@code Publisher} completes.</dd>
      *  <dt><b>Scheduler:</b></dt>
-     *  <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
+     *  <dd>{@code startWithItem} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      *
-     * @param value
+     * @param item
      *            the item to emit first
      * @return a Flowable that emits the specified item before it begins to emit items emitted by the source
      *         Publisher
      * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
+     * @see #startWithArray(Object...)
+     * @see #startWithIterable(Iterable)
+     * @since 3.0.0
      */
     @SuppressWarnings("unchecked")
     @CheckReturnValue
     @NonNull
     @BackpressureSupport(BackpressureKind.FULL)
     @SchedulerSupport(SchedulerSupport.NONE)
-    public final Flowable<T> startWith(T value) {
-        ObjectHelper.requireNonNull(value, "value is null");
-        return concatArray(just(value), this);
+    public final Flowable<T> startWithItem(T item) {
+        ObjectHelper.requireNonNull(item, "item is null");
+        return concatArray(just(item), this);
     }
 
     /**
@@ -14694,6 +14700,8 @@ public final Flowable<T> startWith(T value) {
      * @return a Flowable that emits the specified items before it begins to emit items emitted by the source
      *         Publisher
      * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
+     * @see #startWithItem(Object)
+     * @see #startWithIterable(Iterable)
      */
     @SuppressWarnings("unchecked")
     @CheckReturnValue

src/main/java/io/reactivex/Observable.java

@@ -12036,19 +12036,22 @@ public final Observable<T> sorted(Comparator<? super T> sortFunction) {
      * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
-     *  <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
+     *  <dd>{@code startWithIterable} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      *
      * @param items
      *            an Iterable that contains the items you want the modified ObservableSource to emit first
      * @return an Observable that emits the items in the specified {@link Iterable} and then emits the items
      *         emitted by the source ObservableSource
      * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
+     * @since 3.0.0
+     * @see #startWithItem(Object)
+     * @see #startWithArray(Object...)
      */
     @SuppressWarnings("unchecked")
     @CheckReturnValue
     @SchedulerSupport(SchedulerSupport.NONE)
-    public final Observable<T> startWith(Iterable<? extends T> items) {
+    public final Observable<T> startWithIterable(Iterable<? extends T> items) {
         return concatArray(fromIterable(items), this);
     }
 
@@ -12083,19 +12086,22 @@ public final Observable<T> startWith(ObservableSource<? extends T> other) {
      * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.item.png" alt="">
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
-     *  <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
+     *  <dd>{@code startWithItem} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
      *
      * @param item
      *            the item to emit first
      * @return an Observable that emits the specified item before it begins to emit items emitted by the source
      *         ObservableSource
      * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
+     * @see #startWithArray(Object...)
+     * @see #startWithIterable(Iterable)
+     * @since 3.0.0
      */
     @SuppressWarnings("unchecked")
     @CheckReturnValue
     @SchedulerSupport(SchedulerSupport.NONE)
-    public final Observable<T> startWith(T item) {
+    public final Observable<T> startWithItem(T item) {
         ObjectHelper.requireNonNull(item, "item is null");
         return concatArray(just(item), this);
     }
@@ -12115,6 +12121,8 @@ public final Observable<T> startWith(T item) {
      * @return an Observable that emits the specified items before it begins to emit items emitted by the source
      *         ObservableSource
      * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
+     * @see #startWithItem(Object)
+     * @see #startWithIterable(Iterable)
      */
     @SuppressWarnings("unchecked")
     @CheckReturnValue

src/test/java/io/reactivex/flowable/FlowableCovarianceTest.java

@@ -212,7 +212,7 @@ public Flowable<Movie> apply(List<List<Movie>> listOfLists) {
         @Override
         public Publisher<Movie> apply(Flowable<List<Movie>> movieList) {
             return movieList
-                .startWith(new ArrayList<Movie>())
+                .startWithItem(new ArrayList<Movie>())
                 .buffer(2, 1)
                 .skip(1)
                 .flatMap(calculateDelta);

src/test/java/io/reactivex/flowable/FlowableNullTests.java

@@ -2103,12 +2103,12 @@ public void skipWhileNull() {
 
     @Test(expected = NullPointerException.class)
     public void startWithIterableNull() {
-        just1.startWith((Iterable<Integer>)null);
+        just1.startWithIterable((Iterable<Integer>)null);
     }
 
     @Test(expected = NullPointerException.class)
     public void startWithIterableIteratorNull() {
-        just1.startWith(new Iterable<Integer>() {
+        just1.startWithIterable(new Iterable<Integer>() {
             @Override
             public Iterator<Integer> iterator() {
                 return null;
@@ -2118,12 +2118,12 @@ public Iterator<Integer> iterator() {
 
     @Test(expected = NullPointerException.class)
     public void startWithIterableOneNull() {
-        just1.startWith(Arrays.asList(1, null)).blockingSubscribe();
+        just1.startWithIterable(Arrays.asList(1, null)).blockingSubscribe();
     }
 
     @Test(expected = NullPointerException.class)
     public void startWithSingleNull() {
-        just1.startWith((Integer)null);
+        just1.startWithItem((Integer)null);
     }
 
     @Test(expected = NullPointerException.class)

src/test/java/io/reactivex/flowable/FlowableStartWithTests.java

@@ -37,7 +37,7 @@ public void startWithIterable() {
         List<String> li = new ArrayList<String>();
         li.add("alpha");
         li.add("beta");
-        List<String> values = Flowable.just("one", "two").startWith(li).toList().blockingGet();
+        List<String> values = Flowable.just("one", "two").startWithIterable(li).toList().blockingGet();
 
         assertEquals("alpha", values.get(0));
         assertEquals("beta", values.get(1));

src/test/java/io/reactivex/flowable/FlowableTests.java

@@ -968,7 +968,7 @@ public void justWithScheduler() {
     @Test
     public void startWithWithScheduler() {
         TestScheduler scheduler = new TestScheduler();
-        Flowable<Integer> flowable = Flowable.just(3, 4).startWith(Arrays.asList(1, 2)).subscribeOn(scheduler);
+        Flowable<Integer> flowable = Flowable.just(3, 4).startWithIterable(Arrays.asList(1, 2)).subscribeOn(scheduler);
 
         Subscriber<Integer> subscriber = TestHelper.mockSubscriber();
 

src/test/java/io/reactivex/internal/operators/flowable/FlowableCombineLatestTest.java

@@ -1363,7 +1363,7 @@ public Object apply(Object[] a) throws Exception {
                     }
                 },
                 128,
-                Flowable.error(new TestException()).startWith(1),
+                Flowable.error(new TestException()).startWithItem(1),
                 Flowable.empty()
         )
         .test()

src/test/java/io/reactivex/internal/operators/flowable/FlowableMergeDelayErrorTest.java

@@ -499,7 +499,7 @@ public void errorInParentFlowable() {
         TestSubscriberEx<Integer> ts = new TestSubscriberEx<Integer>();
         Flowable.mergeDelayError(
                 Flowable.just(Flowable.just(1), Flowable.just(2))
-                        .startWith(Flowable.<Integer> error(new RuntimeException()))
+                        .startWithItem(Flowable.<Integer> error(new RuntimeException()))
                 ).subscribe(ts);
         ts.awaitDone(5, TimeUnit.SECONDS);
         ts.assertTerminated();

src/test/java/io/reactivex/internal/operators/flowable/FlowableRetryTest.java

@@ -145,7 +145,7 @@ public Flowable<Object> apply(Flowable<? extends Throwable> t1) {
                     public Integer apply(Throwable t1) {
                         return 1;
                     }
-                }).startWith(1).cast(Object.class);
+                }).startWithItem(1).cast(Object.class);
             }
         })
         .doOnError(new Consumer<Throwable>() {
@@ -183,7 +183,7 @@ public Flowable<Object> apply(Flowable<? extends Throwable> t1) {
                     public Integer apply(Throwable t1) {
                         return 0;
                     }
-                }).startWith(0).cast(Object.class);
+                }).startWithItem(0).cast(Object.class);
             }
         }).subscribe(subscriber);
 

src/test/java/io/reactivex/internal/operators/flowable/FlowableWindowWithSizeTest.java

@@ -289,7 +289,7 @@ public void takeFlatMapCompletes() {
         .flatMap(new Function<Flowable<Integer>, Flowable<Integer>>() {
             @Override
             public Flowable<Integer> apply(Flowable<Integer> w) {
-                return w.startWith(indicator);
+                return w.startWithItem(indicator);
             }
         }).subscribe(ts);
 

src/test/java/io/reactivex/internal/operators/flowable/FlowableWindowWithTimeTest.java

@@ -200,7 +200,7 @@ public void run() {
         .flatMap(new Function<Flowable<Integer>, Flowable<Integer>>() {
             @Override
             public Flowable<Integer> apply(Flowable<Integer> w) {
-                return w.startWith(indicator)
+                return w.startWithItem(indicator)
                         .doOnComplete(new Action() {
                             @Override
                             public void run() {

src/test/java/io/reactivex/internal/operators/observable/ObservableCombineLatestTest.java

@@ -951,7 +951,7 @@ public Object apply(Object[] a) throws Exception {
                     }
                 },
                 128,
-                Observable.error(new TestException()).startWith(1),
+                Observable.error(new TestException()).startWithItem(1),
                 Observable.empty()
         )
         .test()

src/test/java/io/reactivex/internal/operators/observable/ObservableMergeDelayErrorTest.java

@@ -493,7 +493,7 @@ public void errorInParentObservable() {
         TestObserverEx<Integer> to = new TestObserverEx<Integer>();
         Observable.mergeDelayError(
                 Observable.just(Observable.just(1), Observable.just(2))
-                        .startWith(Observable.<Integer> error(new RuntimeException()))
+                        .startWithItem(Observable.<Integer> error(new RuntimeException()))
                 ).subscribe(to);
         to.awaitDone(5, TimeUnit.SECONDS);
         to.assertTerminated();

src/test/java/io/reactivex/internal/operators/observable/ObservableRetryTest.java

@@ -147,7 +147,7 @@ public Observable<Object> apply(Observable<? extends Throwable> t1) {
                     public Object apply(Throwable t1) {
                         return 1;
                     }
-                }).startWith(1);
+                }).startWithItem(1);
             }
         })
         .doOnError(new Consumer<Throwable>() {
@@ -185,7 +185,7 @@ public Observable<Object> apply(Observable<? extends Throwable> t1) {
                     public Integer apply(Throwable t1) {
                         return 0;
                     }
-                }).startWith(0).cast(Object.class);
+                }).startWithItem(0).cast(Object.class);
             }
         }).subscribe(observer);
 

src/test/java/io/reactivex/internal/operators/observable/ObservableWindowWithSizeTest.java

@@ -251,7 +251,7 @@ public void takeFlatMapCompletes() {
         .flatMap(new Function<Observable<Integer>, Observable<Integer>>() {
             @Override
             public Observable<Integer> apply(Observable<Integer> w) {
-                return w.startWith(indicator);
+                return w.startWithItem(indicator);
             }
         }).subscribe(to);
 

src/test/java/io/reactivex/internal/operators/observable/ObservableWindowWithTimeTest.java

@@ -200,7 +200,7 @@ public void run() {
         .flatMap(new Function<Observable<Integer>, Observable<Integer>>() {
             @Override
             public Observable<Integer> apply(Observable<Integer> w) {
-                return w.startWith(indicator)
+                return w.startWithItem(indicator)
                         .doOnComplete(new Action() {
                             @Override
                             public void run() {

src/test/java/io/reactivex/observable/ObservableCovarianceTest.java

@@ -211,7 +211,7 @@ public Observable<Movie> apply(List<List<Movie>> listOfLists) {
         @Override
         public Observable<Movie> apply(Observable<List<Movie>> movieList) {
             return movieList
-                .startWith(new ArrayList<Movie>())
+                .startWithItem(new ArrayList<Movie>())
                 .buffer(2, 1)
                 .skip(1)
                 .flatMap(calculateDelta);

src/test/java/io/reactivex/observable/ObservableNullTests.java

@@ -2140,12 +2140,12 @@ public void skipWhileNull() {
 
     @Test(expected = NullPointerException.class)
     public void startWithIterableNull() {
-        just1.startWith((Iterable<Integer>)null);
+        just1.startWithIterable((Iterable<Integer>)null);
     }
 
     @Test(expected = NullPointerException.class)
     public void startWithIterableIteratorNull() {
-        just1.startWith(new Iterable<Integer>() {
+        just1.startWithIterable(new Iterable<Integer>() {
             @Override
             public Iterator<Integer> iterator() {
                 return null;
@@ -2155,12 +2155,12 @@ public Iterator<Integer> iterator() {
 
     @Test(expected = NullPointerException.class)
     public void startWithIterableOneNull() {
-        just1.startWith(Arrays.asList(1, null)).blockingSubscribe();
+        just1.startWithIterable(Arrays.asList(1, null)).blockingSubscribe();
     }
 
     @Test(expected = NullPointerException.class)
     public void startWithSingleNull() {
-        just1.startWith((Integer)null);
+        just1.startWithItem((Integer)null);
     }
 
     @Test(expected = NullPointerException.class)

src/test/java/io/reactivex/observable/ObservableStartWithTests.java

@@ -37,7 +37,7 @@ public void startWithIterable() {
         List<String> li = new ArrayList<String>();
         li.add("alpha");
         li.add("beta");
-        List<String> values = Observable.just("one", "two").startWith(li).toList().blockingGet();
+        List<String> values = Observable.just("one", "two").startWithIterable(li).toList().blockingGet();
 
         assertEquals("alpha", values.get(0));
         assertEquals("beta", values.get(1));

src/test/java/io/reactivex/observable/ObservableTest.java

@@ -990,7 +990,7 @@ public void justWithScheduler() {
     @Test
     public void startWithWithScheduler() {
         TestScheduler scheduler = new TestScheduler();
-        Observable<Integer> o = Observable.just(3, 4).startWith(Arrays.asList(1, 2)).subscribeOn(scheduler);
+        Observable<Integer> o = Observable.just(3, 4).startWithIterable(Arrays.asList(1, 2)).subscribeOn(scheduler);
 
         Observer<Integer> observer = TestHelper.mockObserver();