Package org.organicdesign.fp.collections

Type-safe versions of immutable collections (mostly from Clojure), plus unmodifiable and immutable collection interfaces that fit these collections into the java.util interfaces. This is a multi-step process. The Unmod____ interfaces deprecate the mutate-in-place methods. The Base___ interfaces add the fluent/copy-on-write mutator methods. Those are extended by Im___ immutable interfaces and Mut___ mutable interfaces which are reflections of each other. The Mut___ interfaces represent faster builders for the immutable collections, but sometimes a mutable collection is useful in its own right.

Definitions

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.

Base

This adds the fluent copy-on-write "modification" methods and is the common ancestor of Im___ and Mut___ interfaces.

Immutable

The collection itself cannot be changed in place. Fluent "modification" methods 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.

Mutable

These are mutate-in-place collections, but with largely the same fluent interfaces as the Immutable ones. They also extend Transformable, so you can still be in a mostly functional happy world.

Just about everything extends/implements Transformable.

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.

Interface Summary

Interface	Description
BaseList<E>	Adds copy-on-write, "fluent interface" methods to UnmodList.
BaseMap<K,V>	Adds copy-on-write, "fluent interface" methods to UnmodMap.
BaseSet<E>	Adds copy-on-write, "fluent interface" methods to UnmodSet.
BaseUnsortedMap<K,V>	Adds BaseUnsortedMap.equator() to BaseMap which is an unsorted-only operation.
ComparisonContext<T>	Represents a context for comparison because sometimes you order the same things differently.
Equator<T>	An Equator represents an equality context in a way that is analgous to the java.util.Comparator interface.
ImList<E>	Immutable copy-on-write list
ImMap<K,V>	An immutable map with no guarantees about its ordering.
ImSet<E>	An immutable set with no guarantees about its ordering
ImSortedMap<K,V>	An immutable sorted map.
ImSortedSet<E>	An immutable sorted set interface
MutList<E>	A mutate-in-place interface using the same copy-on-write methods as BaseList and ImList so that you can treat mutable and immutable lists the same.
MutMap<K,V>	Interface for mutable (hash) map builder.
MutSet<E>	Interface for mutable (hash) set builder.
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>	Formalizes the return type of Collections.unmodifiableList(List), deprecating mutator methods and implementing them to throw exceptions.
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
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.
AbstractUnmodMap<K,V>	Implements equals() and hashCode() methods compatible with java.util.Map (which ignores order) to make defining unmod Maps easier.
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.
Cowry	Cowry is short for Copy On Write aRraY and contains utilities for doing this quickly and correctly.
PersistentHashMap<K,V>	Rich Hickey's immutable rendition of Phil Bagwell's Hash Array Mapped Trie.
PersistentHashMap.MutHashMap<K,V>
PersistentHashSet<E>	A wrapper that turns a PersistentTreeMap into a set.
PersistentHashSet.MutHashSet<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.MutVector<F>
RangeOfInt	An efficient (in both time and memory) implementation of List.
RrbTree<E>	An RRB Tree is an immutable List (like Clojure's PersistentVector) that also supports random inserts, deletes, and can be split and joined back together in logarithmic time.
RrbTree.ImRrbt<E>	Immutable version of an RrbTree.
RrbTree.MutRrbt<E>	Mutable version of an RrbTree.
UnmodList.AbstractUnmodList<E>	Implements equals and hashCode() methods compatible with java.util.List (which ignores order) to make defining unmod lists 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>
UnmodSortedIterator.Wrapper<E>

Enum Summary

Enum	Description
ComparisonContext.CompCtx	Please access this type-safely through ComparisonContext.defCompCtx() instead of calling directly.
Equator.Comp
Equator.Equat
RangeOfInt.Equat
UnmodIterable.UnIterable
UnmodIterator.UnIterator	Instead of calling this directly, please use UnmodIterator.emptyUnmodIterator() instead