2.0.0 (August 2012)
Binaries
Javadoc
JDiff
API differences between 1.2.0 and 2.0.0
New Functionality
Stack Container
A stack is a collection enforcing a last-in, first-out order; its methods iterate over elements beginning with the most-recently added element.
The StackIterable interface extends RichIterable and its methods such as forEach and toString process elements in reverse order of their addition to the stack. MutableStack extends StackIterable and adds mutating methods like push, pop, and clear.
The concrete type is ArrayStack. The current implementation delegates to a FastList and thus has similar runtime complexity. For example, ArrayStack's push method takes amortized constant time, like FastList's add method. In GS Collections, stacks are not lists. This is a deliberate difference from java.util.Stack which extends Vector.
| push | Adds a new element to the top of the stack. |
| pop | Returns the top (most recently-added) element and removes it from the collection |
| pop(int count) | Returns a ListIterable of the number of elements specified by the count, beginning with the top of the stack. |
| peek | Returns but does not remove the top element. Note that, on a stack, getFirst likewise returns the top element, and that getLast throws an exception. |
| peek(int count) | Returns a ListIterable of the number of elements specified by the count, beginning with the top of the stack; does not remove the elements from the stack. |
| peekAt(int index) | Returns the element at index. |
To create a MutableStack, use one of the following static factory methods:
MutableStack<Integer> emptyStack = ArrayStack.newStack();
MutableStack<Integer> mutableStack = ArrayStack.newStackWith(1, 2, 3);
MutableStack<Integer> stackFromFastList = ArrayStack.newStack(FastList.newListWith(1, 2, 3));
MutableStack<Integer> stackFromTopToBottom = ArrayStack.newStackFromTopToBottom(3, 2, 1);
MutableStack<Integer> stackUsingStacksFactory = Stacks.mutable.of(1, 2, 3);ConcurrentHashMap
GS Collections 2.0 includes a new concurrent hashmap implementation, com.gs.collections.impl.map.mutable.ConcurrentHashMap.
Primitive Iterables and their Lazy Implementations
The primitive iterable interfaces are memory-optimized for primitives.
| int | IntIterable |
| long | LongIterable |
| float | FloatIterable |
| double | DoubleIterable |
They are inspired by the RichIterable interface, and contain a subset of the iteration pattern methods from RichIterable like collect. They add some primitive specific API like sum, average, etc. They also include Iterators specialized for each primitive type. They do not extend Iterator, to prevent accidental auto-boxing.
The current implementations use lazy evaluation. Here's an example which calculates the average of a collection of ints.
double average = Interval.oneTo(4).collectInt(PrimitiveFunctions.unboxIntegerToInt()).average();Here, conllectInt() returns an instance of CollectIntIterable, an implementation of IntIterable. CollectIntIterable transforms a source iterable using an IntFunction as it iterates.
The PrimitiveFunctions class has a number of common unboxing functions. For example PrimitiveFunctions.unboxIntegerToInt() returns an IntFunction.
More RichIterable API
selectInstancesOf()
Returns all elements of the source collection that are instances of the Class parameter.
MutableList<Number> numbers = FastList.newListWith(1.0, 2, 3.0, 4, 5.0);
MutableList<Integer> integers = numbers.selectInstancesOf(Integer.class);It is meant to address this problem with select and an “instanceOf” Predicate.
MutableList<Number> numbers = FastList.newListWith(1.0, 2, 3.0, 4, 5.0);
MutableList<Number> integers = numbers.select(Predicates.instanceOf(Integer.class));The result is a collection of Number instead of Integer. If we try to add a simple cast, we get a compiler error.
MutableList<Integer> integers = (MutableList<Integer>) numbers.select(Predicates.instanceOf(Integer.class));The error message tells us we’re trying to cast to an inconvertible type. We can use raw types, or do a double cast, but neither is intuitive.
MutableList<Integer> integers = (MutableList<Integer>) (MutableList<?>) numbers.select(Predicates.instanceOf(Integer.class));The new method selectInstancesOf() addresses these problems with types, plus and it’s concise and communicates what you’re doing.
sumOf() Methods - sumOfInt(), sumOfLong(), sumOfFloat(), sumOfDouble()
The sumOf methods return the final primitive result of evaluating function for each element of the iterable and adding elements together. For example, sumOfInt() takes an IntFunction and returns the int sum without auto-boxing.