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