001/*
002 * Copyright (C) 2008 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.collect;
016
017import static com.google.common.base.Preconditions.checkNotNull;
018
019import com.google.common.annotations.GwtCompatible;
020import com.google.common.annotations.GwtIncompatible;
021import com.google.common.base.Function;
022import com.google.common.base.Joiner;
023import com.google.common.base.Optional;
024import com.google.common.base.Predicate;
025import com.google.errorprone.annotations.CanIgnoreReturnValue;
026import com.google.errorprone.annotations.InlineMe;
027import java.util.Arrays;
028import java.util.Collection;
029import java.util.Collections;
030import java.util.Comparator;
031import java.util.Iterator;
032import java.util.List;
033import java.util.SortedSet;
034import javax.annotation.CheckForNull;
035import org.checkerframework.checker.nullness.qual.NonNull;
036import org.checkerframework.checker.nullness.qual.Nullable;
037
038/**
039 * An expanded {@code Iterable} API, providing functionality similar to Java 8's powerful <a href=
040 * "https://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html#package.description"
041 * >streams library</a> in a slightly different way.
042 *
043 * <p>The following types of methods are provided:
044 *
045 * <ul>
046 *   <li>chaining methods which return a new {@code FluentIterable} based in some way on the
047 *       contents of the current one (for example {@link #transform})
048 *   <li>element extraction methods which facilitate the retrieval of certain elements (for example
049 *       {@link #last})
050 *   <li>query methods which answer questions about the {@code FluentIterable}'s contents (for
051 *       example {@link #anyMatch})
052 *   <li>conversion methods which copy the {@code FluentIterable}'s contents into a new collection
053 *       or array (for example {@link #toList})
054 * </ul>
055 *
056 * <p>Several lesser-used features are currently available only as static methods on the {@link
057 * Iterables} class.
058 *
059 * <p><a id="streams"></a>
060 *
061 * <h3>Comparison to streams</h3>
062 *
063 * <p>Starting with Java 8, the core Java class libraries provide a new "Streams" library (in {@code
064 * java.util.stream}), which is similar to {@code FluentIterable} but generally more powerful. Key
065 * differences include:
066 *
067 * <ul>
068 *   <li>A stream is <i>single-use</i>; it becomes invalid as soon as any "terminal operation" such
069 *       as {@code findFirst()} or {@code iterator()} is invoked. (Even though {@code Stream}
070 *       contains all the right method <i>signatures</i> to implement {@link Iterable}, it does not
071 *       actually do so, to avoid implying repeat-iterability.) {@code FluentIterable}, on the other
072 *       hand, is multiple-use, and does implement {@link Iterable}.
073 *   <li>Streams offer many features not found here, including {@code min/max}, {@code distinct},
074 *       {@code reduce}, {@code sorted}, the very powerful {@code collect}, and built-in support for
075 *       parallelizing stream operations.
076 *   <li>{@code FluentIterable} contains several features not available on {@code Stream}, which are
077 *       noted in the method descriptions below.
078 *   <li>Streams include primitive-specialized variants such as {@code IntStream}, the use of which
079 *       is strongly recommended.
080 *   <li>Streams are standard Java, not requiring a third-party dependency (but do render your code
081 *       incompatible with Java 7 and earlier).
082 * </ul>
083 *
084 * <h3>Example</h3>
085 *
086 * <p>Here is an example that accepts a list from a database call, filters it based on a predicate,
087 * transforms it by invoking {@code toString()} on each element, and returns the first 10 elements
088 * as a {@code List}:
089 *
090 * <pre>{@code
091 * ImmutableList<String> results =
092 *     FluentIterable.from(database.getClientList())
093 *         .filter(Client::isActiveInLastMonth)
094 *         .transform(Object::toString)
095 *         .limit(10)
096 *         .toList();
097 * }</pre>
098 *
099 * The approximate stream equivalent is:
100 *
101 * <pre>{@code
102 * List<String> results =
103 *     database.getClientList()
104 *         .stream()
105 *         .filter(Client::isActiveInLastMonth)
106 *         .map(Object::toString)
107 *         .limit(10)
108 *         .collect(Collectors.toList());
109 * }</pre>
110 *
111 * @author Marcin Mikosik
112 * @since 12.0
113 */
114@GwtCompatible(emulated = true)
115@ElementTypesAreNonnullByDefault
116public abstract class FluentIterable<E extends @Nullable Object> implements Iterable<E> {
117  // We store 'iterable' and use it instead of 'this' to allow Iterables to perform instanceof
118  // checks on the _original_ iterable when FluentIterable.from is used.
119  // To avoid a self retain cycle under j2objc, we store Optional.absent() instead of
120  // Optional.of(this). To access the delegate iterable, call #getDelegate(), which converts to
121  // absent() back to 'this'.
122  private final Optional<Iterable<E>> iterableDelegate;
123
124  /** Constructor for use by subclasses. */
125  protected FluentIterable() {
126    this.iterableDelegate = Optional.absent();
127  }
128
129  FluentIterable(Iterable<E> iterable) {
130    this.iterableDelegate = Optional.of(iterable);
131  }
132
133  private Iterable<E> getDelegate() {
134    return iterableDelegate.or(this);
135  }
136
137  /**
138   * Returns a fluent iterable that wraps {@code iterable}, or {@code iterable} itself if it is
139   * already a {@code FluentIterable}.
140   *
141   * <p><b>{@code Stream} equivalent:</b> {@code iterable.stream()} if {@code iterable} is a {@link
142   * Collection}; {@code StreamSupport.stream(iterable.spliterator(), false)} otherwise.
143   */
144  public static <E extends @Nullable Object> FluentIterable<E> from(final Iterable<E> iterable) {
145    return (iterable instanceof FluentIterable)
146        ? (FluentIterable<E>) iterable
147        : new FluentIterable<E>(iterable) {
148          @Override
149          public Iterator<E> iterator() {
150            return iterable.iterator();
151          }
152        };
153  }
154
155  /**
156   * Returns a fluent iterable containing {@code elements} in the specified order.
157   *
158   * <p>The returned iterable is an unmodifiable view of the input array.
159   *
160   * <p><b>{@code Stream} equivalent:</b> {@link java.util.stream.Stream#of(Object[])
161   * Stream.of(T...)}.
162   *
163   * @since 20.0 (since 18.0 as an overload of {@code of})
164   */
165  public static <E extends @Nullable Object> FluentIterable<E> from(E[] elements) {
166    return from(Arrays.asList(elements));
167  }
168
169  /**
170   * Construct a fluent iterable from another fluent iterable. This is obviously never necessary,
171   * but is intended to help call out cases where one migration from {@code Iterable} to {@code
172   * FluentIterable} has obviated the need to explicitly convert to a {@code FluentIterable}.
173   *
174   * @deprecated instances of {@code FluentIterable} don't need to be converted to {@code
175   *     FluentIterable}
176   */
177  @Deprecated
178  @InlineMe(
179      replacement = "checkNotNull(iterable)",
180      staticImports = {"com.google.common.base.Preconditions.checkNotNull"})
181  public static <E extends @Nullable Object> FluentIterable<E> from(FluentIterable<E> iterable) {
182    return checkNotNull(iterable);
183  }
184
185  /**
186   * Returns a fluent iterable that combines two iterables. The returned iterable has an iterator
187   * that traverses the elements in {@code a}, followed by the elements in {@code b}. The source
188   * iterators are not polled until necessary.
189   *
190   * <p>The returned iterable's iterator supports {@code remove()} when the corresponding input
191   * iterator supports it.
192   *
193   * <p><b>{@code Stream} equivalent:</b> {@link Stream#concat}.
194   *
195   * @since 20.0
196   */
197  public static <T extends @Nullable Object> FluentIterable<T> concat(
198      Iterable<? extends T> a, Iterable<? extends T> b) {
199    return concatNoDefensiveCopy(a, b);
200  }
201
202  /**
203   * Returns a fluent iterable that combines three iterables. The returned iterable has an iterator
204   * that traverses the elements in {@code a}, followed by the elements in {@code b}, followed by
205   * the elements in {@code c}. The source iterators are not polled until necessary.
206   *
207   * <p>The returned iterable's iterator supports {@code remove()} when the corresponding input
208   * iterator supports it.
209   *
210   * <p><b>{@code Stream} equivalent:</b> use nested calls to {@link Stream#concat}, or see the
211   * advice in {@link #concat(Iterable...)}.
212   *
213   * @since 20.0
214   */
215  public static <T extends @Nullable Object> FluentIterable<T> concat(
216      Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c) {
217    return concatNoDefensiveCopy(a, b, c);
218  }
219
220  /**
221   * Returns a fluent iterable that combines four iterables. The returned iterable has an iterator
222   * that traverses the elements in {@code a}, followed by the elements in {@code b}, followed by
223   * the elements in {@code c}, followed by the elements in {@code d}. The source iterators are not
224   * polled until necessary.
225   *
226   * <p>The returned iterable's iterator supports {@code remove()} when the corresponding input
227   * iterator supports it.
228   *
229   * <p><b>{@code Stream} equivalent:</b> use nested calls to {@link Stream#concat}, or see the
230   * advice in {@link #concat(Iterable...)}.
231   *
232   * @since 20.0
233   */
234  public static <T extends @Nullable Object> FluentIterable<T> concat(
235      Iterable<? extends T> a,
236      Iterable<? extends T> b,
237      Iterable<? extends T> c,
238      Iterable<? extends T> d) {
239    return concatNoDefensiveCopy(a, b, c, d);
240  }
241
242  /**
243   * Returns a fluent iterable that combines several iterables. The returned iterable has an
244   * iterator that traverses the elements of each iterable in {@code inputs}. The input iterators
245   * are not polled until necessary.
246   *
247   * <p>The returned iterable's iterator supports {@code remove()} when the corresponding input
248   * iterator supports it.
249   *
250   * <p><b>{@code Stream} equivalent:</b> to concatenate an arbitrary number of streams, use {@code
251   * Stream.of(stream1, stream2, ...).flatMap(s -> s)}. If the sources are iterables, use {@code
252   * Stream.of(iter1, iter2, ...).flatMap(Streams::stream)}.
253   *
254   * @throws NullPointerException if any of the provided iterables is {@code null}
255   * @since 20.0
256   */
257  @SafeVarargs
258  public static <T extends @Nullable Object> FluentIterable<T> concat(
259      Iterable<? extends T>... inputs) {
260    return concatNoDefensiveCopy(Arrays.copyOf(inputs, inputs.length));
261  }
262
263  /**
264   * Returns a fluent iterable that combines several iterables. The returned iterable has an
265   * iterator that traverses the elements of each iterable in {@code inputs}. The input iterators
266   * are not polled until necessary.
267   *
268   * <p>The returned iterable's iterator supports {@code remove()} when the corresponding input
269   * iterator supports it. The methods of the returned iterable may throw {@code
270   * NullPointerException} if any of the input iterators is {@code null}.
271   *
272   * <p><b>{@code Stream} equivalent:</b> {@code streamOfStreams.flatMap(s -> s)} or {@code
273   * streamOfIterables.flatMap(Streams::stream)}. (See {@link Streams#stream}.)
274   *
275   * @since 20.0
276   */
277  public static <T extends @Nullable Object> FluentIterable<T> concat(
278      final Iterable<? extends Iterable<? extends T>> inputs) {
279    checkNotNull(inputs);
280    return new FluentIterable<T>() {
281      @Override
282      public Iterator<T> iterator() {
283        return Iterators.concat(Iterators.transform(inputs.iterator(), Iterable::iterator));
284      }
285    };
286  }
287
288  /** Concatenates a varargs array of iterables without making a defensive copy of the array. */
289  private static <T extends @Nullable Object> FluentIterable<T> concatNoDefensiveCopy(
290      final Iterable<? extends T>... inputs) {
291    for (Iterable<? extends T> input : inputs) {
292      checkNotNull(input);
293    }
294    return new FluentIterable<T>() {
295      @Override
296      public Iterator<T> iterator() {
297        return Iterators.concat(
298            /* lazily generate the iterators on each input only as needed */
299            new AbstractIndexedListIterator<Iterator<? extends T>>(inputs.length) {
300              @Override
301              public Iterator<? extends T> get(int i) {
302                return inputs[i].iterator();
303              }
304            });
305      }
306    };
307  }
308
309  /**
310   * Returns a fluent iterable containing no elements.
311   *
312   * <p><b>{@code Stream} equivalent:</b> {@code Stream.empty()}.
313   *
314   * @since 20.0
315   */
316  public static <E extends @Nullable Object> FluentIterable<E> of() {
317    return FluentIterable.from(Collections.<E>emptyList());
318  }
319
320  /**
321   * Returns a fluent iterable containing the specified elements in order.
322   *
323   * <p><b>{@code Stream} equivalent:</b> {@link java.util.stream.Stream#of(Object[])
324   * Stream.of(T...)}.
325   *
326   * @since 20.0
327   */
328  public static <E extends @Nullable Object> FluentIterable<E> of(
329      @ParametricNullness E element, E... elements) {
330    return from(Lists.asList(element, elements));
331  }
332
333  /**
334   * Returns a string representation of this fluent iterable, with the format {@code [e1, e2, ...,
335   * en]}.
336   *
337   * <p><b>{@code Stream} equivalent:</b> {@code stream.collect(Collectors.joining(", ", "[", "]"))}
338   * or (less efficiently) {@code stream.collect(Collectors.toList()).toString()}.
339   */
340  @Override
341  public String toString() {
342    return Iterables.toString(getDelegate());
343  }
344
345  /**
346   * Returns the number of elements in this fluent iterable.
347   *
348   * <p><b>{@code Stream} equivalent:</b> {@code stream.count()}.
349   */
350  public final int size() {
351    return Iterables.size(getDelegate());
352  }
353
354  /**
355   * Returns {@code true} if this fluent iterable contains any object for which {@code
356   * equals(target)} is true.
357   *
358   * <p><b>{@code Stream} equivalent:</b> {@code stream.anyMatch(Predicate.isEqual(target))}.
359   */
360  public final boolean contains(@CheckForNull Object target) {
361    return Iterables.contains(getDelegate(), target);
362  }
363
364  /**
365   * Returns a fluent iterable whose {@code Iterator} cycles indefinitely over the elements of this
366   * fluent iterable.
367   *
368   * <p>That iterator supports {@code remove()} if {@code iterable.iterator()} does. After {@code
369   * remove()} is called, subsequent cycles omit the removed element, which is no longer in this
370   * fluent iterable. The iterator's {@code hasNext()} method returns {@code true} until this fluent
371   * iterable is empty.
372   *
373   * <p><b>Warning:</b> Typical uses of the resulting iterator may produce an infinite loop. You
374   * should use an explicit {@code break} or be certain that you will eventually remove all the
375   * elements.
376   *
377   * <p><b>{@code Stream} equivalent:</b> if the source iterable has only a single element {@code
378   * e}, use {@code Stream.generate(() -> e)}. Otherwise, collect your stream into a collection and
379   * use {@code Stream.generate(() -> collection).flatMap(Collection::stream)}.
380   */
381  public final FluentIterable<E> cycle() {
382    return from(Iterables.cycle(getDelegate()));
383  }
384
385  /**
386   * Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable,
387   * followed by those of {@code other}. The iterators are not polled until necessary.
388   *
389   * <p>The returned iterable's {@code Iterator} supports {@code remove()} when the corresponding
390   * {@code Iterator} supports it.
391   *
392   * <p><b>{@code Stream} equivalent:</b> {@link Stream#concat}.
393   *
394   * @since 18.0
395   */
396  public final FluentIterable<E> append(Iterable<? extends E> other) {
397    return FluentIterable.concat(getDelegate(), other);
398  }
399
400  /**
401   * Returns a fluent iterable whose iterators traverse first the elements of this fluent iterable,
402   * followed by {@code elements}.
403   *
404   * <p><b>{@code Stream} equivalent:</b> {@code Stream.concat(thisStream, Stream.of(elements))}.
405   *
406   * @since 18.0
407   */
408  public final FluentIterable<E> append(E... elements) {
409    return FluentIterable.concat(getDelegate(), Arrays.asList(elements));
410  }
411
412  /**
413   * Returns the elements from this fluent iterable that satisfy a predicate. The resulting fluent
414   * iterable's iterator does not support {@code remove()}.
415   *
416   * <p><b>{@code Stream} equivalent:</b> {@link Stream#filter} (same).
417   */
418  public final FluentIterable<E> filter(Predicate<? super E> predicate) {
419    return from(Iterables.filter(getDelegate(), predicate));
420  }
421
422  /**
423   * Returns the elements from this fluent iterable that are instances of class {@code type}.
424   *
425   * <p><b>{@code Stream} equivalent:</b> {@code stream.filter(type::isInstance).map(type::cast)}.
426   * This does perform a little more work than necessary, so another option is to insert an
427   * unchecked cast at some later point:
428   *
429   * <pre>
430   * {@code @SuppressWarnings("unchecked") // safe because of ::isInstance check
431   * ImmutableList<NewType> result =
432   *     (ImmutableList) stream.filter(NewType.class::isInstance).collect(toImmutableList());}
433   * </pre>
434   */
435  @GwtIncompatible // Class.isInstance
436  public final <T> FluentIterable<T> filter(Class<T> type) {
437    return from(Iterables.filter(getDelegate(), type));
438  }
439
440  /**
441   * Returns {@code true} if any element in this fluent iterable satisfies the predicate.
442   *
443   * <p><b>{@code Stream} equivalent:</b> {@link Stream#anyMatch} (same).
444   */
445  public final boolean anyMatch(Predicate<? super E> predicate) {
446    return Iterables.any(getDelegate(), predicate);
447  }
448
449  /**
450   * Returns {@code true} if every element in this fluent iterable satisfies the predicate. If this
451   * fluent iterable is empty, {@code true} is returned.
452   *
453   * <p><b>{@code Stream} equivalent:</b> {@link Stream#allMatch} (same).
454   */
455  public final boolean allMatch(Predicate<? super E> predicate) {
456    return Iterables.all(getDelegate(), predicate);
457  }
458
459  /**
460   * Returns an {@link Optional} containing the first element in this fluent iterable that satisfies
461   * the given predicate, if such an element exists.
462   *
463   * <p><b>Warning:</b> avoid using a {@code predicate} that matches {@code null}. If {@code null}
464   * is matched in this fluent iterable, a {@link NullPointerException} will be thrown.
465   *
466   * <p><b>{@code Stream} equivalent:</b> {@code stream.filter(predicate).findFirst()}.
467   */
468  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
469  public final Optional<@NonNull E> firstMatch(Predicate<? super E> predicate) {
470    return Iterables.<E>tryFind((Iterable<@NonNull E>) getDelegate(), predicate);
471  }
472
473  /**
474   * Returns a fluent iterable that applies {@code function} to each element of this fluent
475   * iterable.
476   *
477   * <p>The returned fluent iterable's iterator supports {@code remove()} if this iterable's
478   * iterator does. After a successful {@code remove()} call, this fluent iterable no longer
479   * contains the corresponding element.
480   *
481   * <p><b>{@code Stream} equivalent:</b> {@link Stream#map}.
482   */
483  public final <T extends @Nullable Object> FluentIterable<T> transform(
484      Function<? super E, T> function) {
485    return from(Iterables.transform(getDelegate(), function));
486  }
487
488  /**
489   * Applies {@code function} to each element of this fluent iterable and returns a fluent iterable
490   * with the concatenated combination of results. {@code function} returns an Iterable of results.
491   *
492   * <p>The returned fluent iterable's iterator supports {@code remove()} if this function-returned
493   * iterables' iterator does. After a successful {@code remove()} call, the returned fluent
494   * iterable no longer contains the corresponding element.
495   *
496   * <p><b>{@code Stream} equivalent:</b> {@link Stream#flatMap} (using a function that produces
497   * streams, not iterables).
498   *
499   * @since 13.0 (required {@code Function<E, Iterable<T>>} until 14.0)
500   */
501  public <T extends @Nullable Object> FluentIterable<T> transformAndConcat(
502      Function<? super E, ? extends Iterable<? extends T>> function) {
503    return FluentIterable.concat(transform(function));
504  }
505
506  /**
507   * Returns an {@link Optional} containing the first element in this fluent iterable. If the
508   * iterable is empty, {@code Optional.absent()} is returned.
509   *
510   * <p><b>{@code Stream} equivalent:</b> if the goal is to obtain any element, {@link
511   * Stream#findAny}; if it must specifically be the <i>first</i> element, {@code Stream#findFirst}.
512   *
513   * @throws NullPointerException if the first element is null; if this is a possibility, use {@code
514   *     iterator().next()} or {@link Iterables#getFirst} instead.
515   */
516  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
517  public final Optional<@NonNull E> first() {
518    Iterator<E> iterator = getDelegate().iterator();
519    return iterator.hasNext() ? Optional.of(iterator.next()) : Optional.absent();
520  }
521
522  /**
523   * Returns an {@link Optional} containing the last element in this fluent iterable. If the
524   * iterable is empty, {@code Optional.absent()} is returned. If the underlying {@code iterable} is
525   * a {@link List} with {@link java.util.RandomAccess} support, then this operation is guaranteed
526   * to be {@code O(1)}.
527   *
528   * <p><b>{@code Stream} equivalent:</b> {@code stream.reduce((a, b) -> b)}.
529   *
530   * @throws NullPointerException if the last element is null; if this is a possibility, use {@link
531   *     Iterables#getLast} instead.
532   */
533  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
534  public final Optional<@NonNull E> last() {
535    // Iterables#getLast was inlined here so we don't have to throw/catch a NSEE
536
537    // TODO(kevinb): Support a concurrently modified collection?
538    Iterable<E> iterable = getDelegate();
539    if (iterable instanceof List) {
540      List<E> list = (List<E>) iterable;
541      if (list.isEmpty()) {
542        return Optional.absent();
543      }
544      return Optional.of(list.get(list.size() - 1));
545    }
546    Iterator<E> iterator = iterable.iterator();
547    if (!iterator.hasNext()) {
548      return Optional.absent();
549    }
550
551    /*
552     * TODO(kevinb): consider whether this "optimization" is worthwhile. Users with SortedSets tend
553     * to know they are SortedSets and probably would not call this method.
554     */
555    if (iterable instanceof SortedSet) {
556      SortedSet<E> sortedSet = (SortedSet<E>) iterable;
557      return Optional.of(sortedSet.last());
558    }
559
560    while (true) {
561      E current = iterator.next();
562      if (!iterator.hasNext()) {
563        return Optional.of(current);
564      }
565    }
566  }
567
568  /**
569   * Returns a view of this fluent iterable that skips its first {@code numberToSkip} elements. If
570   * this fluent iterable contains fewer than {@code numberToSkip} elements, the returned fluent
571   * iterable skips all of its elements.
572   *
573   * <p>Modifications to this fluent iterable before a call to {@code iterator()} are reflected in
574   * the returned fluent iterable. That is, the iterator skips the first {@code numberToSkip}
575   * elements that exist when the iterator is created, not when {@code skip()} is called.
576   *
577   * <p>The returned fluent iterable's iterator supports {@code remove()} if the {@code Iterator} of
578   * this fluent iterable supports it. Note that it is <i>not</i> possible to delete the last
579   * skipped element by immediately calling {@code remove()} on the returned fluent iterable's
580   * iterator, as the {@code Iterator} contract states that a call to {@code * remove()} before a
581   * call to {@code next()} will throw an {@link IllegalStateException}.
582   *
583   * <p><b>{@code Stream} equivalent:</b> {@link Stream#skip} (same).
584   */
585  public final FluentIterable<E> skip(int numberToSkip) {
586    return from(Iterables.skip(getDelegate(), numberToSkip));
587  }
588
589  /**
590   * Creates a fluent iterable with the first {@code size} elements of this fluent iterable. If this
591   * fluent iterable does not contain that many elements, the returned fluent iterable will have the
592   * same behavior as this fluent iterable. The returned fluent iterable's iterator supports {@code
593   * remove()} if this fluent iterable's iterator does.
594   *
595   * <p><b>{@code Stream} equivalent:</b> {@link Stream#limit} (same).
596   *
597   * @param maxSize the maximum number of elements in the returned fluent iterable
598   * @throws IllegalArgumentException if {@code size} is negative
599   */
600  public final FluentIterable<E> limit(int maxSize) {
601    return from(Iterables.limit(getDelegate(), maxSize));
602  }
603
604  /**
605   * Determines whether this fluent iterable is empty.
606   *
607   * <p><b>{@code Stream} equivalent:</b> {@code !stream.findAny().isPresent()}.
608   */
609  public final boolean isEmpty() {
610    return !getDelegate().iterator().hasNext();
611  }
612
613  /**
614   * Returns an {@code ImmutableList} containing all of the elements from this fluent iterable in
615   * proper sequence.
616   *
617   * <p><b>{@code Stream} equivalent:</b> {@code ImmutableList.copyOf(stream.iterator())}, or pass
618   * {@link ImmutableList#toImmutableList} to {@code stream.collect()}.
619   *
620   * @throws NullPointerException if any element is {@code null}
621   * @since 14.0 (since 12.0 as {@code toImmutableList()}).
622   */
623  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
624  public final ImmutableList<@NonNull E> toList() {
625    return ImmutableList.copyOf((Iterable<@NonNull E>) getDelegate());
626  }
627
628  /**
629   * Returns an {@code ImmutableList} containing all of the elements from this {@code
630   * FluentIterable} in the order specified by {@code comparator}. To produce an {@code
631   * ImmutableList} sorted by its natural ordering, use {@code toSortedList(Ordering.natural())}.
632   *
633   * <p><b>{@code Stream} equivalent:</b> {@code
634   * ImmutableList.copyOf(stream.sorted(comparator).iterator())}, or pass {@link
635   * ImmutableList#toImmutableList} to {@code stream.sorted(comparator).collect()}.
636   *
637   * @param comparator the function by which to sort list elements
638   * @throws NullPointerException if any element of this iterable is {@code null}
639   * @since 14.0 (since 13.0 as {@code toSortedImmutableList()}).
640   */
641  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
642  public final ImmutableList<@NonNull E> toSortedList(Comparator<? super E> comparator) {
643    return Ordering.from(comparator).immutableSortedCopy((Iterable<@NonNull E>) getDelegate());
644  }
645
646  /**
647   * Returns an {@code ImmutableSet} containing all of the elements from this fluent iterable with
648   * duplicates removed.
649   *
650   * <p><b>{@code Stream} equivalent:</b> {@code ImmutableSet.copyOf(stream.iterator())}, or pass
651   * {@link ImmutableSet#toImmutableSet} to {@code stream.collect()}.
652   *
653   * @throws NullPointerException if any element is {@code null}
654   * @since 14.0 (since 12.0 as {@code toImmutableSet()}).
655   */
656  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
657  public final ImmutableSet<@NonNull E> toSet() {
658    return ImmutableSet.copyOf((Iterable<@NonNull E>) getDelegate());
659  }
660
661  /**
662   * Returns an {@code ImmutableSortedSet} containing all of the elements from this {@code
663   * FluentIterable} in the order specified by {@code comparator}, with duplicates (determined by
664   * {@code comparator.compare(x, y) == 0}) removed. To produce an {@code ImmutableSortedSet} sorted
665   * by its natural ordering, use {@code toSortedSet(Ordering.natural())}.
666   *
667   * <p><b>{@code Stream} equivalent:</b> {@code ImmutableSortedSet.copyOf(comparator,
668   * stream.iterator())}, or pass {@link ImmutableSortedSet#toImmutableSortedSet} to {@code
669   * stream.collect()}.
670   *
671   * @param comparator the function by which to sort set elements
672   * @throws NullPointerException if any element of this iterable is {@code null}
673   * @since 14.0 (since 12.0 as {@code toImmutableSortedSet()}).
674   */
675  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
676  public final ImmutableSortedSet<@NonNull E> toSortedSet(Comparator<? super E> comparator) {
677    return ImmutableSortedSet.copyOf(comparator, (Iterable<@NonNull E>) getDelegate());
678  }
679
680  /**
681   * Returns an {@code ImmutableMultiset} containing all of the elements from this fluent iterable.
682   *
683   * <p><b>{@code Stream} equivalent:</b> {@code ImmutableMultiset.copyOf(stream.iterator())}, or
684   * pass {@link ImmutableMultiset#toImmutableMultiset} to {@code stream.collect()}.
685   *
686   * @throws NullPointerException if any element is null
687   * @since 19.0
688   */
689  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
690  public final ImmutableMultiset<@NonNull E> toMultiset() {
691    return ImmutableMultiset.copyOf((Iterable<@NonNull E>) getDelegate());
692  }
693
694  /**
695   * Returns an immutable map whose keys are the distinct elements of this {@code FluentIterable}
696   * and whose value for each key was computed by {@code valueFunction}. The map's iteration order
697   * is the order of the first appearance of each key in this iterable.
698   *
699   * <p>When there are multiple instances of a key in this iterable, it is unspecified whether
700   * {@code valueFunction} will be applied to more than one instance of that key and, if it is,
701   * which result will be mapped to that key in the returned map.
702   *
703   * <p><b>{@code Stream} equivalent:</b> use {@code stream.collect(ImmutableMap.toImmutableMap(k ->
704   * k, valueFunction))}. {@code ImmutableMap.copyOf(stream.collect(Collectors.toMap(k -> k,
705   * valueFunction)))} behaves similarly, but may not preserve the order of entries.
706   *
707   * @throws NullPointerException if any element of this iterable is {@code null}, or if {@code
708   *     valueFunction} produces {@code null} for any key
709   * @since 14.0
710   */
711  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
712  public final <V> ImmutableMap<@NonNull E, V> toMap(Function<? super E, V> valueFunction) {
713    return Maps.toMap((Iterable<@NonNull E>) getDelegate(), valueFunction);
714  }
715
716  /**
717   * Creates an index {@code ImmutableListMultimap} that contains the results of applying a
718   * specified function to each item in this {@code FluentIterable} of values. Each element of this
719   * iterable will be stored as a value in the resulting multimap, yielding a multimap with the same
720   * size as this iterable. The key used to store that value in the multimap will be the result of
721   * calling the function on that value. The resulting multimap is created as an immutable snapshot.
722   * In the returned multimap, keys appear in the order they are first encountered, and the values
723   * corresponding to each key appear in the same order as they are encountered.
724   *
725   * <p><b>{@code Stream} equivalent:</b> {@code stream.collect(Collectors.groupingBy(keyFunction))}
726   * behaves similarly, but returns a mutable {@code Map<K, List<E>>} instead, and may not preserve
727   * the order of entries.
728   *
729   * @param keyFunction the function used to produce the key for each value
730   * @throws NullPointerException if any element of this iterable is {@code null}, or if {@code
731   *     keyFunction} produces {@code null} for any key
732   * @since 14.0
733   */
734  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
735  public final <K> ImmutableListMultimap<K, @NonNull E> index(Function<? super E, K> keyFunction) {
736    return Multimaps.index((Iterable<@NonNull E>) getDelegate(), keyFunction);
737  }
738
739  /**
740   * Returns a map with the contents of this {@code FluentIterable} as its {@code values}, indexed
741   * by keys derived from those values. In other words, each input value produces an entry in the
742   * map whose key is the result of applying {@code keyFunction} to that value. These entries appear
743   * in the same order as they appeared in this fluent iterable. Example usage:
744   *
745   * <pre>{@code
746   * Color red = new Color("red", 255, 0, 0);
747   * ...
748   * FluentIterable<Color> allColors = FluentIterable.from(ImmutableSet.of(red, green, blue));
749   *
750   * Map<String, Color> colorForName = allColors.uniqueIndex(toStringFunction());
751   * assertThat(colorForName).containsEntry("red", red);
752   * }</pre>
753   *
754   * <p>If your index may associate multiple values with each key, use {@link #index(Function)
755   * index}.
756   *
757   * <p><b>{@code Stream} equivalent:</b> use {@code
758   * stream.collect(ImmutableMap.toImmutableMap(keyFunction, v -> v))}. {@code
759   * ImmutableMap.copyOf(stream.collect(Collectors.toMap(keyFunction, v -> v)))}, but be aware that
760   * this may not preserve the order of entries.
761   *
762   * @param keyFunction the function used to produce the key for each value
763   * @return a map mapping the result of evaluating the function {@code keyFunction} on each value
764   *     in this fluent iterable to that value
765   * @throws IllegalArgumentException if {@code keyFunction} produces the same key for more than one
766   *     value in this fluent iterable
767   * @throws NullPointerException if any element of this iterable is {@code null}, or if {@code
768   *     keyFunction} produces {@code null} for any key
769   * @since 14.0
770   */
771  @SuppressWarnings("nullness") // Unsafe, but we can't do much about it now.
772  public final <K> ImmutableMap<K, @NonNull E> uniqueIndex(Function<? super E, K> keyFunction) {
773    return Maps.uniqueIndex((Iterable<@NonNull E>) getDelegate(), keyFunction);
774  }
775
776  /**
777   * Returns an array containing all of the elements from this fluent iterable in iteration order.
778   *
779   * <p><b>{@code Stream} equivalent:</b> if an object array is acceptable, use {@code
780   * stream.toArray()}; if {@code type} is a class literal such as {@code MyType.class}, use {@code
781   * stream.toArray(MyType[]::new)}. Otherwise use {@code stream.toArray( len -> (E[])
782   * Array.newInstance(type, len))}.
783   *
784   * @param type the type of the elements
785   * @return a newly-allocated array into which all the elements of this fluent iterable have been
786   *     copied
787   */
788  @GwtIncompatible // Array.newArray(Class, int)
789  public final E[] toArray(Class<@NonNull E> type) {
790    return Iterables.<E>toArray(getDelegate(), type);
791  }
792
793  /**
794   * Copies all the elements from this fluent iterable to {@code collection}. This is equivalent to
795   * calling {@code Iterables.addAll(collection, this)}.
796   *
797   * <p><b>{@code Stream} equivalent:</b> {@code stream.forEachOrdered(collection::add)} or {@code
798   * stream.forEach(collection::add)}.
799   *
800   * @param collection the collection to copy elements to
801   * @return {@code collection}, for convenience
802   * @since 14.0
803   */
804  @CanIgnoreReturnValue
805  public final <C extends Collection<? super E>> C copyInto(C collection) {
806    checkNotNull(collection);
807    Iterable<E> iterable = getDelegate();
808    if (iterable instanceof Collection) {
809      collection.addAll((Collection<E>) iterable);
810    } else {
811      for (E item : iterable) {
812        collection.add(item);
813      }
814    }
815    return collection;
816  }
817
818  /**
819   * Returns a {@link String} containing all of the elements of this fluent iterable joined with
820   * {@code joiner}.
821   *
822   * <p><b>{@code Stream} equivalent:</b> {@code joiner.join(stream.iterator())}, or, if you are not
823   * using any optional {@code Joiner} features, {@code
824   * stream.collect(Collectors.joining(delimiter)}.
825   *
826   * @since 18.0
827   */
828  public final String join(Joiner joiner) {
829    return joiner.join(this);
830  }
831
832  /**
833   * Returns the element at the specified position in this fluent iterable.
834   *
835   * <p><b>{@code Stream} equivalent:</b> {@code stream.skip(position).findFirst().get()} (but note
836   * that this throws different exception types, and throws an exception if {@code null} would be
837   * returned).
838   *
839   * @param position position of the element to return
840   * @return the element at the specified position in this fluent iterable
841   * @throws IndexOutOfBoundsException if {@code position} is negative or greater than or equal to
842   *     the size of this fluent iterable
843   */
844  @ParametricNullness
845  public final E get(int position) {
846    return Iterables.get(getDelegate(), position);
847  }
848
849  /** Function that transforms {@code Iterable<E>} into a fluent iterable. */
850  private static class FromIterableFunction<E extends @Nullable Object>
851      implements Function<Iterable<E>, FluentIterable<E>> {
852    @Override
853    public FluentIterable<E> apply(Iterable<E> fromObject) {
854      return FluentIterable.from(fromObject);
855    }
856  }
857}