1090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson/* 21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2007 The Guava Authors 3090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 4090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Licensed under the Apache License, Version 2.0 (the "License"); 5090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * you may not use this file except in compliance with the License. 6090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * You may obtain a copy of the License at 7090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 8090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 9090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 10090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Unless required by applicable law or agreed to in writing, software 11090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 12090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * See the License for the specific language governing permissions and 14090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * limitations under the License. 15090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 16090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 17090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonpackage com.google.common.collect; 18090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport static com.google.common.base.Preconditions.checkArgument; 201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport static com.google.common.base.Preconditions.checkNotNull; 210888a09821a98ac0680fad765217302858e70fa4Paul Duffinimport static com.google.common.collect.CollectPreconditions.checkRemove; 221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.annotations.Beta; 24090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport com.google.common.annotations.GwtCompatible; 25090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport com.google.common.annotations.GwtIncompatible; 26090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport com.google.common.base.Function; 271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.base.Optional; 28090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport com.google.common.base.Predicate; 29090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 30090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Collection; 31090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Collections; 321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.Comparator; 33090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Iterator; 34090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.List; 35090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.NoSuchElementException; 361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport java.util.Queue; 37090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.RandomAccess; 38090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Set; 39090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 40090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport javax.annotation.Nullable; 41090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 42090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson/** 43090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * This class contains static utility methods that operate on or return objects 44090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * of type {@code Iterable}. Except as noted, each method has a corresponding 45090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@link Iterator}-based method in the {@link Iterators} class. 46090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p><i>Performance notes:</i> Unless otherwise noted, all of the iterables 481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * produced in this class are <i>lazy</i>, which means that their iterators 491d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * only advance the backing iteration when absolutely necessary. 501d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 517dd252788645e940eada959bdde927426e2531c9Paul Duffin * <p>See the Guava User Guide article on <a href= 527dd252788645e940eada959bdde927426e2531c9Paul Duffin * "http://code.google.com/p/guava-libraries/wiki/CollectionUtilitiesExplained#Iterables"> 537dd252788645e940eada959bdde927426e2531c9Paul Duffin * {@code Iterables}</a>. 547dd252788645e940eada959bdde927426e2531c9Paul Duffin * 55090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @author Kevin Bourrillion 56090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @author Jared Levy 571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 2.0 (imported from Google Collections Library) 58090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert@GwtCompatible(emulated = true) 60090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonpublic final class Iterables { 61090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson private Iterables() {} 62090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 63090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** Returns an unmodifiable view of {@code iterable}. */ 640888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> unmodifiableIterable( 650888a09821a98ac0680fad765217302858e70fa4Paul Duffin final Iterable<T> iterable) { 66090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(iterable); 670888a09821a98ac0680fad765217302858e70fa4Paul Duffin if (iterable instanceof UnmodifiableIterable || 680888a09821a98ac0680fad765217302858e70fa4Paul Duffin iterable instanceof ImmutableCollection) { 691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return iterable; 701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return new UnmodifiableIterable<T>(iterable); 721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 731d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Simply returns its argument. 761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 771d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @deprecated no need to use this 781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 10.0 791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 800888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Deprecated public static <E> Iterable<E> unmodifiableIterable( 810888a09821a98ac0680fad765217302858e70fa4Paul Duffin ImmutableCollection<E> iterable) { 821d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return checkNotNull(iterable); 831d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 857dd252788645e940eada959bdde927426e2531c9Paul Duffin private static final class UnmodifiableIterable<T> extends FluentIterable<T> { 861d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private final Iterable<T> iterable; 871d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 881d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private UnmodifiableIterable(Iterable<T> iterable) { 891d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert this.iterable = iterable; 901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 920888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 931d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public Iterator<T> iterator() { 941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return Iterators.unmodifiableIterator(iterable.iterator()); 951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 961d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 971d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Override 981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public String toString() { 991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return iterable.toString(); 1001d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 1011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // no equals and hashCode; it would break the contract! 102090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 103090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 104090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 105090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the number of elements in {@code iterable}. 106090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 107090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static int size(Iterable<?> iterable) { 1080888a09821a98ac0680fad765217302858e70fa4Paul Duffin return (iterable instanceof Collection) 1090888a09821a98ac0680fad765217302858e70fa4Paul Duffin ? ((Collection<?>) iterable).size() 1100888a09821a98ac0680fad765217302858e70fa4Paul Duffin : Iterators.size(iterable.iterator()); 111090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 112090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 113090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 1147dd252788645e940eada959bdde927426e2531c9Paul Duffin * Returns {@code true} if {@code iterable} contains any object for which {@code equals(element)} 1157dd252788645e940eada959bdde927426e2531c9Paul Duffin * is true. 116090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 1177dd252788645e940eada959bdde927426e2531c9Paul Duffin public static boolean contains(Iterable<?> iterable, @Nullable Object element) { 118090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if (iterable instanceof Collection) { 119090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson Collection<?> collection = (Collection<?>) iterable; 1207dd252788645e940eada959bdde927426e2531c9Paul Duffin return Collections2.safeContains(collection, element); 121090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 122090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.contains(iterable.iterator(), element); 123090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 124090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 125090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 126090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Removes, from an iterable, every element that belongs to the provided 127090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * collection. 128090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 129090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>This method calls {@link Collection#removeAll} if {@code iterable} is a 130090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * collection, and {@link Iterators#removeAll} otherwise. 131090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 132090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param removeFrom the iterable to (potentially) remove elements from 133090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param elementsToRemove the elements to remove 1341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @return {@code true} if any element was removed from {@code iterable} 135090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 1360888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static boolean removeAll( 1370888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<?> removeFrom, Collection<?> elementsToRemove) { 1380888a09821a98ac0680fad765217302858e70fa4Paul Duffin return (removeFrom instanceof Collection) 1390888a09821a98ac0680fad765217302858e70fa4Paul Duffin ? ((Collection<?>) removeFrom).removeAll(checkNotNull(elementsToRemove)) 1400888a09821a98ac0680fad765217302858e70fa4Paul Duffin : Iterators.removeAll(removeFrom.iterator(), elementsToRemove); 141090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 142090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 143090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 144090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Removes, from an iterable, every element that does not belong to the 145090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * provided collection. 146090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 147090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>This method calls {@link Collection#retainAll} if {@code iterable} is a 148090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * collection, and {@link Iterators#retainAll} otherwise. 149090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 150090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param removeFrom the iterable to (potentially) remove elements from 151090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param elementsToRetain the elements to retain 1521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @return {@code true} if any element was removed from {@code iterable} 153090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 1540888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static boolean retainAll( 1550888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<?> removeFrom, Collection<?> elementsToRetain) { 1560888a09821a98ac0680fad765217302858e70fa4Paul Duffin return (removeFrom instanceof Collection) 1570888a09821a98ac0680fad765217302858e70fa4Paul Duffin ? ((Collection<?>) removeFrom).retainAll(checkNotNull(elementsToRetain)) 1580888a09821a98ac0680fad765217302858e70fa4Paul Duffin : Iterators.retainAll(removeFrom.iterator(), elementsToRetain); 159090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 160090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 161090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 162090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Removes, from an iterable, every element that satisfies the provided 163090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * predicate. 164090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 165090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param removeFrom the iterable to (potentially) remove elements from 166090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param predicate a predicate that determines whether an element should 167090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * be removed 168090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return {@code true} if any elements were removed from the iterable 169090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 170090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws UnsupportedOperationException if the iterable does not support 171090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code remove()}. 1721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 2.0 173090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 1740888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> boolean removeIf( 1750888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<T> removeFrom, Predicate<? super T> predicate) { 176090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if (removeFrom instanceof RandomAccess && removeFrom instanceof List) { 1770888a09821a98ac0680fad765217302858e70fa4Paul Duffin return removeIfFromRandomAccessList( 1780888a09821a98ac0680fad765217302858e70fa4Paul Duffin (List<T>) removeFrom, checkNotNull(predicate)); 179090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 180090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.removeIf(removeFrom.iterator(), predicate); 181090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 182090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 1830888a09821a98ac0680fad765217302858e70fa4Paul Duffin private static <T> boolean removeIfFromRandomAccessList( 1840888a09821a98ac0680fad765217302858e70fa4Paul Duffin List<T> list, Predicate<? super T> predicate) { 1851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // Note: Not all random access lists support set() so we need to deal with 1861d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // those that don't and attempt the slower remove() based solution. 187090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson int from = 0; 188090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson int to = 0; 189090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 190090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson for (; from < list.size(); from++) { 191090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson T element = list.get(from); 192090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if (!predicate.apply(element)) { 193090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if (from > to) { 1941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert try { 1951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert list.set(to, element); 1961d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } catch (UnsupportedOperationException e) { 1971d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert slowRemoveIfForRemainingElements(list, predicate, to, from); 1981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return true; 1991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 200090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 201090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson to++; 202090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 203090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 204090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 205090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson // Clear the tail of any remaining items 2061d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert list.subList(to, list.size()).clear(); 207090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return from != to; 208090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 209090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 2101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private static <T> void slowRemoveIfForRemainingElements(List<T> list, 2111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert Predicate<? super T> predicate, int to, int from) { 2121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // Here we know that: 2131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // * (to < from) and that both are valid indices. 2141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // * Everything with (index < to) should be kept. 2151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // * Everything with (to <= index < from) should be removed. 2161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // * The element with (index == from) should be kept. 2171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // * Everything with (index > from) has not been checked yet. 2181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 2191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // Check from the end of the list backwards (minimize expected cost of 2201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // moving elements when remove() is called). Stop before 'from' because 2211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // we already know that should be kept. 2221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert for (int n = list.size() - 1; n > from; n--) { 2231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert if (predicate.apply(list.get(n))) { 2241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert list.remove(n); 2251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 2261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 2271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // And now remove everything in the range [to, from) (going backwards). 2281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert for (int n = from - 1; n >= to; n--) { 2291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert list.remove(n); 2301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 2311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 2321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 233090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 2340888a09821a98ac0680fad765217302858e70fa4Paul Duffin * Removes and returns the first matching element, or returns {@code null} if there is none. 2350888a09821a98ac0680fad765217302858e70fa4Paul Duffin */ 2360888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Nullable 2370888a09821a98ac0680fad765217302858e70fa4Paul Duffin static <T> T removeFirstMatching(Iterable<T> removeFrom, Predicate<? super T> predicate) { 2380888a09821a98ac0680fad765217302858e70fa4Paul Duffin checkNotNull(predicate); 2390888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterator<T> iterator = removeFrom.iterator(); 2400888a09821a98ac0680fad765217302858e70fa4Paul Duffin while (iterator.hasNext()) { 2410888a09821a98ac0680fad765217302858e70fa4Paul Duffin T next = iterator.next(); 2420888a09821a98ac0680fad765217302858e70fa4Paul Duffin if (predicate.apply(next)) { 2430888a09821a98ac0680fad765217302858e70fa4Paul Duffin iterator.remove(); 2440888a09821a98ac0680fad765217302858e70fa4Paul Duffin return next; 2450888a09821a98ac0680fad765217302858e70fa4Paul Duffin } 2460888a09821a98ac0680fad765217302858e70fa4Paul Duffin } 2470888a09821a98ac0680fad765217302858e70fa4Paul Duffin return null; 2480888a09821a98ac0680fad765217302858e70fa4Paul Duffin } 2490888a09821a98ac0680fad765217302858e70fa4Paul Duffin 2500888a09821a98ac0680fad765217302858e70fa4Paul Duffin /** 251090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Determines whether two iterables contain equal elements in the same order. 252090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * More specifically, this method returns {@code true} if {@code iterable1} 253090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * and {@code iterable2} contain the same number of elements and every element 254090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * of {@code iterable1} is equal to the corresponding element of 255090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code iterable2}. 256090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 2570888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static boolean elementsEqual( 2580888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<?> iterable1, Iterable<?> iterable2) { 2597dd252788645e940eada959bdde927426e2531c9Paul Duffin if (iterable1 instanceof Collection && iterable2 instanceof Collection) { 2607dd252788645e940eada959bdde927426e2531c9Paul Duffin Collection<?> collection1 = (Collection<?>) iterable1; 2617dd252788645e940eada959bdde927426e2531c9Paul Duffin Collection<?> collection2 = (Collection<?>) iterable2; 2627dd252788645e940eada959bdde927426e2531c9Paul Duffin if (collection1.size() != collection2.size()) { 2637dd252788645e940eada959bdde927426e2531c9Paul Duffin return false; 2647dd252788645e940eada959bdde927426e2531c9Paul Duffin } 2657dd252788645e940eada959bdde927426e2531c9Paul Duffin } 266090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.elementsEqual(iterable1.iterator(), iterable2.iterator()); 267090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 268090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 269090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 2700888a09821a98ac0680fad765217302858e70fa4Paul Duffin * Returns a string representation of {@code iterable}, with the format {@code 2710888a09821a98ac0680fad765217302858e70fa4Paul Duffin * [e1, e2, ..., en]} (that is, identical to {@link java.util.Arrays 2720888a09821a98ac0680fad765217302858e70fa4Paul Duffin * Arrays}{@code .toString(Iterables.toArray(iterable))}). Note that for 2730888a09821a98ac0680fad765217302858e70fa4Paul Duffin * <i>most</i> implementations of {@link Collection}, {@code 2740888a09821a98ac0680fad765217302858e70fa4Paul Duffin * collection.toString()} also gives the same result, but that behavior is not 2750888a09821a98ac0680fad765217302858e70fa4Paul Duffin * generally guaranteed. 276090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 277090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static String toString(Iterable<?> iterable) { 278090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.toString(iterable.iterator()); 279090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 280090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 281090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 282090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the single element contained in {@code iterable}. 283090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 284090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws NoSuchElementException if the iterable is empty 285090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws IllegalArgumentException if the iterable contains multiple 286090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * elements 287090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 288090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <T> T getOnlyElement(Iterable<T> iterable) { 289090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.getOnlyElement(iterable.iterator()); 290090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 291090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 292090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 293090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the single element contained in {@code iterable}, or {@code 294090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * defaultValue} if the iterable is empty. 295090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 296090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws IllegalArgumentException if the iterator contains multiple 297090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * elements 298090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 2997dd252788645e940eada959bdde927426e2531c9Paul Duffin @Nullable 3000888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> T getOnlyElement( 3010888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<? extends T> iterable, @Nullable T defaultValue) { 302090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.getOnlyElement(iterable.iterator(), defaultValue); 303090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 304090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 305090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 306090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Copies an iterable's elements into an array. 307090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 308090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param iterable the iterable to copy 309090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param type the type of the elements 310090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return a newly-allocated array into which all the elements of the iterable 311090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * have been copied 312090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 313090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson @GwtIncompatible("Array.newInstance(Class, int)") 314090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <T> T[] toArray(Iterable<? extends T> iterable, Class<T> type) { 3151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert Collection<? extends T> collection = toCollection(iterable); 316090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson T[] array = ObjectArrays.newArray(type, collection.size()); 317090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return collection.toArray(array); 318090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 319090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 320090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 3211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copies an iterable's elements into an array. 3221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 3231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param iterable the iterable to copy 3241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @return a newly-allocated array into which all the elements of the iterable 3251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * have been copied 3261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 3271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert static Object[] toArray(Iterable<?> iterable) { 3281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return toCollection(iterable).toArray(); 3291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 3301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 3311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 3321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Converts an iterable into a collection. If the iterable is already a 3331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * collection, it is returned. Otherwise, an {@link java.util.ArrayList} is 3341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * created with the contents of the iterable in the same iteration order. 3351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 3361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private static <E> Collection<E> toCollection(Iterable<E> iterable) { 3370888a09821a98ac0680fad765217302858e70fa4Paul Duffin return (iterable instanceof Collection) 3380888a09821a98ac0680fad765217302858e70fa4Paul Duffin ? (Collection<E>) iterable 3390888a09821a98ac0680fad765217302858e70fa4Paul Duffin : Lists.newArrayList(iterable.iterator()); 3401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 3411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 3421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 343090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Adds all elements in {@code iterable} to {@code collection}. 344090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 345090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return {@code true} if {@code collection} was modified as a result of this 346090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * operation. 347090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 3480888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> boolean addAll( 3490888a09821a98ac0680fad765217302858e70fa4Paul Duffin Collection<T> addTo, Iterable<? extends T> elementsToAdd) { 350090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if (elementsToAdd instanceof Collection) { 3511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert Collection<? extends T> c = Collections2.cast(elementsToAdd); 352090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return addTo.addAll(c); 353090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 3540888a09821a98ac0680fad765217302858e70fa4Paul Duffin return Iterators.addAll(addTo, checkNotNull(elementsToAdd).iterator()); 355090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 356090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 357090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 358090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the number of elements in the specified iterable that equal the 3591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * specified object. This implementation avoids a full iteration when the 3601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterable is a {@link Multiset} or {@link Set}. 361090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 362090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @see Collections#frequency 363090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 364090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static int frequency(Iterable<?> iterable, @Nullable Object element) { 365090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if ((iterable instanceof Multiset)) { 366090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return ((Multiset<?>) iterable).count(element); 3670888a09821a98ac0680fad765217302858e70fa4Paul Duffin } else if ((iterable instanceof Set)) { 368090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return ((Set<?>) iterable).contains(element) ? 1 : 0; 369090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 370090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.frequency(iterable.iterator(), element); 371090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 372090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 373090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 374090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns an iterable whose iterators cycle indefinitely over the elements of 375090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code iterable}. 376090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 377090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>That iterator supports {@code remove()} if {@code iterable.iterator()} 378090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * does. After {@code remove()} is called, subsequent cycles omit the removed 379090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * element, which is no longer in {@code iterable}. The iterator's 380090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code hasNext()} method returns {@code true} until {@code iterable} is 381090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * empty. 382090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 383090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p><b>Warning:</b> Typical uses of the resulting iterator may produce an 384090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * infinite loop. You should use an explicit {@code break} or be certain that 385090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * you will eventually remove all the elements. 386090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 387090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>To cycle over the iterable {@code n} times, use the following: 388090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code Iterables.concat(Collections.nCopies(n, iterable))} 389090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 390090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <T> Iterable<T> cycle(final Iterable<T> iterable) { 391090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(iterable); 3927dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 3930888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 394090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public Iterator<T> iterator() { 395090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.cycle(iterable); 396090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 3970888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override public String toString() { 398090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return iterable.toString() + " (cycled)"; 399090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 400090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson }; 401090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 402090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 403090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 404090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns an iterable whose iterators cycle indefinitely over the provided 405090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * elements. 406090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 407090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>After {@code remove} is invoked on a generated iterator, the removed 408090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * element will no longer appear in either that iterator or any other iterator 409090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * created from the same source iterable. That is, this method behaves exactly 410090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * as {@code Iterables.cycle(Lists.newArrayList(elements))}. The iterator's 411090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code hasNext} method returns {@code true} until all of the original 412090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * elements have been removed. 413090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 414090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p><b>Warning:</b> Typical uses of the resulting iterator may produce an 415090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * infinite loop. You should use an explicit {@code break} or be certain that 416090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * you will eventually remove all the elements. 417090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 418090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>To cycle over the elements {@code n} times, use the following: 419090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code Iterables.concat(Collections.nCopies(n, Arrays.asList(elements)))} 420090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 421090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <T> Iterable<T> cycle(T... elements) { 422090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return cycle(Lists.newArrayList(elements)); 423090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 424090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 425090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 426090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Combines two iterables into a single iterable. The returned iterable has an 427090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * iterator that traverses the elements in {@code a}, followed by the elements 428090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * in {@code b}. The source iterators are not polled until necessary. 429090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 430090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The returned iterable's iterator supports {@code remove()} when the 431090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * corresponding input iterator supports it. 432090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 4330888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> concat( 4340888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<? extends T> a, Iterable<? extends T> b) { 4350888a09821a98ac0680fad765217302858e70fa4Paul Duffin return concat(ImmutableList.of(a, b)); 436090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 437090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 438090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 439090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Combines three iterables into a single iterable. The returned iterable has 440090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * an iterator that traverses the elements in {@code a}, followed by the 441090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * elements in {@code b}, followed by the elements in {@code c}. The source 442090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * iterators are not polled until necessary. 443090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 444090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The returned iterable's iterator supports {@code remove()} when the 445090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * corresponding input iterator supports it. 446090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 4470888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> concat(Iterable<? extends T> a, 4480888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<? extends T> b, Iterable<? extends T> c) { 4490888a09821a98ac0680fad765217302858e70fa4Paul Duffin return concat(ImmutableList.of(a, b, c)); 450090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 451090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 452090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 453090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Combines four iterables into a single iterable. The returned iterable has 454090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * an iterator that traverses the elements in {@code a}, followed by the 455090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * elements in {@code b}, followed by the elements in {@code c}, followed by 456090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * the elements in {@code d}. The source iterators are not polled until 457090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * necessary. 458090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 459090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The returned iterable's iterator supports {@code remove()} when the 460090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * corresponding input iterator supports it. 461090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 4620888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> concat(Iterable<? extends T> a, 4630888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<? extends T> b, Iterable<? extends T> c, 4640888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<? extends T> d) { 4650888a09821a98ac0680fad765217302858e70fa4Paul Duffin return concat(ImmutableList.of(a, b, c, d)); 466090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 467090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 468090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 469090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Combines multiple iterables into a single iterable. The returned iterable 470090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * has an iterator that traverses the elements of each iterable in 471090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code inputs}. The input iterators are not polled until necessary. 472090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 473090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The returned iterable's iterator supports {@code remove()} when the 474090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * corresponding input iterator supports it. 475090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 476090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws NullPointerException if any of the provided iterables is null 477090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 478090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <T> Iterable<T> concat(Iterable<? extends T>... inputs) { 4791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return concat(ImmutableList.copyOf(inputs)); 480090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 481090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 482090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 483090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Combines multiple iterables into a single iterable. The returned iterable 484090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * has an iterator that traverses the elements of each iterable in 485090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code inputs}. The input iterators are not polled until necessary. 486090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 487090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The returned iterable's iterator supports {@code remove()} when the 488090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * corresponding input iterator supports it. The methods of the returned 489090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * iterable may throw {@code NullPointerException} if any of the input 4901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterators is null. 491090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 4920888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> concat( 4930888a09821a98ac0680fad765217302858e70fa4Paul Duffin final Iterable<? extends Iterable<? extends T>> inputs) { 4941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkNotNull(inputs); 4957dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 4960888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 497090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public Iterator<T> iterator() { 4981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return Iterators.concat(iterators(inputs)); 4991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 5001d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 5011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 5021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 5031d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 5041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns an iterator over the iterators of the given iterables. 5051d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 5060888a09821a98ac0680fad765217302858e70fa4Paul Duffin private static <T> Iterator<Iterator<? extends T>> iterators( 5071d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert Iterable<? extends Iterable<? extends T>> iterables) { 5080888a09821a98ac0680fad765217302858e70fa4Paul Duffin return new TransformedIterator<Iterable<? extends T>, Iterator<? extends T>>( 5090888a09821a98ac0680fad765217302858e70fa4Paul Duffin iterables.iterator()) { 5100888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 5110888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterator<? extends T> transform(Iterable<? extends T> from) { 5120888a09821a98ac0680fad765217302858e70fa4Paul Duffin return from.iterator(); 513090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 514090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson }; 515090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 516090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 517090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 518090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Divides an iterable into unmodifiable sublists of the given size (the final 519090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * iterable may be smaller). For example, partitioning an iterable containing 520090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code [a, b, c, d, e]} with a partition size of 3 yields {@code 521090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * [[a, b, c], [d, e]]} -- an outer iterable containing two inner lists of 522090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * three and two elements, all in the original order. 523090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 524090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>Iterators returned by the returned iterable do not support the {@link 525090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Iterator#remove()} method. The returned lists implement {@link 526090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * RandomAccess}, whether or not the input list does. 527090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 528090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p><b>Note:</b> if {@code iterable} is a {@link List}, use {@link 529090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Lists#partition(List, int)} instead. 530090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 531090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param iterable the iterable to return a partitioned view of 532090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param size the desired size of each partition (the last may be smaller) 533090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return an iterable of unmodifiable lists containing the elements of {@code 534090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * iterable} divided into partitions 535090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws IllegalArgumentException if {@code size} is nonpositive 536090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 5370888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<List<T>> partition( 5380888a09821a98ac0680fad765217302858e70fa4Paul Duffin final Iterable<T> iterable, final int size) { 539090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(iterable); 540090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkArgument(size > 0); 5417dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<List<T>>() { 5420888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 543090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public Iterator<List<T>> iterator() { 544090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.partition(iterable.iterator(), size); 545090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 546090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson }; 547090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 548090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 549090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 550090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Divides an iterable into unmodifiable sublists of the given size, padding 551090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * the final iterable with null values if necessary. For example, partitioning 552090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * an iterable containing {@code [a, b, c, d, e]} with a partition size of 3 553090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * yields {@code [[a, b, c], [d, e, null]]} -- an outer iterable containing 554090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * two inner lists of three elements each, all in the original order. 555090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 556090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>Iterators returned by the returned iterable do not support the {@link 557090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Iterator#remove()} method. 558090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 559090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param iterable the iterable to return a partitioned view of 560090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param size the desired size of each partition 561090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return an iterable of unmodifiable lists containing the elements of {@code 562090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * iterable} divided into partitions (the final iterable may have 563090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * trailing null elements) 564090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws IllegalArgumentException if {@code size} is nonpositive 565090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 5660888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<List<T>> paddedPartition( 5670888a09821a98ac0680fad765217302858e70fa4Paul Duffin final Iterable<T> iterable, final int size) { 568090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(iterable); 569090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkArgument(size > 0); 5707dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<List<T>>() { 5710888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 572090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public Iterator<List<T>> iterator() { 573090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.paddedPartition(iterable.iterator(), size); 574090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 575090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson }; 576090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 577090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 578090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 579090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the elements of {@code unfiltered} that satisfy a predicate. The 580090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * resulting iterable's iterator does not support {@code remove()}. 581090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 5820888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> filter( 5830888a09821a98ac0680fad765217302858e70fa4Paul Duffin final Iterable<T> unfiltered, final Predicate<? super T> predicate) { 584090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(unfiltered); 585090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(predicate); 5867dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 5870888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 588090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public Iterator<T> iterator() { 589090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.filter(unfiltered.iterator(), predicate); 590090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 591090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson }; 592090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 593090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 594090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 595090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns all instances of class {@code type} in {@code unfiltered}. The 596090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * returned iterable has elements whose class is {@code type} or a subclass of 597090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code type}. The returned iterable's iterator does not support 598090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code remove()}. 599090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 600090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param unfiltered an iterable containing objects of any type 601090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param type the type of elements desired 602090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return an unmodifiable iterable containing all elements of the original 603090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * iterable that were of the requested type 604090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 605090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson @GwtIncompatible("Class.isInstance") 6060888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> filter( 6070888a09821a98ac0680fad765217302858e70fa4Paul Duffin final Iterable<?> unfiltered, final Class<T> type) { 608090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(unfiltered); 609090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(type); 6107dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 6110888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 612090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public Iterator<T> iterator() { 613090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.filter(unfiltered.iterator(), type); 614090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 615090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson }; 616090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 617090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 618090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 6197dd252788645e940eada959bdde927426e2531c9Paul Duffin * Returns {@code true} if any element in {@code iterable} satisfies the predicate. 620090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 6210888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> boolean any( 6220888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<T> iterable, Predicate<? super T> predicate) { 623090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.any(iterable.iterator(), predicate); 624090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 625090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 626090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 627090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns {@code true} if every element in {@code iterable} satisfies the 628090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * predicate. If {@code iterable} is empty, {@code true} is returned. 629090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 6300888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> boolean all( 6310888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<T> iterable, Predicate<? super T> predicate) { 632090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.all(iterable.iterator(), predicate); 633090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 634090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 635090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 636090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the first element in {@code iterable} that satisfies the given 6371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * predicate; use this method only when such an element is known to exist. If 6387dd252788645e940eada959bdde927426e2531c9Paul Duffin * it is possible that <i>no</i> element will match, use {@link #tryFind} or 6397dd252788645e940eada959bdde927426e2531c9Paul Duffin * {@link #find(Iterable, Predicate, Object)} instead. 640090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 641090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws NoSuchElementException if no element in {@code iterable} matches 642090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * the given predicate 643090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 6440888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> T find(Iterable<T> iterable, 6450888a09821a98ac0680fad765217302858e70fa4Paul Duffin Predicate<? super T> predicate) { 646090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.find(iterable.iterator(), predicate); 647090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 648090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 649090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 6501d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the first element in {@code iterable} that satisfies the given 6511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * predicate, or {@code defaultValue} if none found. Note that this can 6521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * usually be handled more naturally using {@code 6531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * tryFind(iterable, predicate).or(defaultValue)}. 6541d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 6551d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 7.0 6561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 6577dd252788645e940eada959bdde927426e2531c9Paul Duffin @Nullable 6580888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> T find(Iterable<? extends T> iterable, 6590888a09821a98ac0680fad765217302858e70fa4Paul Duffin Predicate<? super T> predicate, @Nullable T defaultValue) { 6601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return Iterators.find(iterable.iterator(), predicate, defaultValue); 6611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 6621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 6631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 6641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns an {@link Optional} containing the first element in {@code 6651d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterable} that satisfies the given predicate, if such an element exists. 6661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 6671d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p><b>Warning:</b> avoid using a {@code predicate} that matches {@code 6681d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * null}. If {@code null} is matched in {@code iterable}, a 6691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * NullPointerException will be thrown. 6701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 6711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0 6721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 6730888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Optional<T> tryFind(Iterable<T> iterable, 6740888a09821a98ac0680fad765217302858e70fa4Paul Duffin Predicate<? super T> predicate) { 6751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return Iterators.tryFind(iterable.iterator(), predicate); 6761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 6771d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 6781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 679bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Returns the index in {@code iterable} of the first element that satisfies 680bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * the provided {@code predicate}, or {@code -1} if the Iterable has no such 681bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * elements. 682bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 683bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <p>More formally, returns the lowest index {@code i} such that 6841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code predicate.apply(Iterables.get(iterable, i))} returns {@code true}, 6851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * or {@code -1} if there is no such index. 686bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 6871d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 2.0 688bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 6890888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> int indexOf( 6900888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterable<T> iterable, Predicate<? super T> predicate) { 691bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return Iterators.indexOf(iterable.iterator(), predicate); 692bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 693bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 694bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 695090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns an iterable that applies {@code function} to each element of {@code 696090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * fromIterable}. 697090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 698090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The returned iterable's iterator supports {@code remove()} if the 699090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * provided iterator does. After a successful {@code remove()} call, 700090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@code fromIterable} no longer contains the corresponding element. 7011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 7021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>If the input {@code Iterable} is known to be a {@code List} or other 7031d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code Collection}, consider {@link Lists#transform} and {@link 7041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Collections2#transform}. 705090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 706090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <F, T> Iterable<T> transform(final Iterable<F> fromIterable, 707090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson final Function<? super F, ? extends T> function) { 708090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(fromIterable); 709090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(function); 7107dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 7110888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 712090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public Iterator<T> iterator() { 713090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.transform(fromIterable.iterator(), function); 714090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 715090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson }; 716090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 717090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 718090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 719090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the element at the specified position in an iterable. 720090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 721090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param position position of the element to return 722090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return the element at the specified position in {@code iterable} 723090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws IndexOutOfBoundsException if {@code position} is negative or 724090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * greater than or equal to the size of {@code iterable} 725090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 726090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <T> T get(Iterable<T> iterable, int position) { 727090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson checkNotNull(iterable); 7280888a09821a98ac0680fad765217302858e70fa4Paul Duffin return (iterable instanceof List) 7290888a09821a98ac0680fad765217302858e70fa4Paul Duffin ? ((List<T>) iterable).get(position) 7300888a09821a98ac0680fad765217302858e70fa4Paul Duffin : Iterators.get(iterable.iterator(), position); 7311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 7321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 7331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 7341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the element at the specified position in an iterable or a default 7351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * value otherwise. 7361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 7371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param position position of the element to return 7381d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param defaultValue the default value to return if {@code position} is 7391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * greater than or equal to the size of the iterable 7401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @return the element at the specified position in {@code iterable} or 7411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code defaultValue} if {@code iterable} contains fewer than 7421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code position + 1} elements. 7431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws IndexOutOfBoundsException if {@code position} is negative 7441d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 4.0 7451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 7467dd252788645e940eada959bdde927426e2531c9Paul Duffin @Nullable 7477dd252788645e940eada959bdde927426e2531c9Paul Duffin public static <T> T get(Iterable<? extends T> iterable, int position, @Nullable T defaultValue) { 7481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkNotNull(iterable); 7490888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterators.checkNonnegative(position); 7500888a09821a98ac0680fad765217302858e70fa4Paul Duffin if (iterable instanceof List) { 7510888a09821a98ac0680fad765217302858e70fa4Paul Duffin List<? extends T> list = Lists.cast(iterable); 7520888a09821a98ac0680fad765217302858e70fa4Paul Duffin return (position < list.size()) ? list.get(position) : defaultValue; 7530888a09821a98ac0680fad765217302858e70fa4Paul Duffin } else { 7540888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterator<? extends T> iterator = iterable.iterator(); 7550888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterators.advance(iterator, position); 7560888a09821a98ac0680fad765217302858e70fa4Paul Duffin return Iterators.getNext(iterator, defaultValue); 7571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 7581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 7591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 7601d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 7611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the first element in {@code iterable} or {@code defaultValue} if 7621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the iterable is empty. The {@link Iterators} analog to this method is 7631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@link Iterators#getNext}. 7641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 7657dd252788645e940eada959bdde927426e2531c9Paul Duffin * <p>If no default value is desired (and the caller instead wants a 7667dd252788645e940eada959bdde927426e2531c9Paul Duffin * {@link NoSuchElementException} to be thrown), it is recommended that 7677dd252788645e940eada959bdde927426e2531c9Paul Duffin * {@code iterable.iterator().next()} is used instead. 7687dd252788645e940eada959bdde927426e2531c9Paul Duffin * 7691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param defaultValue the default value to return if the iterable is empty 7701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @return the first element of {@code iterable} or the default value 7711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 7.0 7721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 7737dd252788645e940eada959bdde927426e2531c9Paul Duffin @Nullable 7747dd252788645e940eada959bdde927426e2531c9Paul Duffin public static <T> T getFirst(Iterable<? extends T> iterable, @Nullable T defaultValue) { 7751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return Iterators.getNext(iterable.iterator(), defaultValue); 7761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 7771d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 778090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 779090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the last element of {@code iterable}. 780090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 781090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return the last element of {@code iterable} 7821d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws NoSuchElementException if the iterable is empty 783090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 784090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson public static <T> T getLast(Iterable<T> iterable) { 7851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // TODO(kevinb): Support a concurrently modified collection? 786090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if (iterable instanceof List) { 787090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson List<T> list = (List<T>) iterable; 788090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson if (list.isEmpty()) { 789090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson throw new NoSuchElementException(); 790090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 7911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return getLastInNonemptyList(list); 792090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 793090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 794090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return Iterators.getLast(iterable.iterator()); 795090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 796090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 797bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 7981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns the last element of {@code iterable} or {@code defaultValue} if 7991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the iterable is empty. 8001d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 8011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param defaultValue the value to return if {@code iterable} is empty 8021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @return the last element of {@code iterable} or the default value 8031d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 3.0 8041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 8057dd252788645e940eada959bdde927426e2531c9Paul Duffin @Nullable 8067dd252788645e940eada959bdde927426e2531c9Paul Duffin public static <T> T getLast(Iterable<? extends T> iterable, @Nullable T defaultValue) { 8071d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert if (iterable instanceof Collection) { 8080888a09821a98ac0680fad765217302858e70fa4Paul Duffin Collection<? extends T> c = Collections2.cast(iterable); 8090888a09821a98ac0680fad765217302858e70fa4Paul Duffin if (c.isEmpty()) { 8101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return defaultValue; 8110888a09821a98ac0680fad765217302858e70fa4Paul Duffin } else if (iterable instanceof List) { 8120888a09821a98ac0680fad765217302858e70fa4Paul Duffin return getLastInNonemptyList(Lists.cast(iterable)); 8131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return Iterators.getLast(iterable.iterator(), defaultValue); 8171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private static <T> T getLastInNonemptyList(List<T> list) { 8201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return list.get(list.size() - 1); 8211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 8241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns a view of {@code iterable} that skips its first 8251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code numberToSkip} elements. If {@code iterable} contains fewer than 8261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code numberToSkip} elements, the returned iterable skips all of its 8271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * elements. 8281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 8291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Modifications to the underlying {@link Iterable} before a call to 8301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code iterator()} are reflected in the returned iterator. That is, the 8311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterator skips the first {@code numberToSkip} elements that exist when the 8321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code Iterator} is created, not when {@code skip()} is called. 8331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 8341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>The returned iterable's iterator supports {@code remove()} if the 8351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterator of the underlying iterable supports it. Note that it is 8361d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <i>not</i> possible to delete the last skipped element by immediately 8371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * calling {@code remove()} on that iterator, as the {@code Iterator} 8381d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * contract states that a call to {@code remove()} before a call to 8391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code next()} will throw an {@link IllegalStateException}. 8401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 8411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 3.0 8421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 8430888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> skip(final Iterable<T> iterable, 8440888a09821a98ac0680fad765217302858e70fa4Paul Duffin final int numberToSkip) { 8451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkNotNull(iterable); 8461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkArgument(numberToSkip >= 0, "number to skip cannot be negative"); 8471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert if (iterable instanceof List) { 8491d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert final List<T> list = (List<T>) iterable; 8507dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 8510888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 8521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public Iterator<T> iterator() { 8531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // TODO(kevinb): Support a concurrently modified collection? 8540888a09821a98ac0680fad765217302858e70fa4Paul Duffin int toSkip = Math.min(list.size(), numberToSkip); 8550888a09821a98ac0680fad765217302858e70fa4Paul Duffin return list.subList(toSkip, list.size()).iterator(); 8561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8571d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 8581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8591d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8607dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 8610888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 8621d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public Iterator<T> iterator() { 8631d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert final Iterator<T> iterator = iterable.iterator(); 8641d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8657dd252788645e940eada959bdde927426e2531c9Paul Duffin Iterators.advance(iterator, numberToSkip); 8661d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8671d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /* 8681d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * We can't just return the iterator because an immediate call to its 8691d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * remove() method would remove one of the skipped elements instead of 8701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * throwing an IllegalStateException. 8711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 8721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return new Iterator<T>() { 8731d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert boolean atStart = true; 8741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8750888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 8761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public boolean hasNext() { 8771d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return iterator.hasNext(); 8781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8800888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 8811d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public T next() { 8820888a09821a98ac0680fad765217302858e70fa4Paul Duffin T result = iterator.next(); 8830888a09821a98ac0680fad765217302858e70fa4Paul Duffin atStart = false; // not called if next() fails 8840888a09821a98ac0680fad765217302858e70fa4Paul Duffin return result; 8851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8861d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8870888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 8881d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public void remove() { 8890888a09821a98ac0680fad765217302858e70fa4Paul Duffin checkRemove(!atStart); 8901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert iterator.remove(); 8911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8921d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 8931d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 8951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 8961d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 8971d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 8981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Creates an iterable with the first {@code limitSize} elements of the given 8991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterable. If the original iterable does not contain that many elements, the 9000888a09821a98ac0680fad765217302858e70fa4Paul Duffin * returned iterable will have the same behavior as the original iterable. The 9011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * returned iterable's iterator supports {@code remove()} if the original 9021d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterator does. 9031d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 9041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @param iterable the iterable to limit 9050888a09821a98ac0680fad765217302858e70fa4Paul Duffin * @param limitSize the maximum number of elements in the returned iterable 9061d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @throws IllegalArgumentException if {@code limitSize} is negative 9071d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 3.0 9081d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 9090888a09821a98ac0680fad765217302858e70fa4Paul Duffin public static <T> Iterable<T> limit( 9100888a09821a98ac0680fad765217302858e70fa4Paul Duffin final Iterable<T> iterable, final int limitSize) { 9111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkNotNull(iterable); 9121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkArgument(limitSize >= 0, "limit is negative"); 9137dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 9140888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 9151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public Iterator<T> iterator() { 9161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return Iterators.limit(iterable.iterator(), limitSize); 9171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 9191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 9211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 922bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Returns a view of the supplied iterable that wraps each generated 923bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * {@link Iterator} through {@link Iterators#consumingIterator(Iterator)}. 924bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 9251d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Note: If {@code iterable} is a {@link Queue}, the returned iterable will 9261d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * get entries from {@link Queue#remove()} since {@link Queue}'s iteration 9271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * order is undefined. Calling {@link Iterator#hasNext()} on a generated 9281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * iterator from the returned iterable may cause an item to be immediately 9291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * dequeued for return on a subsequent call to {@link Iterator#next()}. 9301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 931bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param iterable the iterable to wrap 932bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return a view of the supplied iterable that wraps each generated iterator 9331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * through {@link Iterators#consumingIterator(Iterator)}; for queues, 9341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * an iterable that generates iterators that return and consume the 9351d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * queue's elements in queue order 936bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 937bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @see Iterators#consumingIterator(Iterator) 9381d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 2.0 939bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 940bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static <T> Iterable<T> consumingIterable(final Iterable<T> iterable) { 9411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert if (iterable instanceof Queue) { 9427dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 9430888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 9441d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public Iterator<T> iterator() { 9451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return new ConsumingQueueIterator<T>((Queue<T>) iterable); 9461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9470888a09821a98ac0680fad765217302858e70fa4Paul Duffin 9480888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 9490888a09821a98ac0680fad765217302858e70fa4Paul Duffin public String toString() { 9500888a09821a98ac0680fad765217302858e70fa4Paul Duffin return "Iterables.consumingIterable(...)"; 9510888a09821a98ac0680fad765217302858e70fa4Paul Duffin } 9521d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 9531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9541d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 955bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor checkNotNull(iterable); 9561d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 9577dd252788645e940eada959bdde927426e2531c9Paul Duffin return new FluentIterable<T>() { 9580888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 959bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public Iterator<T> iterator() { 960bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return Iterators.consumingIterator(iterable.iterator()); 961bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 9620888a09821a98ac0680fad765217302858e70fa4Paul Duffin 9630888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 9640888a09821a98ac0680fad765217302858e70fa4Paul Duffin public String toString() { 9650888a09821a98ac0680fad765217302858e70fa4Paul Duffin return "Iterables.consumingIterable(...)"; 9660888a09821a98ac0680fad765217302858e70fa4Paul Duffin } 967bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor }; 968bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 969bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 9701d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private static class ConsumingQueueIterator<T> extends AbstractIterator<T> { 9711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private final Queue<T> queue; 9721d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 9731d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private ConsumingQueueIterator(Queue<T> queue) { 9741d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert this.queue = queue; 9751d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9761d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 9770888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override public T computeNext() { 9781d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert try { 9791d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return queue.remove(); 9801d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } catch (NoSuchElementException e) { 9811d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return endOfData(); 9821d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9831d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 9851d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 986090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson // Methods only in Iterables, not in Iterators 987090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 988090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 989090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Determines if the given iterable contains no elements. 990090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 991090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>There is no precise {@link Iterator} equivalent to this method, since 992090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * one can only ask an iterator whether it has any elements <i>remaining</i> 993090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * (which one does using {@link Iterator#hasNext}). 994090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 995090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return {@code true} if the iterable contains no elements 996090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 9971d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public static boolean isEmpty(Iterable<?> iterable) { 9981d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert if (iterable instanceof Collection) { 9991d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return ((Collection<?>) iterable).isEmpty(); 10001d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 1001090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson return !iterable.iterator().hasNext(); 1002090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson } 1003090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 10041d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert /** 10051d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Returns an iterable over the merged contents of all given 10061d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * {@code iterables}. Equivalent entries will not be de-duplicated. 10071d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 10081d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>Callers must ensure that the source {@code iterables} are in 10091d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * non-descending order as this method does not sort its input. 10101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 10111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p>For any equivalent elements across all {@code iterables}, it is 10121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * undefined which element is returned first. 10131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * 10141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0 10151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */ 10161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Beta 10171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public static <T> Iterable<T> mergeSorted( 10181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert final Iterable<? extends Iterable<? extends T>> iterables, 10191d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert final Comparator<? super T> comparator) { 10201d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkNotNull(iterables, "iterables"); 10211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert checkNotNull(comparator, "comparator"); 10227dd252788645e940eada959bdde927426e2531c9Paul Duffin Iterable<T> iterable = new FluentIterable<T>() { 10230888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 10241d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public Iterator<T> iterator() { 10250888a09821a98ac0680fad765217302858e70fa4Paul Duffin return Iterators.mergeSorted( 10260888a09821a98ac0680fad765217302858e70fa4Paul Duffin Iterables.transform(iterables, Iterables.<T>toIterator()), 10271d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert comparator); 10281d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 10291d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 10301d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return new UnmodifiableIterable<T>(iterable); 10311d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 10321d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 10331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // TODO(user): Is this the best place for this? Move to fluent functions? 10341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert // Useful as a public method? 10350888a09821a98ac0680fad765217302858e70fa4Paul Duffin private static <T> Function<Iterable<? extends T>, Iterator<? extends T>> 10360888a09821a98ac0680fad765217302858e70fa4Paul Duffin toIterator() { 10371d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return new Function<Iterable<? extends T>, Iterator<? extends T>>() { 10380888a09821a98ac0680fad765217302858e70fa4Paul Duffin @Override 10391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert public Iterator<? extends T> apply(Iterable<? extends T> iterable) { 10401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert return iterable.iterator(); 10411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 10421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert }; 10431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert } 1044090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson} 1045