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