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