001/*
002 * Copyright (C) 2015 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you
005 * may not use this file except in compliance with the License.  You may
006 * obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
013 * implied.  See the License for the specific language governing
014 * permissions and limitations under the License.
015 */
016
017package com.google.common.collect;
018
019import static com.google.common.base.Preconditions.checkNotNull;
020import static com.google.common.collect.NullnessCasts.uncheckedCastNullableTToT;
021import static java.lang.Math.min;
022import static java.util.Objects.requireNonNull;
023
024import com.google.common.annotations.Beta;
025import com.google.common.annotations.GwtCompatible;
026import com.google.common.math.LongMath;
027import com.google.errorprone.annotations.InlineMe;
028import com.google.errorprone.annotations.InlineMeValidationDisabled;
029import java.util.ArrayDeque;
030import java.util.Collection;
031import java.util.Deque;
032import java.util.Iterator;
033import java.util.OptionalDouble;
034import java.util.OptionalInt;
035import java.util.OptionalLong;
036import java.util.PrimitiveIterator;
037import java.util.Spliterator;
038import java.util.Spliterators;
039import java.util.Spliterators.AbstractSpliterator;
040import java.util.function.BiConsumer;
041import java.util.function.BiFunction;
042import java.util.function.Consumer;
043import java.util.function.DoubleConsumer;
044import java.util.function.IntConsumer;
045import java.util.function.LongConsumer;
046import java.util.stream.BaseStream;
047import java.util.stream.DoubleStream;
048import java.util.stream.IntStream;
049import java.util.stream.LongStream;
050import java.util.stream.Stream;
051import java.util.stream.StreamSupport;
052import javax.annotation.CheckForNull;
053import org.checkerframework.checker.nullness.qual.Nullable;
054
055/**
056 * Static utility methods related to {@code Stream} instances.
057 *
058 * @since 21.0
059 */
060@GwtCompatible
061@ElementTypesAreNonnullByDefault
062public final class Streams {
063  /**
064   * Returns a sequential {@link Stream} of the contents of {@code iterable}, delegating to {@link
065   * Collection#stream} if possible.
066   */
067  public static <T extends @Nullable Object> Stream<T> stream(Iterable<T> iterable) {
068    return (iterable instanceof Collection)
069        ? ((Collection<T>) iterable).stream()
070        : StreamSupport.stream(iterable.spliterator(), false);
071  }
072
073  /**
074   * Returns {@link Collection#stream}.
075   *
076   * @deprecated There is no reason to use this; just invoke {@code collection.stream()} directly.
077   */
078  @Deprecated
079  @InlineMe(replacement = "collection.stream()")
080  public static <T extends @Nullable Object> Stream<T> stream(Collection<T> collection) {
081    return collection.stream();
082  }
083
084  /**
085   * Returns a sequential {@link Stream} of the remaining contents of {@code iterator}. Do not use
086   * {@code iterator} directly after passing it to this method.
087   */
088  public static <T extends @Nullable Object> Stream<T> stream(Iterator<T> iterator) {
089    return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, 0), false);
090  }
091
092  /**
093   * If a value is present in {@code optional}, returns a stream containing only that element,
094   * otherwise returns an empty stream.
095   */
096  public static <T> Stream<T> stream(com.google.common.base.Optional<T> optional) {
097    return optional.isPresent() ? Stream.of(optional.get()) : Stream.empty();
098  }
099
100  /**
101   * If a value is present in {@code optional}, returns a stream containing only that element,
102   * otherwise returns an empty stream.
103   *
104   * <p><b>Java 9 users:</b> use {@code optional.stream()} instead.
105   */
106  @Beta
107  @InlineMe(replacement = "optional.stream()")
108  @InlineMeValidationDisabled("Java 9+ API only")
109  public static <T> Stream<T> stream(java.util.Optional<T> optional) {
110    return optional.isPresent() ? Stream.of(optional.get()) : Stream.empty();
111  }
112
113  /**
114   * If a value is present in {@code optional}, returns a stream containing only that element,
115   * otherwise returns an empty stream.
116   *
117   * <p><b>Java 9 users:</b> use {@code optional.stream()} instead.
118   */
119  @Beta
120  @InlineMe(replacement = "optional.stream()")
121  @InlineMeValidationDisabled("Java 9+ API only")
122  public static IntStream stream(OptionalInt optional) {
123    return optional.isPresent() ? IntStream.of(optional.getAsInt()) : IntStream.empty();
124  }
125
126  /**
127   * If a value is present in {@code optional}, returns a stream containing only that element,
128   * otherwise returns an empty stream.
129   *
130   * <p><b>Java 9 users:</b> use {@code optional.stream()} instead.
131   */
132  @Beta
133  @InlineMe(replacement = "optional.stream()")
134  @InlineMeValidationDisabled("Java 9+ API only")
135  public static LongStream stream(OptionalLong optional) {
136    return optional.isPresent() ? LongStream.of(optional.getAsLong()) : LongStream.empty();
137  }
138
139  /**
140   * If a value is present in {@code optional}, returns a stream containing only that element,
141   * otherwise returns an empty stream.
142   *
143   * <p><b>Java 9 users:</b> use {@code optional.stream()} instead.
144   */
145  @Beta
146  @InlineMe(replacement = "optional.stream()")
147  @InlineMeValidationDisabled("Java 9+ API only")
148  public static DoubleStream stream(OptionalDouble optional) {
149    return optional.isPresent() ? DoubleStream.of(optional.getAsDouble()) : DoubleStream.empty();
150  }
151
152  @SuppressWarnings("CatchingUnchecked") // sneaky checked exception
153  private static void closeAll(BaseStream<?, ?>[] toClose) {
154    // If one of the streams throws an exception, continue closing the others, then throw the
155    // exception later. If more than one stream throws an exception, the later ones are added to the
156    // first as suppressed exceptions. We don't catch Error on the grounds that it should be allowed
157    // to propagate immediately.
158    Exception exception = null;
159    for (BaseStream<?, ?> stream : toClose) {
160      try {
161        stream.close();
162      } catch (Exception e) { // sneaky checked exception
163        if (exception == null) {
164          exception = e;
165        } else {
166          exception.addSuppressed(e);
167        }
168      }
169    }
170    if (exception != null) {
171      // Normally this is a RuntimeException that doesn't need sneakyThrow.
172      // But theoretically we could see sneaky checked exception
173      sneakyThrow(exception);
174    }
175  }
176
177  /** Throws an undeclared checked exception. */
178  private static void sneakyThrow(Throwable t) {
179    class SneakyThrower<T extends Throwable> {
180      @SuppressWarnings("unchecked") // not really safe, but that's the point
181      void throwIt(Throwable t) throws T {
182        throw (T) t;
183      }
184    }
185    new SneakyThrower<Error>().throwIt(t);
186  }
187
188  /**
189   * Returns a {@link Stream} containing the elements of the first stream, followed by the elements
190   * of the second stream, and so on.
191   *
192   * <p>This is equivalent to {@code Stream.of(streams).flatMap(stream -> stream)}, but the returned
193   * stream may perform better.
194   *
195   * @see Stream#concat(Stream, Stream)
196   */
197  @SuppressWarnings("unchecked") // could probably be avoided with a forwarding Spliterator
198  @SafeVarargs
199  public static <T extends @Nullable Object> Stream<T> concat(Stream<? extends T>... streams) {
200    // TODO(lowasser): consider an implementation that can support SUBSIZED
201    boolean isParallel = false;
202    int characteristics = Spliterator.ORDERED | Spliterator.SIZED | Spliterator.NONNULL;
203    long estimatedSize = 0L;
204    ImmutableList.Builder<Spliterator<? extends T>> splitrsBuilder =
205        new ImmutableList.Builder<>(streams.length);
206    for (Stream<? extends T> stream : streams) {
207      isParallel |= stream.isParallel();
208      Spliterator<? extends T> splitr = stream.spliterator();
209      splitrsBuilder.add(splitr);
210      characteristics &= splitr.characteristics();
211      estimatedSize = LongMath.saturatedAdd(estimatedSize, splitr.estimateSize());
212    }
213    return StreamSupport.stream(
214            CollectSpliterators.flatMap(
215                splitrsBuilder.build().spliterator(),
216                splitr -> (Spliterator<T>) splitr,
217                characteristics,
218                estimatedSize),
219            isParallel)
220        .onClose(() -> closeAll(streams));
221  }
222
223  /**
224   * Returns an {@link IntStream} containing the elements of the first stream, followed by the
225   * elements of the second stream, and so on.
226   *
227   * <p>This is equivalent to {@code Stream.of(streams).flatMapToInt(stream -> stream)}, but the
228   * returned stream may perform better.
229   *
230   * @see IntStream#concat(IntStream, IntStream)
231   */
232  public static IntStream concat(IntStream... streams) {
233    boolean isParallel = false;
234    int characteristics = Spliterator.ORDERED | Spliterator.SIZED | Spliterator.NONNULL;
235    long estimatedSize = 0L;
236    ImmutableList.Builder<Spliterator.OfInt> splitrsBuilder =
237        new ImmutableList.Builder<>(streams.length);
238    for (IntStream stream : streams) {
239      isParallel |= stream.isParallel();
240      Spliterator.OfInt splitr = stream.spliterator();
241      splitrsBuilder.add(splitr);
242      characteristics &= splitr.characteristics();
243      estimatedSize = LongMath.saturatedAdd(estimatedSize, splitr.estimateSize());
244    }
245    return StreamSupport.intStream(
246            CollectSpliterators.flatMapToInt(
247                splitrsBuilder.build().spliterator(),
248                splitr -> splitr,
249                characteristics,
250                estimatedSize),
251            isParallel)
252        .onClose(() -> closeAll(streams));
253  }
254
255  /**
256   * Returns a {@link LongStream} containing the elements of the first stream, followed by the
257   * elements of the second stream, and so on.
258   *
259   * <p>This is equivalent to {@code Stream.of(streams).flatMapToLong(stream -> stream)}, but the
260   * returned stream may perform better.
261   *
262   * @see LongStream#concat(LongStream, LongStream)
263   */
264  public static LongStream concat(LongStream... streams) {
265    boolean isParallel = false;
266    int characteristics = Spliterator.ORDERED | Spliterator.SIZED | Spliterator.NONNULL;
267    long estimatedSize = 0L;
268    ImmutableList.Builder<Spliterator.OfLong> splitrsBuilder =
269        new ImmutableList.Builder<>(streams.length);
270    for (LongStream stream : streams) {
271      isParallel |= stream.isParallel();
272      Spliterator.OfLong splitr = stream.spliterator();
273      splitrsBuilder.add(splitr);
274      characteristics &= splitr.characteristics();
275      estimatedSize = LongMath.saturatedAdd(estimatedSize, splitr.estimateSize());
276    }
277    return StreamSupport.longStream(
278            CollectSpliterators.flatMapToLong(
279                splitrsBuilder.build().spliterator(),
280                splitr -> splitr,
281                characteristics,
282                estimatedSize),
283            isParallel)
284        .onClose(() -> closeAll(streams));
285  }
286
287  /**
288   * Returns a {@link DoubleStream} containing the elements of the first stream, followed by the
289   * elements of the second stream, and so on.
290   *
291   * <p>This is equivalent to {@code Stream.of(streams).flatMapToDouble(stream -> stream)}, but the
292   * returned stream may perform better.
293   *
294   * @see DoubleStream#concat(DoubleStream, DoubleStream)
295   */
296  public static DoubleStream concat(DoubleStream... streams) {
297    boolean isParallel = false;
298    int characteristics = Spliterator.ORDERED | Spliterator.SIZED | Spliterator.NONNULL;
299    long estimatedSize = 0L;
300    ImmutableList.Builder<Spliterator.OfDouble> splitrsBuilder =
301        new ImmutableList.Builder<>(streams.length);
302    for (DoubleStream stream : streams) {
303      isParallel |= stream.isParallel();
304      Spliterator.OfDouble splitr = stream.spliterator();
305      splitrsBuilder.add(splitr);
306      characteristics &= splitr.characteristics();
307      estimatedSize = LongMath.saturatedAdd(estimatedSize, splitr.estimateSize());
308    }
309    return StreamSupport.doubleStream(
310            CollectSpliterators.flatMapToDouble(
311                splitrsBuilder.build().spliterator(),
312                splitr -> splitr,
313                characteristics,
314                estimatedSize),
315            isParallel)
316        .onClose(() -> closeAll(streams));
317  }
318
319  /**
320   * Returns a stream in which each element is the result of passing the corresponding element of
321   * each of {@code streamA} and {@code streamB} to {@code function}.
322   *
323   * <p>For example:
324   *
325   * <pre>{@code
326   * Streams.zip(
327   *   Stream.of("foo1", "foo2", "foo3"),
328   *   Stream.of("bar1", "bar2"),
329   *   (arg1, arg2) -> arg1 + ":" + arg2)
330   * }</pre>
331   *
332   * <p>will return {@code Stream.of("foo1:bar1", "foo2:bar2")}.
333   *
334   * <p>The resulting stream will only be as long as the shorter of the two input streams; if one
335   * stream is longer, its extra elements will be ignored.
336   *
337   * <p>Note that if you are calling {@link Stream#forEach} on the resulting stream, you might want
338   * to consider using {@link #forEachPair} instead of this method.
339   *
340   * <p><b>Performance note:</b> The resulting stream is not <a
341   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>.
342   * This may harm parallel performance.
343   */
344  @Beta
345  public static <A extends @Nullable Object, B extends @Nullable Object, R extends @Nullable Object>
346      Stream<R> zip(
347          Stream<A> streamA, Stream<B> streamB, BiFunction<? super A, ? super B, R> function) {
348    checkNotNull(streamA);
349    checkNotNull(streamB);
350    checkNotNull(function);
351    boolean isParallel = streamA.isParallel() || streamB.isParallel(); // same as Stream.concat
352    Spliterator<A> splitrA = streamA.spliterator();
353    Spliterator<B> splitrB = streamB.spliterator();
354    int characteristics =
355        splitrA.characteristics()
356            & splitrB.characteristics()
357            & (Spliterator.SIZED | Spliterator.ORDERED);
358    Iterator<A> itrA = Spliterators.iterator(splitrA);
359    Iterator<B> itrB = Spliterators.iterator(splitrB);
360    return StreamSupport.stream(
361            new AbstractSpliterator<R>(
362                min(splitrA.estimateSize(), splitrB.estimateSize()), characteristics) {
363              @Override
364              public boolean tryAdvance(Consumer<? super R> action) {
365                if (itrA.hasNext() && itrB.hasNext()) {
366                  action.accept(function.apply(itrA.next(), itrB.next()));
367                  return true;
368                }
369                return false;
370              }
371            },
372            isParallel)
373        .onClose(streamA::close)
374        .onClose(streamB::close);
375  }
376
377  /**
378   * Invokes {@code consumer} once for each pair of <i>corresponding</i> elements in {@code streamA}
379   * and {@code streamB}. If one stream is longer than the other, the extra elements are silently
380   * ignored. Elements passed to the consumer are guaranteed to come from the same position in their
381   * respective source streams. For example:
382   *
383   * <pre>{@code
384   * Streams.forEachPair(
385   *   Stream.of("foo1", "foo2", "foo3"),
386   *   Stream.of("bar1", "bar2"),
387   *   (arg1, arg2) -> System.out.println(arg1 + ":" + arg2)
388   * }</pre>
389   *
390   * <p>will print:
391   *
392   * <pre>{@code
393   * foo1:bar1
394   * foo2:bar2
395   * }</pre>
396   *
397   * <p><b>Warning:</b> If either supplied stream is a parallel stream, the same correspondence
398   * between elements will be made, but the order in which those pairs of elements are passed to the
399   * consumer is <i>not</i> defined.
400   *
401   * <p>Note that many usages of this method can be replaced with simpler calls to {@link #zip}.
402   * This method behaves equivalently to {@linkplain #zip zipping} the stream elements into
403   * temporary pair objects and then using {@link Stream#forEach} on that stream.
404   *
405   * @since 22.0
406   */
407  @Beta
408  public static <A extends @Nullable Object, B extends @Nullable Object> void forEachPair(
409      Stream<A> streamA, Stream<B> streamB, BiConsumer<? super A, ? super B> consumer) {
410    checkNotNull(consumer);
411
412    if (streamA.isParallel() || streamB.isParallel()) {
413      zip(streamA, streamB, TemporaryPair::new).forEach(pair -> consumer.accept(pair.a, pair.b));
414    } else {
415      Iterator<A> iterA = streamA.iterator();
416      Iterator<B> iterB = streamB.iterator();
417      while (iterA.hasNext() && iterB.hasNext()) {
418        consumer.accept(iterA.next(), iterB.next());
419      }
420    }
421  }
422
423  // Use this carefully - it doesn't implement value semantics
424  private static class TemporaryPair<A extends @Nullable Object, B extends @Nullable Object> {
425    @ParametricNullness final A a;
426    @ParametricNullness final B b;
427
428    TemporaryPair(@ParametricNullness A a, @ParametricNullness B b) {
429      this.a = a;
430      this.b = b;
431    }
432  }
433
434  /**
435   * Returns a stream consisting of the results of applying the given function to the elements of
436   * {@code stream} and their indices in the stream. For example,
437   *
438   * <pre>{@code
439   * mapWithIndex(
440   *     Stream.of("a", "b", "c"),
441   *     (e, index) -> index + ":" + e)
442   * }</pre>
443   *
444   * <p>would return {@code Stream.of("0:a", "1:b", "2:c")}.
445   *
446   * <p>The resulting stream is <a
447   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
448   * if and only if {@code stream} was efficiently splittable and its underlying spliterator
449   * reported {@link Spliterator#SUBSIZED}. This is generally the case if the underlying stream
450   * comes from a data structure supporting efficient indexed random access, typically an array or
451   * list.
452   *
453   * <p>The order of the resulting stream is defined if and only if the order of the original stream
454   * was defined.
455   */
456  public static <T extends @Nullable Object, R extends @Nullable Object> Stream<R> mapWithIndex(
457      Stream<T> stream, FunctionWithIndex<? super T, ? extends R> function) {
458    checkNotNull(stream);
459    checkNotNull(function);
460    boolean isParallel = stream.isParallel();
461    Spliterator<T> fromSpliterator = stream.spliterator();
462
463    if (!fromSpliterator.hasCharacteristics(Spliterator.SUBSIZED)) {
464      Iterator<T> fromIterator = Spliterators.iterator(fromSpliterator);
465      return StreamSupport.stream(
466              new AbstractSpliterator<R>(
467                  fromSpliterator.estimateSize(),
468                  fromSpliterator.characteristics() & (Spliterator.ORDERED | Spliterator.SIZED)) {
469                long index = 0;
470
471                @Override
472                public boolean tryAdvance(Consumer<? super R> action) {
473                  if (fromIterator.hasNext()) {
474                    action.accept(function.apply(fromIterator.next(), index++));
475                    return true;
476                  }
477                  return false;
478                }
479              },
480              isParallel)
481          .onClose(stream::close);
482    }
483    class Splitr extends MapWithIndexSpliterator<Spliterator<T>, R, Splitr> implements Consumer<T> {
484      @CheckForNull T holder;
485
486      Splitr(Spliterator<T> splitr, long index) {
487        super(splitr, index);
488      }
489
490      @Override
491      public void accept(@ParametricNullness T t) {
492        this.holder = t;
493      }
494
495      @Override
496      public boolean tryAdvance(Consumer<? super R> action) {
497        if (fromSpliterator.tryAdvance(this)) {
498          try {
499            // The cast is safe because tryAdvance puts a T into `holder`.
500            action.accept(function.apply(uncheckedCastNullableTToT(holder), index++));
501            return true;
502          } finally {
503            holder = null;
504          }
505        }
506        return false;
507      }
508
509      @Override
510      Splitr createSplit(Spliterator<T> from, long i) {
511        return new Splitr(from, i);
512      }
513    }
514    return StreamSupport.stream(new Splitr(fromSpliterator, 0), isParallel).onClose(stream::close);
515  }
516
517  /**
518   * Returns a stream consisting of the results of applying the given function to the elements of
519   * {@code stream} and their indexes in the stream. For example,
520   *
521   * <pre>{@code
522   * mapWithIndex(
523   *     IntStream.of(10, 11, 12),
524   *     (e, index) -> index + ":" + e)
525   * }</pre>
526   *
527   * <p>...would return {@code Stream.of("0:10", "1:11", "2:12")}.
528   *
529   * <p>The resulting stream is <a
530   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
531   * if and only if {@code stream} was efficiently splittable and its underlying spliterator
532   * reported {@link Spliterator#SUBSIZED}. This is generally the case if the underlying stream
533   * comes from a data structure supporting efficient indexed random access, typically an array or
534   * list.
535   *
536   * <p>The order of the resulting stream is defined if and only if the order of the original stream
537   * was defined.
538   */
539  public static <R extends @Nullable Object> Stream<R> mapWithIndex(
540      IntStream stream, IntFunctionWithIndex<R> function) {
541    checkNotNull(stream);
542    checkNotNull(function);
543    boolean isParallel = stream.isParallel();
544    Spliterator.OfInt fromSpliterator = stream.spliterator();
545
546    if (!fromSpliterator.hasCharacteristics(Spliterator.SUBSIZED)) {
547      PrimitiveIterator.OfInt fromIterator = Spliterators.iterator(fromSpliterator);
548      return StreamSupport.stream(
549              new AbstractSpliterator<R>(
550                  fromSpliterator.estimateSize(),
551                  fromSpliterator.characteristics() & (Spliterator.ORDERED | Spliterator.SIZED)) {
552                long index = 0;
553
554                @Override
555                public boolean tryAdvance(Consumer<? super R> action) {
556                  if (fromIterator.hasNext()) {
557                    action.accept(function.apply(fromIterator.nextInt(), index++));
558                    return true;
559                  }
560                  return false;
561                }
562              },
563              isParallel)
564          .onClose(stream::close);
565    }
566    class Splitr extends MapWithIndexSpliterator<Spliterator.OfInt, R, Splitr>
567        implements IntConsumer, Spliterator<R> {
568      int holder;
569
570      Splitr(Spliterator.OfInt splitr, long index) {
571        super(splitr, index);
572      }
573
574      @Override
575      public void accept(int t) {
576        this.holder = t;
577      }
578
579      @Override
580      public boolean tryAdvance(Consumer<? super R> action) {
581        if (fromSpliterator.tryAdvance(this)) {
582          action.accept(function.apply(holder, index++));
583          return true;
584        }
585        return false;
586      }
587
588      @Override
589      Splitr createSplit(Spliterator.OfInt from, long i) {
590        return new Splitr(from, i);
591      }
592    }
593    return StreamSupport.stream(new Splitr(fromSpliterator, 0), isParallel).onClose(stream::close);
594  }
595
596  /**
597   * Returns a stream consisting of the results of applying the given function to the elements of
598   * {@code stream} and their indexes in the stream. For example,
599   *
600   * <pre>{@code
601   * mapWithIndex(
602   *     LongStream.of(10, 11, 12),
603   *     (e, index) -> index + ":" + e)
604   * }</pre>
605   *
606   * <p>...would return {@code Stream.of("0:10", "1:11", "2:12")}.
607   *
608   * <p>The resulting stream is <a
609   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
610   * if and only if {@code stream} was efficiently splittable and its underlying spliterator
611   * reported {@link Spliterator#SUBSIZED}. This is generally the case if the underlying stream
612   * comes from a data structure supporting efficient indexed random access, typically an array or
613   * list.
614   *
615   * <p>The order of the resulting stream is defined if and only if the order of the original stream
616   * was defined.
617   */
618  public static <R extends @Nullable Object> Stream<R> mapWithIndex(
619      LongStream stream, LongFunctionWithIndex<R> function) {
620    checkNotNull(stream);
621    checkNotNull(function);
622    boolean isParallel = stream.isParallel();
623    Spliterator.OfLong fromSpliterator = stream.spliterator();
624
625    if (!fromSpliterator.hasCharacteristics(Spliterator.SUBSIZED)) {
626      PrimitiveIterator.OfLong fromIterator = Spliterators.iterator(fromSpliterator);
627      return StreamSupport.stream(
628              new AbstractSpliterator<R>(
629                  fromSpliterator.estimateSize(),
630                  fromSpliterator.characteristics() & (Spliterator.ORDERED | Spliterator.SIZED)) {
631                long index = 0;
632
633                @Override
634                public boolean tryAdvance(Consumer<? super R> action) {
635                  if (fromIterator.hasNext()) {
636                    action.accept(function.apply(fromIterator.nextLong(), index++));
637                    return true;
638                  }
639                  return false;
640                }
641              },
642              isParallel)
643          .onClose(stream::close);
644    }
645    class Splitr extends MapWithIndexSpliterator<Spliterator.OfLong, R, Splitr>
646        implements LongConsumer, Spliterator<R> {
647      long holder;
648
649      Splitr(Spliterator.OfLong splitr, long index) {
650        super(splitr, index);
651      }
652
653      @Override
654      public void accept(long t) {
655        this.holder = t;
656      }
657
658      @Override
659      public boolean tryAdvance(Consumer<? super R> action) {
660        if (fromSpliterator.tryAdvance(this)) {
661          action.accept(function.apply(holder, index++));
662          return true;
663        }
664        return false;
665      }
666
667      @Override
668      Splitr createSplit(Spliterator.OfLong from, long i) {
669        return new Splitr(from, i);
670      }
671    }
672    return StreamSupport.stream(new Splitr(fromSpliterator, 0), isParallel).onClose(stream::close);
673  }
674
675  /**
676   * Returns a stream consisting of the results of applying the given function to the elements of
677   * {@code stream} and their indexes in the stream. For example,
678   *
679   * <pre>{@code
680   * mapWithIndex(
681   *     DoubleStream.of(0.0, 1.0, 2.0)
682   *     (e, index) -> index + ":" + e)
683   * }</pre>
684   *
685   * <p>...would return {@code Stream.of("0:0.0", "1:1.0", "2:2.0")}.
686   *
687   * <p>The resulting stream is <a
688   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
689   * if and only if {@code stream} was efficiently splittable and its underlying spliterator
690   * reported {@link Spliterator#SUBSIZED}. This is generally the case if the underlying stream
691   * comes from a data structure supporting efficient indexed random access, typically an array or
692   * list.
693   *
694   * <p>The order of the resulting stream is defined if and only if the order of the original stream
695   * was defined.
696   */
697  public static <R extends @Nullable Object> Stream<R> mapWithIndex(
698      DoubleStream stream, DoubleFunctionWithIndex<R> function) {
699    checkNotNull(stream);
700    checkNotNull(function);
701    boolean isParallel = stream.isParallel();
702    Spliterator.OfDouble fromSpliterator = stream.spliterator();
703
704    if (!fromSpliterator.hasCharacteristics(Spliterator.SUBSIZED)) {
705      PrimitiveIterator.OfDouble fromIterator = Spliterators.iterator(fromSpliterator);
706      return StreamSupport.stream(
707              new AbstractSpliterator<R>(
708                  fromSpliterator.estimateSize(),
709                  fromSpliterator.characteristics() & (Spliterator.ORDERED | Spliterator.SIZED)) {
710                long index = 0;
711
712                @Override
713                public boolean tryAdvance(Consumer<? super R> action) {
714                  if (fromIterator.hasNext()) {
715                    action.accept(function.apply(fromIterator.nextDouble(), index++));
716                    return true;
717                  }
718                  return false;
719                }
720              },
721              isParallel)
722          .onClose(stream::close);
723    }
724    class Splitr extends MapWithIndexSpliterator<Spliterator.OfDouble, R, Splitr>
725        implements DoubleConsumer, Spliterator<R> {
726      double holder;
727
728      Splitr(Spliterator.OfDouble splitr, long index) {
729        super(splitr, index);
730      }
731
732      @Override
733      public void accept(double t) {
734        this.holder = t;
735      }
736
737      @Override
738      public boolean tryAdvance(Consumer<? super R> action) {
739        if (fromSpliterator.tryAdvance(this)) {
740          action.accept(function.apply(holder, index++));
741          return true;
742        }
743        return false;
744      }
745
746      @Override
747      Splitr createSplit(Spliterator.OfDouble from, long i) {
748        return new Splitr(from, i);
749      }
750    }
751    return StreamSupport.stream(new Splitr(fromSpliterator, 0), isParallel).onClose(stream::close);
752  }
753
754  /**
755   * An analogue of {@link java.util.function.Function} also accepting an index.
756   *
757   * <p>This interface is only intended for use by callers of {@link #mapWithIndex(Stream,
758   * FunctionWithIndex)}.
759   *
760   * @since 21.0
761   */
762  public interface FunctionWithIndex<T extends @Nullable Object, R extends @Nullable Object> {
763    /** Applies this function to the given argument and its index within a stream. */
764    @ParametricNullness
765    R apply(@ParametricNullness T from, long index);
766  }
767
768  private abstract static class MapWithIndexSpliterator<
769          F extends Spliterator<?>,
770          R extends @Nullable Object,
771          S extends MapWithIndexSpliterator<F, R, S>>
772      implements Spliterator<R> {
773    final F fromSpliterator;
774    long index;
775
776    MapWithIndexSpliterator(F fromSpliterator, long index) {
777      this.fromSpliterator = fromSpliterator;
778      this.index = index;
779    }
780
781    abstract S createSplit(F from, long i);
782
783    @Override
784    @CheckForNull
785    public S trySplit() {
786      Spliterator<?> splitOrNull = fromSpliterator.trySplit();
787      if (splitOrNull == null) {
788        return null;
789      }
790      @SuppressWarnings("unchecked")
791      F split = (F) splitOrNull;
792      S result = createSplit(split, index);
793      this.index += split.getExactSizeIfKnown();
794      return result;
795    }
796
797    @Override
798    public long estimateSize() {
799      return fromSpliterator.estimateSize();
800    }
801
802    @Override
803    public int characteristics() {
804      return fromSpliterator.characteristics()
805          & (Spliterator.ORDERED | Spliterator.SIZED | Spliterator.SUBSIZED);
806    }
807  }
808
809  /**
810   * An analogue of {@link java.util.function.IntFunction} also accepting an index.
811   *
812   * <p>This interface is only intended for use by callers of {@link #mapWithIndex(IntStream,
813   * IntFunctionWithIndex)}.
814   *
815   * @since 21.0
816   */
817  public interface IntFunctionWithIndex<R extends @Nullable Object> {
818    /** Applies this function to the given argument and its index within a stream. */
819    @ParametricNullness
820    R apply(int from, long index);
821  }
822
823  /**
824   * An analogue of {@link java.util.function.LongFunction} also accepting an index.
825   *
826   * <p>This interface is only intended for use by callers of {@link #mapWithIndex(LongStream,
827   * LongFunctionWithIndex)}.
828   *
829   * @since 21.0
830   */
831  public interface LongFunctionWithIndex<R extends @Nullable Object> {
832    /** Applies this function to the given argument and its index within a stream. */
833    @ParametricNullness
834    R apply(long from, long index);
835  }
836
837  /**
838   * An analogue of {@link java.util.function.DoubleFunction} also accepting an index.
839   *
840   * <p>This interface is only intended for use by callers of {@link #mapWithIndex(DoubleStream,
841   * DoubleFunctionWithIndex)}.
842   *
843   * @since 21.0
844   */
845  public interface DoubleFunctionWithIndex<R extends @Nullable Object> {
846    /** Applies this function to the given argument and its index within a stream. */
847    @ParametricNullness
848    R apply(double from, long index);
849  }
850
851  /**
852   * Returns the last element of the specified stream, or {@link java.util.Optional#empty} if the
853   * stream is empty.
854   *
855   * <p>Equivalent to {@code stream.reduce((a, b) -> b)}, but may perform significantly better. This
856   * method's runtime will be between O(log n) and O(n), performing better on <a
857   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
858   * streams.
859   *
860   * <p>If the stream has nondeterministic order, this has equivalent semantics to {@link
861   * Stream#findAny} (which you might as well use).
862   *
863   * @see Stream#findFirst()
864   * @throws NullPointerException if the last element of the stream is null
865   */
866  /*
867   * By declaring <T> instead of <T extends @Nullable Object>, we declare this method as requiring a
868   * stream whose elements are non-null. However, the method goes out of its way to still handle
869   * nulls in the stream. This means that the method can safely be used with a stream that contains
870   * nulls as long as the *last* element is *not* null.
871   *
872   * (To "go out of its way," the method tracks a `set` bit so that it can distinguish "the final
873   * split has a last element of null, so throw NPE" from "the final split was empty, so look for an
874   * element in the prior one.")
875   */
876  public static <T> java.util.Optional<T> findLast(Stream<T> stream) {
877    class OptionalState {
878      boolean set = false;
879      @CheckForNull T value = null;
880
881      void set(T value) {
882        this.set = true;
883        this.value = value;
884      }
885
886      T get() {
887        /*
888         * requireNonNull is safe because we call get() only if we've previously called set().
889         *
890         * (For further discussion of nullness, see the comment above the method.)
891         */
892        return requireNonNull(value);
893      }
894    }
895    OptionalState state = new OptionalState();
896
897    Deque<Spliterator<T>> splits = new ArrayDeque<>();
898    splits.addLast(stream.spliterator());
899
900    while (!splits.isEmpty()) {
901      Spliterator<T> spliterator = splits.removeLast();
902
903      if (spliterator.getExactSizeIfKnown() == 0) {
904        continue; // drop this split
905      }
906
907      // Many spliterators will have trySplits that are SUBSIZED even if they are not themselves
908      // SUBSIZED.
909      if (spliterator.hasCharacteristics(Spliterator.SUBSIZED)) {
910        // we can drill down to exactly the smallest nonempty spliterator
911        while (true) {
912          Spliterator<T> prefix = spliterator.trySplit();
913          if (prefix == null || prefix.getExactSizeIfKnown() == 0) {
914            break;
915          } else if (spliterator.getExactSizeIfKnown() == 0) {
916            spliterator = prefix;
917            break;
918          }
919        }
920
921        // spliterator is known to be nonempty now
922        spliterator.forEachRemaining(state::set);
923        return java.util.Optional.of(state.get());
924      }
925
926      Spliterator<T> prefix = spliterator.trySplit();
927      if (prefix == null || prefix.getExactSizeIfKnown() == 0) {
928        // we can't split this any further
929        spliterator.forEachRemaining(state::set);
930        if (state.set) {
931          return java.util.Optional.of(state.get());
932        }
933        // fall back to the last split
934        continue;
935      }
936      splits.addLast(prefix);
937      splits.addLast(spliterator);
938    }
939    return java.util.Optional.empty();
940  }
941
942  /**
943   * Returns the last element of the specified stream, or {@link OptionalInt#empty} if the stream is
944   * empty.
945   *
946   * <p>Equivalent to {@code stream.reduce((a, b) -> b)}, but may perform significantly better. This
947   * method's runtime will be between O(log n) and O(n), performing better on <a
948   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
949   * streams.
950   *
951   * @see IntStream#findFirst()
952   * @throws NullPointerException if the last element of the stream is null
953   */
954  public static OptionalInt findLast(IntStream stream) {
955    // findLast(Stream) does some allocation, so we might as well box some more
956    java.util.Optional<Integer> boxedLast = findLast(stream.boxed());
957    return boxedLast.map(OptionalInt::of).orElse(OptionalInt.empty());
958  }
959
960  /**
961   * Returns the last element of the specified stream, or {@link OptionalLong#empty} if the stream
962   * is empty.
963   *
964   * <p>Equivalent to {@code stream.reduce((a, b) -> b)}, but may perform significantly better. This
965   * method's runtime will be between O(log n) and O(n), performing better on <a
966   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
967   * streams.
968   *
969   * @see LongStream#findFirst()
970   * @throws NullPointerException if the last element of the stream is null
971   */
972  public static OptionalLong findLast(LongStream stream) {
973    // findLast(Stream) does some allocation, so we might as well box some more
974    java.util.Optional<Long> boxedLast = findLast(stream.boxed());
975    return boxedLast.map(OptionalLong::of).orElse(OptionalLong.empty());
976  }
977
978  /**
979   * Returns the last element of the specified stream, or {@link OptionalDouble#empty} if the stream
980   * is empty.
981   *
982   * <p>Equivalent to {@code stream.reduce((a, b) -> b)}, but may perform significantly better. This
983   * method's runtime will be between O(log n) and O(n), performing better on <a
984   * href="http://gee.cs.oswego.edu/dl/html/StreamParallelGuidance.html">efficiently splittable</a>
985   * streams.
986   *
987   * @see DoubleStream#findFirst()
988   * @throws NullPointerException if the last element of the stream is null
989   */
990  public static OptionalDouble findLast(DoubleStream stream) {
991    // findLast(Stream) does some allocation, so we might as well box some more
992    java.util.Optional<Double> boxedLast = findLast(stream.boxed());
993    return boxedLast.map(OptionalDouble::of).orElse(OptionalDouble.empty());
994  }
995
996  private Streams() {}
997}