org.eclipse.collections.api.ordered.OrderedIterable Maven / Gradle / Ivy
/*
* Copyright (c) 2021 Goldman Sachs and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* and Eclipse Distribution License v. 1.0 which accompany this distribution.
* The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
* and the Eclipse Distribution License is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*/
package org.eclipse.collections.api.ordered;
import java.util.Collection;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.Optional;
import org.eclipse.collections.api.RichIterable;
import org.eclipse.collections.api.block.function.Function;
import org.eclipse.collections.api.block.function.Function2;
import org.eclipse.collections.api.block.function.primitive.BooleanFunction;
import org.eclipse.collections.api.block.function.primitive.ByteFunction;
import org.eclipse.collections.api.block.function.primitive.CharFunction;
import org.eclipse.collections.api.block.function.primitive.DoubleFunction;
import org.eclipse.collections.api.block.function.primitive.FloatFunction;
import org.eclipse.collections.api.block.function.primitive.IntFunction;
import org.eclipse.collections.api.block.function.primitive.LongFunction;
import org.eclipse.collections.api.block.function.primitive.ObjectIntToObjectFunction;
import org.eclipse.collections.api.block.function.primitive.ShortFunction;
import org.eclipse.collections.api.block.predicate.Predicate;
import org.eclipse.collections.api.block.predicate.Predicate2;
import org.eclipse.collections.api.block.predicate.primitive.ObjectIntPredicate;
import org.eclipse.collections.api.block.procedure.Procedure;
import org.eclipse.collections.api.block.procedure.primitive.ObjectIntProcedure;
import org.eclipse.collections.api.factory.Stacks;
import org.eclipse.collections.api.multimap.ordered.OrderedIterableMultimap;
import org.eclipse.collections.api.ordered.primitive.OrderedBooleanIterable;
import org.eclipse.collections.api.ordered.primitive.OrderedByteIterable;
import org.eclipse.collections.api.ordered.primitive.OrderedCharIterable;
import org.eclipse.collections.api.ordered.primitive.OrderedDoubleIterable;
import org.eclipse.collections.api.ordered.primitive.OrderedFloatIterable;
import org.eclipse.collections.api.ordered.primitive.OrderedIntIterable;
import org.eclipse.collections.api.ordered.primitive.OrderedLongIterable;
import org.eclipse.collections.api.ordered.primitive.OrderedShortIterable;
import org.eclipse.collections.api.partition.ordered.PartitionOrderedIterable;
import org.eclipse.collections.api.stack.MutableStack;
import org.eclipse.collections.api.tuple.Pair;
/**
* An OrderedIterable is a RichIterable with some meaningful order, such as insertion order, access order, or sorted order.
*
* @since 6.0
*/
public interface OrderedIterable extends RichIterable
{
/**
* Returns the index of the first occurrence of the specified item
* in this iterable, or -1 if this iterable does not contain the item.
*
* @see List#indexOf(Object)
*/
default int indexOf(Object object)
{
return this.detectIndex(each -> Objects.equals(each, object));
}
/**
* 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.
*/
@Override
T getFirst();
/**
* Returns the first element of an iterable as an Optional. 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, {@link Optional#empty} is returned.
*
* @throws NullPointerException if the element is null
* @since 8.2
*/
default Optional getFirstOptional()
{
if (this.isEmpty())
{
return Optional.empty();
}
return Optional.of(this.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.
*/
@Override
T getLast();
/**
* Returns the last element of an iterable as an Optional. 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, {@link Optional#empty} is returned.
*
* @throws NullPointerException if the element is null
* @since 8.2
*/
default Optional getLastOptional()
{
if (this.isEmpty())
{
return Optional.empty();
}
return Optional.of(this.getLast());
}
@Override
OrderedIterable tap(Procedure procedure);
/**
* Returns the initial elements that satisfy the Predicate. Short circuits at the first element which does not
* satisfy the Predicate.
*/
OrderedIterable takeWhile(Predicate predicate);
/**
* Returns the final elements that do not satisfy the Predicate. Short circuits at the first element which does
* satisfy the Predicate.
*/
OrderedIterable dropWhile(Predicate predicate);
/**
* Returns a Partition of the initial elements that satisfy the Predicate and the remaining elements. Short circuits at the first element which does
* satisfy the Predicate.
*/
PartitionOrderedIterable partitionWhile(Predicate predicate);
/**
* Returns a new {@code OrderedIterable} containing the distinct elements in this iterable.
*
* Conceptually similar to {@link #toSet()}.{@link #toList()} but retains the original order. If an element appears
* multiple times in this iterable, the first one will be copied into the result.
*
* @return {@code OrderedIterable} of distinct elements
*/
OrderedIterable distinct();
/**
* Returns true if both OrderedIterables have the same length
* and {@code predicate} returns true for all corresponding elements e1 of
* this {@code OrderedIterable} and e2 of {@code other}.
* The {@code predicate} is evaluated for each element at the same position of each {@code OrderedIterable} in a forward iteration order.
* This is a short circuit pattern.
*
* @since 6.0
*/
boolean corresponds(OrderedIterable other, Predicate2 predicate);
/**
* Iterates over the section of the iterable covered by the specified inclusive indexes. The indexes are
* both inclusive.
*
* e.g.
* OrderedIterable<Person> people = FastList.newListWith(ted, mary, bob, sally)
* people.forEach(0, 1, person -> LOGGER.info(person.getName()));
*
*
* This code would output ted and mary's names.
*/
void forEach(int startIndex, int endIndex, Procedure procedure);
/**
* Iterates over the iterable passing each element and the current relative int index to the specified instance of
* ObjectIntProcedure
*
e.g.
* people.forEachWithIndex((person, index) -> LOGGER.info("Index: " + index + " person: " + person.getName()));
*
*/
@Override
void forEachWithIndex(ObjectIntProcedure objectIntProcedure);
/**
* Iterates over the section of the iterable covered by the specified inclusive indexes. The indexes are
* both inclusive.
*
* e.g.
* OrderedIterable<People> people = FastList.newListWith(ted, mary, bob, sally)
* people.forEachWithIndex(0, 1, (person, index) -> LOGGER.info(person.getName()));
*
*
* This code would output ted and mary's names.
*/
void forEachWithIndex(int fromIndex, int toIndex, ObjectIntProcedure objectIntProcedure);
/**
* Converts the OrderedIterable to a mutable MutableStack implementation.
*/
default MutableStack toStack()
{
return Stacks.mutable.withAll(this);
}
/**
* Returns the minimum element out of this container based on the natural order, not the order of this container.
* If you want the minimum element based on the order of this container, use {@link #getFirst()}.
*
* @throws ClassCastException if the elements are not {@link Comparable}
* @throws NoSuchElementException if the OrderedIterable is empty
*/
@Override
T min();
/**
* Returns the maximum element out of this container based on the natural order, not the order of this container.
* If you want the maximum element based on the order of this container, use {@link #getLast()}.
*
* @throws ClassCastException if the elements are not {@link Comparable}
* @throws NoSuchElementException if the OrderedIterable is empty
*/
@Override
T max();
@Override
OrderedIterable select(Predicate predicate);
@Override
OrderedIterable selectWith(Predicate2 predicate, P parameter);
@Override
OrderedIterable reject(Predicate predicate);
@Override
OrderedIterable rejectWith(Predicate2 predicate, P parameter);
@Override
PartitionOrderedIterable partition(Predicate predicate);
@Override
PartitionOrderedIterable partitionWith(Predicate2 predicate, P parameter);
@Override
OrderedIterable selectInstancesOf(Class clazz);
@Override
OrderedIterable collect(Function function);
/**
* Returns a new OrderedIterable using results obtained by applying the specified function to each element
* and its corresponding index.
*
* @since 9.1.
*/
default OrderedIterable collectWithIndex(ObjectIntToObjectFunction function)
{
int[] index = {0};
return this.collect(each -> function.valueOf(each, index[0]++));
}
/**
* Adds elements to the target Collection using results obtained by applying the specified function to each element
* and its corresponding index.
*
* @since 9.1.
*/
default > R collectWithIndex(ObjectIntToObjectFunction function, R target)
{
int[] index = {0};
return this.collect(each -> function.valueOf(each, index[0]++), target);
}
/**
* Adds all elements to the target Collection that return true when evaluating the specified predicate which is
* supplied each element and its relative index.
*
* @since 11.0
*/
default > R selectWithIndex(ObjectIntPredicate predicate, R target)
{
int[] index = {0};
return this.select(each -> predicate.accept(each, index[0]++), target);
}
/**
* Adds all elements to the target Collection that return false when evaluating the specified predicate which is
* supplied each element and its relative index.
*
* @since 11.0
*/
default > R rejectWithIndex(ObjectIntPredicate predicate, R target)
{
int[] index = {0};
return this.reject(each -> predicate.accept(each, index[0]++), target);
}
@Override
OrderedIterable collectWith(Function2 function, P parameter);
@Override
OrderedIterable collectIf(Predicate predicate, Function function);
@Override
OrderedIterable flatCollect(Function> function);
/**
* @since 9.2
*/
@Override
default OrderedIterable flatCollectWith(Function2> function, P parameter)
{
return this.flatCollect(each -> function.apply(each, parameter));
}
@Override
OrderedBooleanIterable collectBoolean(BooleanFunction booleanFunction);
@Override
OrderedByteIterable collectByte(ByteFunction byteFunction);
@Override
OrderedCharIterable collectChar(CharFunction charFunction);
@Override
OrderedDoubleIterable collectDouble(DoubleFunction doubleFunction);
@Override
OrderedFloatIterable collectFloat(FloatFunction floatFunction);
@Override
OrderedIntIterable collectInt(IntFunction intFunction);
@Override
OrderedLongIterable collectLong(LongFunction longFunction);
@Override
OrderedShortIterable collectShort(ShortFunction shortFunction);
/**
* Returns the index of the first element of the {@code OrderedIterable} for which the {@code predicate} evaluates to true.
* Returns -1 if no element evaluates true for the {@code predicate}.
*
* @since 6.0
*/
int detectIndex(Predicate predicate);
@Override
OrderedIterableMultimap groupBy(Function function);
@Override
OrderedIterableMultimap groupByEach(Function> function);
/**
* Returns a {@code OrderedIterable} formed from this {@code OrderedIterable} and another {@code Iterable} by
* combining corresponding elements in pairs. The second {@code Iterable} should also be ordered.
* If one of the two {@code Iterable}s is longer than the other, its
* remaining elements are ignored.
*
* @param that The {@code Iterable} providing the second half of each result pair
* @param the type of the second half of the returned pairs
* @return A new {@code OrderedIterable} containing pairs consisting of corresponding elements of this {@code
* OrderedIterable} and that. The length of the returned {@code OrderedIterable} is the minimum of the lengths of
* this {@code OrderedIterable} and that.
*/
@Override
OrderedIterable> zip(Iterable that);
/**
* Same as {@link #zip(Iterable)} but uses {@code target} for output.
*/
@Override
>> R zip(Iterable that, R target);
@Override
OrderedIterable> zipWithIndex();
/**
* Same as {@link #zipWithIndex()} but uses {@code target} for output.
*/
@Override
>> R zipWithIndex(R target);
}