Package org.organicdesign.fp.collections

Type-safe versions of the immutable Clojure collections, plus unmodifiable and immutable collection interfaces that extend the java.util collections, deprecating the mutate-in-place methods (Unmod____) and adding methods that return a new, immutable, modified version of the collection (Im____).

See: Description

Interface Summary

Interface	Description
ComparisonContext<T>	Implement compare() and hash() and you get a 100% compatible eq() for free.
Equator<T>	An Equator represents an equality context in a way that is analgous to the java.util.Comparator interface.
ImList<E>	Holds Immutable "modification" methods that return a new ImList reflecting the modification while sharing as much data structure with the previous ImList as possible (for performance).
ImMap<K,V>	An immutable map with no guarantees about its ordering.
ImMapTrans<K,V>	Deprecated
ImSet<E>	An immutable set interface
ImSortedMap<K,V>	An immutable sorted map.
ImSortedSet<E>	An immutable sorted set interface
ImUnsortedMap<K,V>	Interface for unsorted (today that probably means "hash") maps.
ImUnsortedSet<E>	The super-interface of PersistentHashSet (excludes TreeSet).
MutableList<E>	You could think of this as a builder for an immutable map.
MutableUnsortedMap<K,V>	Interface for mutable (hash) map builder.
MutableUnsortedSet<E>	Declare your set as MutableUnsortedSet, call mutable(), build it, then call mySet = mySet.immutable() without having to declare a new variable.
Sized
UnmodCollection<E>	Don't implement this interface directly if you don't have to.
UnmodIterable<T>	An unmodifiable Iterable, without any guarantee about order.
UnmodIterator<E>	A one-time use, mutable, not-thread-safe way to get each value of the underling collection in turn.
UnmodList<E>	An unmodifiable version of List which formalizes the return type of Collections.unmodifiableList()
UnmodListIterator<E>	An unmodifiable ListIterator
UnmodMap<K,V>	An unmodifiable map.
UnmodMap.UnEntry<K,V>	A map entry (key-value pair).
UnmodSet<E>	An unmodifiable set
UnmodSortedCollection<E>
UnmodSortedIterable<T>	An unmodifiable Iterable, with guaranteed order.
UnmodSortedIterator<E>	This represents an iterator with a guaranteed ordering.
UnmodSortedMap<K,V>	An unmodifiable SortedMap.
UnmodSortedSet<E>	An unmodifiable SortedSet.

Class Summary

Class	Description
KeyVal<K,V>	Deprecated
PersistentHashMap<K,V>	Rich Hickey's immutable rendition of Phil Bagwell's Hash Array Mapped Trie.
PersistentHashMap.MutableHashMap<K,V>
PersistentHashSet<E>	A wrapper that turns a PersistentTreeMap into a set.
PersistentHashSet.MutableHashSet<E>
PersistentTreeMap<K,V>	Persistent Red Black Tree.
PersistentTreeSet<E>	A wrapper that turns a PersistentTreeMap into a set.
PersistentVector<E>	This started out as Rich Hickey's PersistentVector class from Clojure in late 2014.
PersistentVector.MutableVector<F>
RangeOfInt	An efficient (in both time and memory) implementation of List.
UnmodIterable.AbstractUnmodIterable<T>	Implements equals and hashCode() methods compatible with all java.util collections (this algorithm is not order-dependent) and toString which takes the name of the sub-class.
UnmodIterator.Wrapper<E>	Deprecated
UnmodList.AbstractUnmodList<E>	Implements equals and hashCode() methods compatible with java.util.Set (which ignores order) to make defining unmod sets easier, especially for implementing Map.keySet() and such.
UnmodMap.AbstractUnmodMap<K,V>	Implements equals and hashCode() methods compatible with java.util.Map (which ignores order) to make defining unmod Maps easier.
UnmodMap.UnEntry.EntryToUnEntryIter<K,V>
UnmodMap.UnEntry.EntryToUnEntrySortedIter<K,V>
UnmodMap.UnEntry.UnmodKeyIter<K,V>
UnmodMap.UnEntry.UnmodSortedKeyIter<K,V>
UnmodMap.UnEntry.UnmodSortedValIter<K,V>
UnmodMap.UnEntry.UnmodValIter<K,V>
UnmodSet.AbstractUnmodSet<T>	Implements equals and hashCode() methods compatible with java.util.Set (which ignores order) to make defining unmod sets easier, especially for implementing Map.keySet() and such.
UnmodSortedIterator.Wrapper<E>

Enum Summary

Enum	Description
ComparisonContext.CompCtx
Equator.Comp
Equator.Equat
RangeOfInt.Equat

Package org.organicdesign.fp.collections Description

Type-safe versions of the immutable Clojure collections, plus unmodifiable and immutable collection interfaces that extend the java.util collections, deprecating the mutate-in-place methods (Unmod____) and adding methods that return a new, immutable, modified version of the collection (Im____).

Definitions

Mutable

This describes the mutate-in-place philosophy of the java.util collections. This was sensible when they were created in the 1990's when memory was expensive, the garbage collector was in its infancy, and multi-processor systems were rare. Today, memory is cheap, the garbage collector is one of the wonders of the modern world, and even your phone has several processors. But we still need to extend these interfaces for backward compatibility.

Unmodifiable

This is similar to what the Collections.unmodifiableXxxx() methods return. The "Unmod-" interfaces in this package extend the java.util mutable collections, but deprecate all mutate-in-place methods and throw UnsupportedOperationExceptions when those methods are called. These interfaces also provide an extension point for making new Immutable interfaces and collections. In general, the "Unmod-" interfaces do not add functionality, except UnmodIterable adds transformation to all collections and UnmodMap adds Iterable<Map.Entry> to Map.

Immutable

This is what the Clojure collections provide. The collection itself cannot be changed, yet it has "modification" methods that return a new immutable collection reflecting the change while still sharing as much data as possible with the original collection so that these methods are relatively fast and lightweight.

Description

We want to make it as easy as possible to live in an immutable world while working with existing Java code. In a perfect world, all the Java APIs and existing code would be magically rewritten to use Immutable (according to the above definition) collections.

This package contains Unmodifiable "Unmod" interfaces which override, deprecate, and implement each of the "set" methods in the java.util collections interfaces. They also provide built-in Transformations (inherited from UnmodIterable). These interfaces were extremely useful before the "Im" implementations were added to this project, but may be able to be worked into the Immutable interfaces some day. If you find the "Unmod" interfaces really useful, please speak up!

Each of the "Unmod" interfaces is eventually extended by an "Im" interface which represent "Immutable" collections. The Immutable interfaces provide alternative "set" methods which return the altered collection, as well as some convenience methods.

Finally, there are various implementations of the Immutable interfaces. Most of those implementations (beginning with Persistent___) are derivative works of the source code for Clojure.