org.eclipse.collections.api.stack.StackIterable Maven / Gradle / Ivy
/*
* Copyright (c) 2017 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.stack;
import java.util.List;
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.procedure.Procedure;
import org.eclipse.collections.api.factory.Stacks;
import org.eclipse.collections.api.list.ListIterable;
import org.eclipse.collections.api.multimap.list.ListMultimap;
import org.eclipse.collections.api.ordered.OrderedIterable;
import org.eclipse.collections.api.partition.stack.PartitionStack;
import org.eclipse.collections.api.stack.primitive.BooleanStack;
import org.eclipse.collections.api.stack.primitive.ByteStack;
import org.eclipse.collections.api.stack.primitive.CharStack;
import org.eclipse.collections.api.stack.primitive.DoubleStack;
import org.eclipse.collections.api.stack.primitive.FloatStack;
import org.eclipse.collections.api.stack.primitive.IntStack;
import org.eclipse.collections.api.stack.primitive.LongStack;
import org.eclipse.collections.api.stack.primitive.ShortStack;
import org.eclipse.collections.api.tuple.Pair;
/**
* StackIterable is a last-in-first-out data structure. All iteration methods iterate from the "top" of the stack to the
* "bottom". In other words, it processes the most recently added elements first.
*
* For example:
*
* {@link #forEach(Procedure)} iterates over every element, starting with the most recently added
*
* {@link #getFirst()} returns the most recently added element, not the element that was added first
*
* {@link #toString()} follows the same rules as {@link java.util.AbstractCollection#toString()} except it processes the elements
* in the same order as {@code forEach()}.
*/
public interface StackIterable extends OrderedIterable
{
/**
* Returns the element at the top of the stack, without removing it from the stack.
*
* @return the top of the stack.
*/
T peek();
/**
* @return a ListIterable of the number of elements specified by the count, beginning with the top of the stack.
*/
ListIterable peek(int count);
/**
* Returns the element at a specific index, without removing it from the stack.
*
* @param index the location to peek into
* @return the element at the specified index
*/
T peekAt(int index);
/**
* Should return the same value as peek().
*/
@Override
default T getFirst()
{
return this.peek();
}
/**
* Should not work as it violates the contract of a Stack.
*/
@Override
T getLast();
/**
* Follows the same rules as {@link java.util.AbstractCollection#toString()} except it processes the elements
* in the same order as {@code forEach()}.
*
* Assert.assertEquals("[3, 2, 1]", Stacks.mutable.with(1, 2, 3).toString());
*
*/
@Override
String toString();
/**
* Follows the same general contract as {@link List#equals(Object)}, but for Stacks.
*/
@Override
boolean equals(Object o);
/**
* Follows the same general contract as {@link List#hashCode()}, but for Stacks.
*/
@Override
int hashCode();
@Override
StackIterable takeWhile(Predicate predicate);
@Override
StackIterable dropWhile(Predicate predicate);
@Override
PartitionStack partitionWhile(Predicate predicate);
@Override
StackIterable distinct();
/**
* Converts the stack to a MutableStack implementation.
*
* @since 2.0
*/
@Override
default MutableStack toStack()
{
return Stacks.mutable.withAllReversed(this);
}
@Override
StackIterable tap(Procedure procedure);
@Override
StackIterable select(Predicate predicate);
@Override
StackIterable selectWith(Predicate2 predicate, P parameter);
@Override
StackIterable reject(Predicate predicate);
@Override
StackIterable rejectWith(Predicate2 predicate, P parameter);
@Override
StackIterable selectInstancesOf(Class clazz);
@Override
PartitionStack partition(Predicate predicate);
@Override
PartitionStack partitionWith(Predicate2 predicate, P parameter);
@Override
StackIterable collect(Function function);
@Override
BooleanStack collectBoolean(BooleanFunction booleanFunction);
@Override
ByteStack collectByte(ByteFunction byteFunction);
@Override
CharStack collectChar(CharFunction charFunction);
@Override
DoubleStack collectDouble(DoubleFunction doubleFunction);
@Override
FloatStack collectFloat(FloatFunction floatFunction);
@Override
IntStack collectInt(IntFunction intFunction);
@Override
LongStack collectLong(LongFunction longFunction);
@Override
ShortStack collectShort(ShortFunction shortFunction);
@Override
StackIterable collectWith(Function2 function, P parameter);
@Override
StackIterable collectIf(Predicate predicate, Function function);
/**
* @since 9.1.
*/
@Override
default StackIterable collectWithIndex(ObjectIntToObjectFunction function)
{
int[] index = {0};
return this.collect(each -> function.valueOf(each, index[0]++));
}
@Override
StackIterable flatCollect(Function> function);
/**
* @since 9.2
*/
@Override
default StackIterable flatCollectWith(Function2> function, P parameter)
{
return this.flatCollect(each -> function.apply(each, parameter));
}
@Override
ListMultimap groupBy(Function function);
@Override
ListMultimap groupByEach(Function> function);
@Override
StackIterable> zip(Iterable that);
@Override
StackIterable> zipWithIndex();
/**
* Converts the StackIterable to an immutable implementation. Returns this for immutable stacks.
*
* @since 5.0
*/
ImmutableStack toImmutable();
}