com.gs.collections.api.RichIterable Maven / Gradle / Ivy
/*
* Copyright 2015 Goldman Sachs.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.gs.collections.api;
import java.util.Collection;
import java.util.Comparator;
import java.util.NoSuchElementException;
import com.gs.collections.api.bag.MutableBag;
import com.gs.collections.api.bag.sorted.MutableSortedBag;
import com.gs.collections.api.block.function.Function;
import com.gs.collections.api.block.function.Function0;
import com.gs.collections.api.block.function.Function2;
import com.gs.collections.api.block.function.primitive.BooleanFunction;
import com.gs.collections.api.block.function.primitive.ByteFunction;
import com.gs.collections.api.block.function.primitive.CharFunction;
import com.gs.collections.api.block.function.primitive.DoubleFunction;
import com.gs.collections.api.block.function.primitive.DoubleObjectToDoubleFunction;
import com.gs.collections.api.block.function.primitive.FloatFunction;
import com.gs.collections.api.block.function.primitive.FloatObjectToFloatFunction;
import com.gs.collections.api.block.function.primitive.IntFunction;
import com.gs.collections.api.block.function.primitive.IntObjectToIntFunction;
import com.gs.collections.api.block.function.primitive.LongFunction;
import com.gs.collections.api.block.function.primitive.LongObjectToLongFunction;
import com.gs.collections.api.block.function.primitive.ShortFunction;
import com.gs.collections.api.block.predicate.Predicate;
import com.gs.collections.api.block.predicate.Predicate2;
import com.gs.collections.api.block.procedure.Procedure;
import com.gs.collections.api.block.procedure.Procedure2;
import com.gs.collections.api.collection.primitive.MutableBooleanCollection;
import com.gs.collections.api.collection.primitive.MutableByteCollection;
import com.gs.collections.api.collection.primitive.MutableCharCollection;
import com.gs.collections.api.collection.primitive.MutableDoubleCollection;
import com.gs.collections.api.collection.primitive.MutableFloatCollection;
import com.gs.collections.api.collection.primitive.MutableIntCollection;
import com.gs.collections.api.collection.primitive.MutableLongCollection;
import com.gs.collections.api.collection.primitive.MutableShortCollection;
import com.gs.collections.api.list.MutableList;
import com.gs.collections.api.map.MapIterable;
import com.gs.collections.api.map.MutableMap;
import com.gs.collections.api.map.primitive.ObjectDoubleMap;
import com.gs.collections.api.map.primitive.ObjectLongMap;
import com.gs.collections.api.map.sorted.MutableSortedMap;
import com.gs.collections.api.multimap.Multimap;
import com.gs.collections.api.multimap.MutableMultimap;
import com.gs.collections.api.ordered.OrderedIterable;
import com.gs.collections.api.partition.PartitionIterable;
import com.gs.collections.api.set.MutableSet;
import com.gs.collections.api.set.sorted.MutableSortedSet;
import com.gs.collections.api.tuple.Pair;
/**
* RichIterable is an interface which extends the InternalIterable interface with several internal iterator methods, from
* the Smalltalk Collection protocol. These include select, reject, detect, collect, injectInto, anySatisfy,
* allSatisfy. The API also includes converter methods to convert a RichIterable to a List (toList), to a sorted
* List (toSortedList), to a Set (toSet), and to a Map (toMap).
*
* @since 1.0
*/
public interface
RichIterable
extends InternalIterable
{
/**
* Returns the number of items in this iterable.
*
* @since 1.0
*/
int size();
/**
* Returns true if this iterable has zero items.
*
* @since 1.0
*/
boolean isEmpty();
/**
* The English equivalent of !this.isEmpty()
*
* @since 1.0
*/
boolean notEmpty();
/**
* Returns the first element of an iterable. In the case of a List it is the element at the first index. In the
* case of any other Collection, it is the first element that would be returned during an iteration. If the
* iterable is empty, null is returned. If null is a valid element of the container, then a developer would need to
* check to see if the iterable is empty to validate that a null result was not due to the container being empty.
*
* The order of Sets are not guaranteed (except for TreeSets and other Ordered Set implementations), so if you use
* this method, the first element could be any element from the Set.
*
* @since 1.0
* @deprecated in 6.0. Use {@link OrderedIterable#getFirst()} instead.
*/
@Deprecated
T getFirst();
/**
* Returns the last element of an iterable. In the case of a List it is the element at the last index. In the case
* of any other Collection, it is the last element that would be returned during an iteration. If the iterable is
* empty, null is returned. If null is a valid element of the container, then a developer would need to check to
* see if the iterable is empty to validate that a null result was not due to the container being empty.
*
* The order of Sets are not guaranteed (except for TreeSets and other Ordered Set implementations), so if you use
* this method, the last element could be any element from the Set.
*
* @since 1.0
* @deprecated in 6.0. Use {@link OrderedIterable#getLast()} instead.
*/
@Deprecated
T getLast();
/**
* Returns true if the iterable has an element which responds true to element.equals(object).
*
* @since 1.0
*/
boolean contains(Object object);
/**
* Returns true if all elements in source are contained in this collection.
*
* @since 1.0
*/
boolean containsAllIterable(Iterable source);
/**
* Returns true if all elements in source are contained in this collection.
*
* @see Collection#containsAll(Collection)
* @since 1.0
*/
boolean containsAll(Collection source);
/**
* Returns true if all elements in the specified var arg array are contained in this collection.
*
* @since 1.0
*/
boolean containsAllArguments(Object... elements);
/**
* Executes the Procedure for each element in the iterable and returns {@code this}.
*
* Example using a Java 8 lambda expression:
*
* RichIterable<Person> tapped =
* people.tap(person -> LOGGER.info(person.getName()));
*
*
* Example using an anonymous inner class:
*
* RichIterable<Person> tapped =
* people.tap(new Procedure()
* {
* public void value(Person person)
* {
* LOGGER.info(person.getName());
* }
* });
*
*
* @see #each(Procedure)
* @see #forEach(Procedure)
* @since 6.0
*/
RichIterable tap(Procedure procedure);
/**
* The procedure is executed for each element in the iterable.
*
* Example using a Java 8 lambda expression:
*
* people.each(person -> LOGGER.info(person.getName()));
*
*
* Example using an anonymous inner class:
*
* people.each(new Procedure()
* {
* public void value(Person person)
* {
* LOGGER.info(person.getName());
* }
* });
*
* This method is a variant of {@link InternalIterable#forEach(Procedure)}
* that has a signature conflict with {@link Iterable#forEach(java.util.function.Consumer)}.
*
* @see InternalIterable#forEach(Procedure)
* @see Iterable#forEach(java.util.function.Consumer)
* @since 6.0
*/
@SuppressWarnings("UnnecessaryFullyQualifiedName")
void each(Procedure procedure);
/**
* Returns all elements of the source collection that return true when evaluating the predicate. This method is also
* commonly called filter.
*
* Example using a Java 8 lambda expression:
*
* RichIterable<Person> selected =
* people.select(person -> person.getAddress().getCity().equals("London"));
*
*
* Example using an anonymous inner class:
*
* RichIterable<Person> selected =
* people.select(new Predicate<Person>()
* {
* public boolean accept(Person person)
* {
* return person.getAddress().getCity().equals("London");
* }
* });
*
* @since 1.0
*/
RichIterable select(Predicate predicate);
/**
* Same as the select method with one parameter but uses the specified target collection for the results.
*
* Example using a Java 8 lambda expression:
*
* MutableList<Person> selected =
* people.select(person -> person.person.getLastName().equals("Smith"), Lists.mutable.empty());
*
*
* Example using an anonymous inner class:
*
* MutableList<Person> selected =
* people.select(new Predicate<Person>()
* {
* public boolean accept(Person person)
* {
* return person.person.getLastName().equals("Smith");
* }
* }, Lists.mutable.empty());
*
*
*
* @param predicate a {@link Predicate} to use as the select criteria
* @param target the Collection to append to for all elements in this {@code RichIterable} that meet select criteria {@code predicate}
* @return {@code target}, which contains appended elements as a result of the select criteria
* @see #select(Predicate)
* @since 1.0
*/
> R select(Predicate predicate, R target);
/**
* Similar to {@link #select(Predicate)}, except with an evaluation parameter for the second generic argument in {@link Predicate2}.
*
* E.g. return a {@link Collection} of Person elements where the person has an age greater than or equal to 18 years
*
* Example using a Java 8 lambda expression:
*
* RichIterable<Person> selected =
* people.selectWith((Person person, Integer age) -> person.getAge() >= age, Integer.valueOf(18));
*
*
* Example using an anonymous inner class:
*
* RichIterable<Person> selected =
* people.selectWith(new Predicate2<Person, Integer>()
* {
* public boolean accept(Person person, Integer age)
* {
* return person.getAge() >= age;
* }
* }, Integer.valueOf(18));
*
*
* @param predicate a {@link Predicate2} to use as the select criteria
* @param parameter a parameter to pass in for evaluation of the second argument {@code P} in {@code predicate}
* @see #select(Predicate)
* @since 5.0
*/
RichIterable selectWith(Predicate2 predicate, P parameter);
/**
* Similar to {@link #select(Predicate, Collection)}, except with an evaluation parameter for the second generic argument in {@link Predicate2}.
*
* E.g. return a {@link Collection} of Person elements where the person has an age greater than or equal to 18 years
*
* Example using a Java 8 lambda expression:
*
* MutableList<Person> selected =
* people.selectWith((Person person, Integer age) -> person.getAge() >= age, Integer.valueOf(18), Lists.mutable.empty());
*
*
* Example using an anonymous inner class:
*
* MutableList<Person> selected =
* people.selectWith(new Predicate2<Person, Integer>()
* {
* public boolean accept(Person person, Integer age)
* {
* return person.getAge() >= age;
* }
* }, Integer.valueOf(18), Lists.mutable.empty());
*
*
* @param predicate a {@link Predicate2} to use as the select criteria
* @param parameter a parameter to pass in for evaluation of the second argument {@code P} in {@code predicate}
* @param targetCollection the Collection to append to for all elements in this {@code RichIterable} that meet select criteria {@code predicate}
* @return {@code targetCollection}, which contains appended elements as a result of the select criteria
* @see #select(Predicate)
* @see #select(Predicate, Collection)
* @since 1.0
*/
> R selectWith(
Predicate2 predicate,
P parameter,
R targetCollection);
/**
* Returns all elements of the source collection that return false when evaluating of the predicate. This method is also
* sometimes called filterNot and is the equivalent of calling iterable.select(Predicates.not(predicate)).
*
* Example using a Java 8 lambda expression:
*
* RichIterable<Person> rejected =
* people.reject(person -> person.person.getLastName().equals("Smith"));
*
*
* Example using an anonymous inner class:
*
* RichIterable<Person> rejected =
* people.reject(new Predicate<Person>()
* {
* public boolean accept(Person person)
* {
* return person.person.getLastName().equals("Smith");
* }
* });
*
*
* @param predicate a {@link Predicate} to use as the reject criteria
* @return a RichIterable that contains elements that cause {@link Predicate#accept(Object)} method to evaluate to false
* @since 1.0
*/
RichIterable reject(Predicate predicate);
/**
* Similar to {@link #reject(Predicate)}, except with an evaluation parameter for the second generic argument in {@link Predicate2}.
*
* E.g. return a {@link Collection} of Person elements where the person has an age greater than or equal to 18 years
*
* Example using a Java 8 lambda expression:
*
* RichIterable<Person> rejected =
* people.rejectWith((Person person, Integer age) -> person.getAge() < age, Integer.valueOf(18));
*
*
* Example using an anonymous inner class:
*
* MutableList<Person> rejected =
* people.rejectWith(new Predicate2<Person, Integer>()
* {
* public boolean accept(Person person, Integer age)
* {
* return person.getAge() < age;
* }
* }, Integer.valueOf(18));
*
*
* @param predicate a {@link Predicate2} to use as the select criteria
* @param parameter a parameter to pass in for evaluation of the second argument {@code P} in {@code predicate}
* @see #select(Predicate)
* @since 5.0
*/
RichIterable rejectWith(Predicate2 predicate, P parameter);
/**
* Same as the reject method with one parameter but uses the specified target collection for the results.
*
* Example using a Java 8 lambda expression:
*
* MutableList<Person> rejected =
* people.reject(person -> person.person.getLastName().equals("Smith"), Lists.mutable.empty());
*
*
* Example using an anonymous inner class:
*
* MutableList<Person> rejected =
* people.reject(new Predicate<Person>()
* {
* public boolean accept(Person person)
* {
* return person.person.getLastName().equals("Smith");
* }
* }, Lists.mutable.empty());
*
*
* @param predicate a {@link Predicate} to use as the reject criteria
* @param target the Collection to append to for all elements in this {@code RichIterable} that cause {@code Predicate#accept(Object)} method to evaluate to false
* @return {@code target}, which contains appended elements as a result of the reject criteria
* @since 1.0
*/
> R reject(Predicate predicate, R target);
/**
* Similar to {@link #reject(Predicate, Collection)}, except with an evaluation parameter for the second generic argument in {@link Predicate2}.
*
* E.g. return a {@link Collection} of Person elements where the person has an age greater than or equal to 18 years
*
* Example using a Java 8 lambda expression:
*
* MutableList<Person> rejected =
* people.rejectWith((Person person, Integer age) -> person.getAge() < age, Integer.valueOf(18), Lists.mutable.empty());
*
*
* Example using an anonymous inner class:
*
* MutableList<Person> rejected =
* people.rejectWith(new Predicate2<Person, Integer>()
* {
* public boolean accept(Person person, Integer age)
* {
* return person.getAge() < age;
* }
* }, Integer.valueOf(18), Lists.mutable.empty());
*
*
* @param predicate a {@link Predicate2} to use as the reject criteria
* @param parameter a parameter to pass in for evaluation of the second argument {@code P} in {@code predicate}
* @param targetCollection the Collection to append to for all elements in this {@code RichIterable} that cause {@code Predicate#accept(Object)} method to evaluate to false
* @return {@code targetCollection}, which contains appended elements as a result of the reject criteria
* @see #reject(Predicate)
* @see #reject(Predicate, Collection)
* @since 1.0
*/
> R rejectWith(
Predicate2 predicate,
P parameter,
R targetCollection);
/**
* Filters a collection into a PartitionedIterable based on the evaluation of the predicate.
*
* Example using a Java 8 lambda expression:
*
* PartitionIterable<Person> newYorkersAndNonNewYorkers =
* people.partition(person -> person.getAddress().getState().getName().equals("New York"));
*
*
* Example using an anonymous inner class:
*
* PartitionIterable<Person> newYorkersAndNonNewYorkers =
* people.partition(new Predicate<Person>()
* {
* public boolean accept(Person person)
* {
* return person.getAddress().getState().getName().equals("New York");
* }
* });
*
*
* @since 1.0.
*/
PartitionIterable partition(Predicate predicate);
/**
* Filters a collection into a PartitionIterable based on the evaluation of the predicate.
*
* Example using a Java 8 lambda expression:
*
* PartitionIterable<Person>> newYorkersAndNonNewYorkers =
* people.partitionWith((Person person, String state) -> person.getAddress().getState().getName().equals(state), "New York");
*
*
* Example using an anonymous inner class:
*
* PartitionIterable<Person>> newYorkersAndNonNewYorkers =
* people.partitionWith(new Predicate2<Person, String>()
* {
* public boolean accept(Person person, String state)
* {
* return person.getAddress().getState().getName().equals(state);
* }
* }, "New York");
*
*
* @since 5.0.
*/
PartitionIterable partitionWith(Predicate2 predicate, P parameter);
/**
* Returns all elements of the source collection that are instances of the Class {@code clazz}.
*
* @since 2.0
*/
RichIterable selectInstancesOf(Class clazz);
/**
* Returns a new collection with the results of applying the specified function on each element of the source
* collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* RichIterable<String> names =
* people.collect(person -> person.getFirstName() + " " + person.getLastName());
*
*
* Example using an anonymous inner class:
*
* RichIterable<String> names =
* people.collect(new Function<Person, String>()
* {
* public String valueOf(Person person)
* {
* return person.getFirstName() + " " + person.getLastName();
* }
* });
*
*
* @since 1.0
*/
RichIterable collect(Function function);
/**
* Same as {@link #collect(Function)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* MutableList<String> names =
* people.collect(person -> person.getFirstName() + " " + person.getLastName(), Lists.mutable.empty());
*
*
* Example using an anonymous inner class:
*
* MutableList<String> names =
* people.collect(new Function<Person, String>()
* {
* public String valueOf(Person person)
* {
* return person.getFirstName() + " " + person.getLastName();
* }
* }, Lists.mutable.empty());
*
*
* @param function a {@link Function} to use as the collect transformation function
* @param target the Collection to append to for all elements in this {@code RichIterable} that meet select criteria {@code function}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @see #collect(Function)
* @since 1.0
*/
> R collect(Function function, R target);
/**
* Returns a new primitive {@code boolean} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* BooleanIterable licenses =
* people.collectBoolean(person -> person.hasDrivingLicense());
*
*
* Example using an anonymous inner class:
*
* BooleanIterable licenses =
* people.collectBoolean(new BooleanFunction<Person>()
* {
* public boolean booleanValueOf(Person person)
* {
* return person.hasDrivingLicense();
* }
* });
*
*
* @since 4.0
*/
BooleanIterable collectBoolean(BooleanFunction booleanFunction);
/**
* Same as {@link #collectBoolean(BooleanFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* BooleanArrayList licenses =
* people.collectBoolean(person -> person.hasDrivingLicense(), new BooleanArrayList());
*
*
* Example using an anonymous inner class:
*
* BooleanArrayList licenses =
* people.collectBoolean(new BooleanFunction<Person>()
* {
* public boolean booleanValueOf(Person person)
* {
* return person.hasDrivingLicense();
* }
* }, new BooleanArrayList());
*
*
* @param booleanFunction a {@link BooleanFunction} to use as the collect transformation function
* @param target the MutableBooleanCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectBoolean(BooleanFunction booleanFunction, R target);
/**
* Returns a new primitive {@code byte} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* ByteIterable bytes =
* people.collectByte(person -> person.getCode());
*
*
* Example using an anonymous inner class:
*
* ByteIterable bytes =
* people.collectByte(new ByteFunction<Person>()
* {
* public byte byteValueOf(Person person)
* {
* return person.getCode();
* }
* });
*
*
* @since 4.0
*/
ByteIterable collectByte(ByteFunction byteFunction);
/**
* Same as {@link #collectByte(ByteFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* ByteArrayList bytes =
* people.collectByte(person -> person.getCode(), new ByteArrayList());
*
*
* Example using an anonymous inner class:
*
* ByteArrayList bytes =
* people.collectByte(new ByteFunction<Person>()
* {
* public byte byteValueOf(Person person)
* {
* return person.getCode();
* }
* }, new ByteArrayList());
*
*
* @param byteFunction a {@link ByteFunction} to use as the collect transformation function
* @param target the MutableByteCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectByte(ByteFunction byteFunction, R target);
/**
* Returns a new primitive {@code char} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* CharIterable chars =
* people.collectChar(person -> person.getMiddleInitial());
*
*
* Example using an anonymous inner class:
*
* CharIterable chars =
* people.collectChar(new CharFunction<Person>()
* {
* public char charValueOf(Person person)
* {
* return person.getMiddleInitial();
* }
* });
*
*
* @since 4.0
*/
CharIterable collectChar(CharFunction charFunction);
/**
* Same as {@link #collectChar(CharFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* CharArrayList chars =
* people.collectChar(person -> person.getMiddleInitial(), new CharArrayList());
*
*
* Example using an anonymous inner class:
*
* CharArrayList chars =
* people.collectChar(new CharFunction<Person>()
* {
* public char charValueOf(Person person)
* {
* return person.getMiddleInitial();
* }
* }, new CharArrayList());
*
*
* @param charFunction a {@link CharFunction} to use as the collect transformation function
* @param target the MutableCharCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectChar(CharFunction charFunction, R target);
/**
* Returns a new primitive {@code double} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* DoubleIterable doubles =
* people.collectDouble(person -> person.getMilesFromNorthPole());
*
*
* Example using an anonymous inner class:
*
* DoubleIterable doubles =
* people.collectDouble(new DoubleFunction<Person>()
* {
* public double doubleValueOf(Person person)
* {
* return person.getMilesFromNorthPole();
* }
* });
*
*
* @since 4.0
*/
DoubleIterable collectDouble(DoubleFunction doubleFunction);
/**
* Same as {@link #collectDouble(DoubleFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* DoubleArrayList doubles =
* people.collectDouble(person -> person.getMilesFromNorthPole(), new DoubleArrayList());
*
*
* Example using an anonymous inner class:
*
* DoubleArrayList doubles =
* people.collectDouble(new DoubleFunction<Person>()
* {
* public double doubleValueOf(Person person)
* {
* return person.getMilesFromNorthPole();
* }
* }, new DoubleArrayList());
*
*
* @param doubleFunction a {@link DoubleFunction} to use as the collect transformation function
* @param target the MutableDoubleCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectDouble(DoubleFunction doubleFunction, R target);
/**
* Returns a new primitive {@code float} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* FloatIterable floats =
* people.collectFloat(person -> person.getHeightInInches());
*
*
* Example using an anonymous inner class:
*
* FloatIterable floats =
* people.collectFloat(new FloatFunction<Person>()
* {
* public float floatValueOf(Person person)
* {
* return person.getHeightInInches();
* }
* });
*
*
* @since 4.0
*/
FloatIterable collectFloat(FloatFunction floatFunction);
/**
* Same as {@link #collectFloat(FloatFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* FloatArrayList floats =
* people.collectFloat(person -> person.getHeightInInches(), new FloatArrayList());
*
*
* Example using an anonymous inner class:
*
* FloatArrayList floats =
* people.collectFloat(new FloatFunction<Person>()
* {
* public float floatValueOf(Person person)
* {
* return person.getHeightInInches();
* }
* }, new FloatArrayList());
*
*
* @param floatFunction a {@link FloatFunction} to use as the collect transformation function
* @param target the MutableFloatCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectFloat(FloatFunction floatFunction, R target);
/**
* Returns a new primitive {@code int} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* IntIterable ints =
* people.collectInt(person -> person.getAge());
*
*
* Example using an anonymous inner class:
*
* IntIterable ints =
* people.collectInt(new IntFunction<Person>()
* {
* public int intValueOf(Person person)
* {
* return person.getAge();
* }
* });
*
*
* @since 4.0
*/
IntIterable collectInt(IntFunction intFunction);
/**
* Same as {@link #collectInt(IntFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* IntArrayList ints =
* people.collectInt(person -> person.getAge(), new IntArrayList());
*
*
* Example using an anonymous inner class:
*
* IntArrayList ints =
* people.collectInt(new IntFunction<Person>()
* {
* public int intValueOf(Person person)
* {
* return person.getAge();
* }
* }, new IntArrayList());
*
*
* @param intFunction a {@link IntFunction} to use as the collect transformation function
* @param target the MutableIntCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectInt(IntFunction intFunction, R target);
/**
* Returns a new primitive {@code long} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* LongIterable longs =
* people.collectLong(person -> person.getGuid());
*
*
* Example using an anonymous inner class:
*
* LongIterable longs =
* people.collectLong(new LongFunction<Person>()
* {
* public long longValueOf(Person person)
* {
* return person.getGuid();
* }
* });
*
*
* @since 4.0
*/
LongIterable collectLong(LongFunction longFunction);
/**
* Same as {@link #collectLong(LongFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* LongArrayList longs =
* people.collectLong(person -> person.getGuid(), new LongArrayList());
*
*
* Example using an anonymous inner class:
*
* LongArrayList longs =
* people.collectLong(new LongFunction<Person>()
* {
* public long longValueOf(Person person)
* {
* return person.getGuid();
* }
* }, new LongArrayList());
*
*
* @param longFunction a {@link LongFunction} to use as the collect transformation function
* @param target the MutableLongCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectLong(LongFunction longFunction, R target);
/**
* Returns a new primitive {@code short} iterable with the results of applying the specified function on each element
* of the source collection. This method is also commonly called transform or map.
*
* Example using a Java 8 lambda expression:
*
* ShortIterable shorts =
* people.collectShort(person -> person.getNumberOfJunkMailItemsReceivedPerMonth());
*
*
* Example using an anonymous inner class:
*
* ShortIterable shorts =
* people.collectShort(new ShortFunction<Person>()
* {
* public short shortValueOf(Person person)
* {
* return person.getNumberOfJunkMailItemsReceivedPerMonth();
* }
* });
*
*
* @since 4.0
*/
ShortIterable collectShort(ShortFunction shortFunction);
/**
* Same as {@link #collectShort(ShortFunction)}, except that the results are gathered into the specified {@code target}
* collection.
*
* Example using a Java 8 lambda expression:
*
* ShortArrayList shorts =
* people.collectShort(person -> person.getNumberOfJunkMailItemsReceivedPerMonth, new ShortArrayList());
*
*
* Example using an anonymous inner class:
*
* ShortArrayList shorts =
* people.collectShort(new ShortFunction<Person>()
* {
* public short shortValueOf(Person person)
* {
* return person.getNumberOfJunkMailItemsReceivedPerMonth;
* }
* }, new ShortArrayList());
*
*
* @param shortFunction a {@link ShortFunction} to use as the collect transformation function
* @param target the MutableShortCollection to append to for all elements in this {@code RichIterable}
* @return {@code target}, which contains appended elements as a result of the collect transformation
* @since 5.0
*/
R collectShort(ShortFunction shortFunction, R target);
/**
* Same as {@link #collect(Function)} with a {@code Function2} and specified parameter which is passed to the block.
*
* Example using a Java 8 lambda expression:
*
* RichIterable<Integer> integers =
* Lists.mutable.with(1, 2, 3).collectWith((each, parameter) -> each + parameter, Integer.valueOf(1));
*
*
* Example using an anonymous inner class:
*
* Function2<Integer, Integer, Integer> addParameterFunction =
* new Function2<Integer, Integer, Integer>()
* {
* public Integer value(Integer each, Integer parameter)
* {
* return each + parameter;
* }
* };
* RichIterable<Integer> integers =
* Lists.mutable.with(1, 2, 3).collectWith(addParameterFunction, Integer.valueOf(1));
*
*
* @param function A {@link Function2} to use as the collect transformation function
* @param parameter A parameter to pass in for evaluation of the second argument {@code P} in {@code function}
* @return A new {@code RichIterable} that contains the transformed elements returned by {@link Function2#value(Object, Object)}
* @see #collect(Function)
* @since 5.0
*/
RichIterable collectWith(Function2 function, P parameter);
/**
* Same as collectWith but with a targetCollection parameter to gather the results.
*
* Example using a Java 8 lambda expression:
*
* MutableSet<Integer> integers =
* Lists.mutable.with(1, 2, 3).collectWith((each, parameter) -> each + parameter, Integer.valueOf(1), Sets.mutable.empty());
*
*
* Example using an anonymous inner class:
*
* Function2 addParameterFunction =
* new Function2()
* {
* public Integer value(final Integer each, final Integer parameter)
* {
* return each + parameter;
* }
* };
* MutableSet<Integer> integers =
* Lists.mutable.with(1, 2, 3).collectWith(addParameterFunction, Integer.valueOf(1), Sets.mutable.empty());
*
*
* @param function a {@link Function2} to use as the collect transformation function
* @param parameter a parameter to pass in for evaluation of the second argument {@code P} in {@code function}
* @param targetCollection the Collection to append to for all elements in this {@code RichIterable} that meet select criteria {@code function}
* @return {@code targetCollection}, which contains appended elements as a result of the collect transformation
* @since 1.0
*/
> R collectWith(
Function2 function,
P parameter,
R targetCollection);
/**
* Returns a new collection with the results of applying the specified function on each element of the source
* collection, but only for those elements which return true upon evaluation of the predicate. This is the
* the optimized equivalent of calling iterable.select(predicate).collect(function).
*
* Example using a Java 8 lambda and method reference:
*
* RichIterable<String> strings = Lists.mutable.with(1, 2, 3).collectIf(e -> e != null, Object::toString);
*
*
* Example using Predicates factory:
*
* RichIterable<String> strings = Lists.mutable.with(1, 2, 3).collectIf(Predicates.notNull(), Functions.getToString());
*
*
* @since 1.0
*/
RichIterable collectIf(Predicate predicate, Function function);
/**
* Same as the collectIf method with two parameters but uses the specified target collection for the results.
*
* @param predicate a {@link Predicate} to use as the select criteria
* @param function a {@link Function} to use as the collect transformation function
* @param target the Collection to append to for all elements in this {@code RichIterable} that meet the collect criteria {@code predicate}
* @return {@code targetCollection}, which contains appended elements as a result of the collect criteria and transformation
* @see #collectIf(Predicate, Function)
* @since 1.0
*/
> R collectIf(
Predicate predicate,
Function function,
R target);
/**
* {@code flatCollect} is a special case of {@link #collect(Function)}. With {@code collect}, when the {@link Function} returns
* a collection, the result is a collection of collections. {@code flatCollect} outputs a single "flattened" collection
* instead. This method is commonly called flatMap.
*
* Consider the following example where we have a {@code Person} class, and each {@code Person} has a list of {@code Address} objects. Take the following {@link Function}:
*
* Function<Person, List<Address>> addressFunction = Person::getAddresses;
* MutableList<Person> people = ...;
*
* Using {@code collect} returns a collection of collections of addresses.
*
* MutableList<List<Address>> addresses = people.collect(addressFunction);
*
* Using {@code flatCollect} returns a single flattened list of addresses.
*
* MutableList<Address> addresses = people.flatCollect(addressFunction);
*
*
* @param function The {@link Function} to apply
* @return a new flattened collection produced by applying the given {@code function}
* @since 1.0
*/
RichIterable flatCollect(Function> function);
/**
* Same as flatCollect, only the results are collected into the target collection.
*
* @param function The {@link Function} to apply
* @param target The collection into which results should be added.
* @return {@code target}, which will contain a flattened collection of results produced by applying the given {@code function}
* @see #flatCollect(Function)
*/
> R flatCollect(Function> function, R target);
/**
* Returns the first element of the iterable for which the predicate evaluates to true or null in the case where no
* element returns true. This method is commonly called find.
*
* Example using a Java 8 lambda expression:
*
* Person person =
* people.detect(person -> person.getFirstName().equals("John") && person.getLastName().equals("Smith"));
*
*
* Example using an anonymous inner class:
*
* Person person =
* people.detect(new Predicate<Person>()
* {
* public boolean value(Person person)
* {
* return person.getFirstName().equals("John") && person.getLastName().equals("Smith");
* }
* });
*
*
* @since 1.0
*/
T detect(Predicate predicate);
/**
* Returns the first element that evaluates to true for the specified predicate2 and parameter, or null if none
* evaluate to true.
*
* Example using a Java 8 lambda expression:
*
* Person person =
* people.detectWith((person, fullName) -> person.getFullName().equals(fullName), "John Smith");
*
*
* Example using an anonymous inner class:
*
* Person person =
* people.detectWith(new Predicate2<Person, String>()
* {
* public boolean value(Person person, String fullName)
* {
* return person.getFullName().equals(fullName);
* }
* }, "John Smith");
*
*
* @since 5.0
*/
T detectWith(Predicate2 predicate, P parameter);
/**
* Returns the first element of the iterable for which the predicate evaluates to true. If no element matches
* the predicate, then returns the value of applying the specified function.
*
* @since 1.0
*/
T detectIfNone(Predicate predicate, Function0 function);
/**
* Returns the first element of the iterable that evaluates to true for the specified predicate2 and parameter, or
* returns the value of evaluating the specified function.
*
* @since 5.0
*/
T detectWithIfNone(
Predicate2 predicate,
P parameter,
Function0 function);
/**
* Return the total number of elements that answer true to the specified predicate.
*
* Example using a Java 8 lambda expression:
*
* int count =
* people.count(person -> person.getAddress().getState().getName().equals("New York"));
*
*
* Example using an anonymous inner class:
*
* int count =
* people.count(new Predicate<Person>()
* {
* public boolean accept(Person person)
* {
* return person.getAddress().getState().getName().equals("New York");
* }
* });
*
*
* @since 1.0
*/
int count(Predicate predicate);
/**
* Returns the total number of elements that evaluate to true for the specified predicate.
*
*
e.g.
* return lastNames.countWith(PredicatesLite.equal(), "Smith");
*
*/
int countWith(Predicate2 predicate, P parameter);
/**
* Returns true if the predicate evaluates to true for any element of the iterable.
* Returns false if the iterable is empty, or if no element returned true when evaluating the predicate.
*
* @since 1.0
*/
boolean anySatisfy(Predicate predicate);
/**
* Returns true if the predicate evaluates to true for any element of the collection, or return false.
* Returns false if the collection is empty.
*
* @since 5.0
*/
boolean anySatisfyWith(Predicate2 predicate, P parameter);
/**
* Returns true if the predicate evaluates to true for every element of the iterable or if the iterable is empty.
* Otherwise, returns false.
*
* @since 1.0
*/
boolean allSatisfy(Predicate predicate);
/**
* Returns true if the predicate evaluates to true for every element of the collection, or returns false.
*
* @since 5.0
*/
boolean allSatisfyWith(Predicate2 predicate, P parameter);
/**
* Returns true if the predicate evaluates to false for every element of the iterable or if the iterable is empty.
* Otherwise, returns false.
*
* @since 3.0
*/
boolean noneSatisfy(Predicate predicate);
/**
* Returns true if the predicate evaluates to false for every element of the collection, or return false.
* Returns true if the collection is empty.
*
* @since 5.0
*/
boolean noneSatisfyWith(Predicate2 predicate, P parameter);
/**
* Returns the final result of evaluating function using each element of the iterable and the previous evaluation
* result as the parameters. The injected value is used for the first parameter of the first evaluation, and the current
* item in the iterable is used as the second parameter. This method is commonly called fold or sometimes reduce.
*
* @since 1.0
*/
IV injectInto(IV injectedValue, Function2 function);
/**
* Returns the final int result of evaluating function using each element of the iterable and the previous evaluation
* result as the parameters. The injected value is used for the first parameter of the first evaluation, and the current
* item in the iterable is used as the second parameter.
*
* @since 1.0
*/
int injectInto(int injectedValue, IntObjectToIntFunction function);
/**
* Returns the final long result of evaluating function using each element of the iterable and the previous evaluation
* result as the parameters. The injected value is used for the first parameter of the first evaluation, and the current
* item in the iterable is used as the second parameter.
*
* @since 1.0
*/
long injectInto(long injectedValue, LongObjectToLongFunction function);
/**
* Returns the final float result of evaluating function using each element of the iterable and the previous evaluation
* result as the parameters. The injected value is used for the first parameter of the first evaluation, and the current
* item in the iterable is used as the second parameter.
*
* @since 2.0
*/
float injectInto(float injectedValue, FloatObjectToFloatFunction function);
/**
* Returns the final double result of evaluating function using each element of the iterable and the previous evaluation
* result as the parameters. The injected value is used for the first parameter of the first evaluation, and the current
* item in the iterable is used as the second parameter.
*
* @since 1.0
*/
double injectInto(double injectedValue, DoubleObjectToDoubleFunction function);
/**
* Converts the collection to a MutableList implementation.
*
* @since 1.0
*/
MutableList toList();
/**
* Converts the collection to a MutableList implementation and sorts it using the natural order of the elements.
*
* @since 1.0
*/
MutableList toSortedList();
/**
* Converts the collection to a MutableList implementation and sorts it using the specified comparator.
*
* @since 1.0
*/
MutableList toSortedList(Comparator comparator);
/**
* Converts the collection to a MutableList implementation and sorts it based on the natural order of the
* attribute returned by {@code function}.
*
* @since 1.0
*/
> MutableList toSortedListBy(Function function);
/**
* Converts the collection to a MutableSet implementation.
*
* @since 1.0
*/
MutableSet toSet();
/**
* Converts the collection to a MutableSortedSet implementation and sorts it using the natural order of the
* elements.
*
* @since 1.0
*/
MutableSortedSet toSortedSet();
/**
* Converts the collection to a MutableSortedSet implementation and sorts it using the specified comparator.
*
* @since 1.0
*/
MutableSortedSet toSortedSet(Comparator comparator);
/**
* Converts the collection to a MutableSortedSet implementation and sorts it based on the natural order of the
* attribute returned by {@code function}.
*
* @since 1.0
*/
> MutableSortedSet toSortedSetBy(Function function);
/**
* Converts the collection to the default MutableBag implementation.
*
* @since 1.0
*/
MutableBag toBag();
/**
* Converts the collection to a MutableSortedBag implementation and sorts it using the natural order of the
* elements.
*
* @since 6.0
*/
MutableSortedBag toSortedBag();
/**
* Converts the collection to the MutableSortedBag implementation and sorts it using the specified comparator.
*
* @since 6.0
*/
MutableSortedBag toSortedBag(Comparator comparator);
/**
* Converts the collection to a MutableSortedBag implementation and sorts it based on the natural order of the
* attribute returned by {@code function}.
*
* @since 6.0
*/
> MutableSortedBag toSortedBagBy(Function function);
/**
* Converts the collection to a MutableMap implementation using the specified key and value functions.
*
* @since 1.0
*/
MutableMap toMap(
Function keyFunction,
Function valueFunction);
/**
* Converts the collection to a MutableSortedMap implementation using the specified key and value functions
* sorted by the key elements' natural ordering.
*
* @since 1.0
*/
MutableSortedMap toSortedMap(
Function keyFunction,
Function valueFunction);
/**
* Converts the collection to a MutableSortedMap implementation using the specified key and value functions
* sorted by the given comparator.
*
* @since 1.0
*/
MutableSortedMap toSortedMap(
Comparator comparator,
Function keyFunction,
Function valueFunction);
/**
* Returns a lazy (deferred) iterable, most likely implemented by calling LazyIterate.adapt(this).
*
* @since 1.0.
*/
LazyIterable asLazy();
/**
* Converts this iterable to an array.
*
* @see Collection#toArray()
* @since 1.0
*/
Object[] toArray();
/**
* Converts this iterable to an array using the specified target array, assuming the target array is as long
* or longer than the iterable.
*
* @see Collection#toArray(Object[])
* @since 1.0
*/
T[] toArray(T[] target);
/**
* Returns the minimum element out of this container based on the comparator.
*
* @throws NoSuchElementException if the RichIterable is empty
* @since 1.0
*/
T min(Comparator comparator);
/**
* Returns the maximum element out of this container based on the comparator.
*
* @throws NoSuchElementException if the RichIterable is empty
* @since 1.0
*/
T max(Comparator comparator);
/**
* Returns the minimum element out of this container based on the natural order.
*
* @throws ClassCastException if the elements are not {@link Comparable}
* @throws NoSuchElementException if the RichIterable is empty
* @since 1.0
*/
T min();
/**
* Returns the maximum element out of this container based on the natural order.
*
* @throws ClassCastException if the elements are not {@link Comparable}
* @throws NoSuchElementException if the RichIterable is empty
* @since 1.0
*/
T max();
/**
* Returns the minimum elements out of this container based on the natural order of the attribute returned by Function.
*
* @throws NoSuchElementException if the RichIterable is empty
* @since 1.0
*/
> T minBy(Function function);
/**
* Returns the maximum elements out of this container based on the natural order of the attribute returned by Function.
*
* @throws NoSuchElementException if the RichIterable is empty
* @since 1.0
*/
> T maxBy(Function function);
/**
* Returns the final long result of evaluating function for each element of the iterable and adding the results
* together.
*
* @since 2.0
*/
long sumOfInt(IntFunction function);
/**
* Returns the final double result of evaluating function for each element of the iterable and adding the results
* together. It uses Kahan summation algorithm to reduce numerical error.
*
* @since 2.0
*/
double sumOfFloat(FloatFunction function);
/**
* Returns the final long result of evaluating function for each element of the iterable and adding the results
* together.
*
* @since 2.0
*/
long sumOfLong(LongFunction function);
/**
* Returns the final double result of evaluating function for each element of the iterable and adding the results
* together. It uses Kahan summation algorithm to reduce numerical error.
*
* @since 2.0
*/
double sumOfDouble(DoubleFunction function);
/**
* Groups and sums the values using the two specified functions.
*
* @since 6.0
*/
ObjectLongMap sumByInt(Function groupBy, IntFunction function);
/**
* Groups and sums the values using the two specified functions.
*
* @since 6.0
*/
ObjectDoubleMap sumByFloat(Function groupBy, FloatFunction function);
/**
* Groups and sums the values using the two specified functions.
*
* @since 6.0
*/
ObjectLongMap sumByLong(Function groupBy, LongFunction function);
/**
* Groups and sums the values using the two specified functions.
*
* @since 6.0
*/
ObjectDoubleMap sumByDouble(Function groupBy, DoubleFunction function);
/**
* Returns a string representation of this collection by delegating to {@link #makeString(String)} and defaulting
* the separator parameter to the characters ", " (comma and space).
*
* @return a string representation of this collection.
* @since 1.0
*/
String makeString();
/**
* Returns a string representation of this collection by delegating to {@link #makeString(String, String, String)}
* and defaulting the start and end parameters to "" (the empty String).
*
* @return a string representation of this collection.
* @since 1.0
*/
String makeString(String separator);
/**
* Returns a string representation of this collection. The string representation consists of a list of the
* collection's elements in the order they are returned by its iterator, enclosed in the start and end strings.
* Adjacent elements are separated by the separator string. Elements are converted to strings as by
* String.valueOf(Object).
*
* @return a string representation of this collection.
* @since 1.0
*/
String makeString(String start, String separator, String end);
/**
* Prints a string representation of this collection onto the given {@code Appendable}. Prints the string returned
* by {@link #makeString()}.
*
* @since 1.0
*/
void appendString(Appendable appendable);
/**
* Prints a string representation of this collection onto the given {@code Appendable}. Prints the string returned
* by {@link #makeString(String)}.
*
* @since 1.0
*/
void appendString(Appendable appendable, String separator);
/**
* Prints a string representation of this collection onto the given {@code Appendable}. Prints the string returned
* by {@link #makeString(String, String, String)}.
*
* @since 1.0
*/
void appendString(Appendable appendable, String start, String separator, String end);
/**
* For each element of the iterable, the function is evaluated and the results of these evaluations are collected
* into a new multimap, where the transformed value is the key and the original values are added to the same (or similar)
* species of collection as the source iterable.
*
* Example using a Java 8 method reference:
*
* Multimap<String, Person> peopleByLastName =
* people.groupBy(Person::getLastName);
*
*
* Example using an anonymous inner class:
*
* Multimap<String, Person> peopleByLastName =
* people.groupBy(new Function<Person, String>()
* {
* public String value(Person person)
* {
* return person.getLastName();
* }
* });
*
*
* @since 1.0
*/
Multimap groupBy(Function function);
/**
* Same as {@link #groupBy(Function)}, except that the results are gathered into the specified {@code target}
* multimap.
*
* Example using a Java 8 method reference:
*
* FastListMultimap<String, Person> peopleByLastName =
* people.groupBy(Person::getLastName, new FastListMultimap<String, Person>());
*
*
* Example using an anonymous inner class:
*
* FastListMultimap<String, Person> peopleByLastName =
* people.groupBy(new Function<Person, String>()
* {
* public String value(Person person)
* {
* return person.getLastName();
* }
* }, new FastListMultimap<String, Person>());
*
*
* @since 1.0
*/
> R groupBy(Function function, R target);
/**
* Similar to {@link #groupBy(Function)}, except the result of evaluating function will return a collection of keys
* for each value.
*
* @since 1.0
*/
Multimap groupByEach(Function> function);
/**
* Same as {@link #groupByEach(Function)}, except that the results are gathered into the specified {@code target}
* multimap.
*
* @since 1.0
*/
> R groupByEach(
Function> function,
R target);
/**
* For each element of the iterable, the function is evaluated and he results of these evaluations are collected
* into a new map, where the transformed value is the key. The generated keys must each be unique, or else an
* exception is thrown.
*
* @throws IllegalStateException if the keys returned by the function are not unique
* @see #groupBy(Function)
* @since 5.0
*/
MapIterable groupByUniqueKey(Function function);
/**
* Same as {@link #groupByUniqueKey(Function)}, except that the results are gathered into the specified {@code target}
* map.
*
* @throws IllegalStateException if the keys returned by the function are not unique
* @see #groupByUniqueKey(Function)
* @since 6.0
*/
> R groupByUniqueKey(
Function function,
R target);
/**
* Returns a string representation of this RichIterable. The string representation consists of a list of the
* RichIterable's elements in the order they are returned by its iterator, enclosed in square brackets
* ("[]"). Adjacent elements are separated by the characters ", " (comma and space). Elements
* are converted to strings as by {@link String#valueOf(Object)}.
*
* @return a string representation of this RichIterable
* @since 1.0
*/
String toString();
/**
* Returns a {@code RichIterable} formed from this {@code RichIterable} and another {@code RichIterable} by
* combining corresponding elements in pairs. If one of the two {@code RichIterable}s is longer than the other, its
* remaining elements are ignored.
*
* @param that The {@code RichIterable} providing the second half of each result pair
* @param the type of the second half of the returned pairs
* @return A new {@code RichIterable} containing pairs consisting of corresponding elements of this {@code
* RichIterable} and that. The length of the returned {@code RichIterable} is the minimum of the lengths of
* this {@code RichIterable} and that.
* @since 1.0
* @deprecated in 6.0. Use {@link OrderedIterable#zip(Iterable)} instead.
*/
@Deprecated
RichIterable> zip(Iterable that);
/**
* Same as {@link #zip(Iterable)} but uses {@code target} for output.
*
* @since 1.0
* @deprecated in 6.0. Use {@link OrderedIterable#zip(Iterable, Collection)} instead;
*/
@Deprecated
>> R zip(Iterable that, R target);
/**
* Zips this {@code RichIterable} with its indices.
*
* @return A new {@code RichIterable} containing pairs consisting of all elements of this {@code RichIterable}
* paired with their index. Indices start at 0.
* @see #zip(Iterable)
* @since 1.0
* @deprecated in 6.0. Use {@link OrderedIterable#zipWithIndex()} instead.
*/
@Deprecated
RichIterable> zipWithIndex();
/**
* Same as {@link #zipWithIndex()} but uses {@code target} for output.
*
* @since 1.0
* @deprecated in 6.0. Use {@link OrderedIterable#zipWithIndex(Collection)} instead.
*/
@Deprecated
>> R zipWithIndex(R target);
/**
* Partitions elements in fixed size chunks.
*
* @param size the number of elements per chunk
* @return A {@code RichIterable} containing {@code RichIterable}s of size {@code size}, except the last will be
* truncated if the elements don't divide evenly.
* @since 1.0
*/
RichIterable> chunk(int size);
/**
* Applies an aggregate procedure over the iterable grouping results into a Map based on the specific groupBy function.
* Aggregate results are required to be mutable as they will be changed in place by the procedure. A second function
* specifies the initial "zero" aggregate value to work with (i.e. new AtomicInteger(0)).
*
* @since 3.0
*/
MapIterable aggregateInPlaceBy(Function groupBy, Function0 zeroValueFactory, Procedure2 mutatingAggregator);
/**
* Applies an aggregate function over the iterable grouping results into a map based on the specific groupBy function.
* Aggregate results are allowed to be immutable as they will be replaced in place in the map. A second function
* specifies the initial "zero" aggregate value to work with (i.e. Integer.valueOf(0)).
*
* @since 3.0
*/
MapIterable aggregateBy(Function groupBy, Function0 zeroValueFactory, Function2 nonMutatingAggregator);
}