Package com.bluegosling.collections

Various utilities that extend the Java Collections Framework (JCF).

See: Description

Interface Summary

Interface	Description
Stack<T>	A simple stack interface.

Class Summary

Class	Description
AbstractDeque<E>	An abstract base class for implementations of the Deque interface.
AbstractNavigableMap<K,V>	An abstract base class for NavigableMap implementations.
ArrayUtils	Utility methods for working with arrays that back collection implementations.
CircularBuffer<E>	A simple fixed-capacity buffer of object references.
CollectionUtils	Utility functions for implementing standard collection interfaces.
DescendingMap<K,V>
DescendingSet<E>	A NavigableSet that is a view of another set, but in opposite (descending) order.
FilteringCollection<E>	A filtered view of another collection.
FilteringIterable<E>	A filtered view of another iterable.
FilteringIterator<E>	A filtered view of another iterator.
FilteringList<E>	A filtered view of another list.
FilteringListIterator<E>	A filtered view of another list iterator.
FilteringMap<K,V>
FilteringNavigableMap<K,V>
FilteringNavigableSet<E>
FilteringSet<E>	A filtered view of another set.
FilteringSortedMap<K,V>
FilteringSortedSet<E>
MapUtils
MoreCollections
MoreIterables	Utility methods for working with and creating instances of Iterable.
MoreIterators	Utility methods for working with and creating instanceos of Iterator.
MoreMaps	Utility methods for working with and creating instanceos of Map.
MoreSets	Utility methods for working with and creating instanceos of Set.
MoreSpliterators	Utility methods for working with and creating instances of Spliterator.
MoreStreams	Utility methods for working with and creating instances of Stream.
NoCopyGrowableArray<T>	A growable array that does not require doubling and copying an underlying array.
TransformingCollection<I,O>	A collection whose elements are the results of applying a function to another collection.
TransformingCollection.Bidi<I,O>	A transforming collection that can transform values in both directions.
TransformingCollection.ReadOnly<I,O>	An unmodifiable transforming collection.
TransformingIterable<I,O>	An iterable whose elements are the results of applying a function to another iterable.
TransformingIterable.ReadOnly<I,O>	An unmodifiable transforming iterable.
TransformingIterator<I,O>	An iterator whose elements are the results of applying a function to results from another iterator.
TransformingIterator.ReadOnly<I,O>	An unmodifiable transforming iterator.
TransformingList<I,O>	A list whose elements are the results of applying a function to another list.
TransformingList.Bidi<I,O>	A transforming list that can transform values in both directions.
TransformingList.Bidi.RandomAccess<I,O>	A bidirectional transforming list that also has the RandomAccess marker interface.
TransformingList.RandomAccess<I,O>	A transforming list that supports random access to its elements.
TransformingList.ReadOnly<I,O>	An unmodifiable transforming list.
TransformingList.ReadOnly.RandomAccess<I,O>	A read-only transforming list that also has the RandomAccess marker interface.
TransformingListIterator<I,O>	A list iterator whose elements are the results of applying a function to results from another iterator.
TransformingListIterator.Bidi<I,O>	A transforming list iterator that can transform values in both directions.
TransformingListIterator.ReadOnly<I,O>	An unmodifiable transforming list iterator.
TransformingMap<KI,VI,KO,VO>	A map whose keys and/or values are the results of applying functions to the keys and/or values of another map.
TransformingMap.Bidi<KI,VI,KO,VO>	A transforming map that can transform keys and values in both directions.
TransformingMap.ReadOnly<KI,VI,KO,VO>	An unmodifiable transforming map.
TransformingMap.ReadOnly.ValuesOnly<K,VI,VO>	An unmodifiable transforming map that can only transform values, not keys.
TransformingMap.ValuesOnly<K,VI,VO>	A TransformingMap that only transforms map values, not keys.
TransformingMapEntry<KI,VI,KO,VO>
TransformingMapEntry.Bidi<KI,VI,KO,VO>
TransformingSet<I,O>	A set whose elements are the results of applying a function to another collection.
TransformingSet.Bidi<I,O>	A transforming set that can transform values in both directions.
TransformingSet.ReadOnly<I,O>	An unmodifiable transforming set.

Enum Summary

Enum	Description
BoundType	The type of bound for a AbstractNavigableMap.SubMap.
IteratorModifiedState	Enumeration of possible modification states of the iterator.
SpliteratorCharacteristics	An enum for the various characteristics of a spliterator.

Package com.bluegosling.collections Description

Various utilities that extend the Java Collections Framework (JCF). These expand on similar utilities provided by Guava. The various sub-packages include new implementations and collection interfaces. This package contains a few different kinds of utilities, described in the sections below.

Static Utilities

In the vein of Guava's Lists, Sets, and Maps, this package has several classes with a variety of static utility methods. They include more stuff for standard JCF interfaces (such as MoreIterables, MoreCollections, and MoreMaps). And they also include stuff for interfaces new to Java 8 (such as MoreSpliterators and MoreStreams).

Views

This package includes classes that provide various views over other collection. Most of these views wrap a given collection (or iterable or iterator) and provide a filtered or transformed view of it using a function or a predicate, applied to each element as needed. Updates to the underlying collection are visible (depending on the results of applying the function or predicate) through this wrapper and vice versa.

The filtering and transforming views are very similar to related methods in Guava's Collections2, Lists, Sets, and Maps except that these are public types which can be sub-classed.

The filtering implementations provide O(n) performance for several methods that might usually run in constant time for other collection implementations, for example size(). This is because, to provide an up-to-date view of the backing collection, the filter must be applied to each element when these methods are used.

The transforming implementations have a few variants worth noting:

1. Normal: The standard transformed views accept a single function. Since the inverse of the function is not available, new elements cannot be added (since the actual element added to the underlying collection would need to be "un-transformed" into the source type). But other mutation operations will work. Some operation implementations, for example removing an element from a transformed set, will have O(n) performance, even when the underlying implementation may provide sub-linear performance. This is similar to the functionality provided by Guava's utility methods.
2. ReadOnly: A read-only transformed view will throw UnsupportedOperationException for all mutation operations. The view will still reflect changes made to the underlying collection. But changes cannot directly be made through the view. This can be convenient when you want to avoid double-wrapping -- e.g. in both a transforming view and an unmodifiable view.
3. Bidi: A bi-directional transformed view accepts two functions -- a transform and its inverse. This allows the collection to support add operations. Implementations that run in O(n) time with a normal view, such as removing an element from a set, can instead run in sub-linear time if the underlying collection provides sub-linear performance. This variant has no analog in Guava's utility methods.

Other functionality present here that is not present in Guava's utility methods is the ability to filter lists, transform sets, and transform map keys.

A third category of classes is also in this package: descending views. These are not necessarily useful by themselves, but are intended to be used when implementing new navigable maps and sets. If your map or set implements every operation other than the descending ones (and none in terms of the descending ones), then these classes can be used to easily implement the descending ones.

Abstract Base Classes

This package includes useful base classes for new implementations of Deque and NavigableMap.

Other

The sub-packages contain a greater variety of new collections, grouped by collection type (e.g. list, set, queue, map, etc). But there are also a few in this package:

• CircularBuffer: a circular buffer of reference-type elements. This buffer is much simpler than related primitive buffers in java.nio.
• NoCopyGrowableArray: a new collection that is a growable array but does not incur the expense of copying on growth. It implements the List interface and provides constant time random access, too.
• Stack: a new collection interface for LIFO stacks. This is much narrower than existing JCF types used as stacks like Deque and List.