org.organicdesign.fp.collections.package.html Maven / Gradle / Ivy
Show all versions of UncleJim Show documentation
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.
We still want to extend these interfaces for backward compatibility.
- Unmodifiable
- This is similar to what the Collections.unmodifiableXxxx() methods return.
Thses interfaces implement the Mutable interfaces, but deprecate all mutate-in-place methods and throw UnsupportedOperationExceptions when those methods are called.
The "Unmod-" interfaces in this package extend the java.util mutable collections and provide an extension point for making new Immutable interfaces and collections.
In general, the "Unmod-" interfaces only take away mutation methods.
They do not add functionality, except UnmodIterable which adds transformation to all collections and UnmodMap which adds iterator() 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.
Each of the "Unmod" collection interfaces is then extended by an "Im" interface which represents an "Immutable" collection.
The Immutable interfaces further provide new alternative "set" methods which return the "altered" collection, as well as some convenience methods and hooks into the Sequence abstraction.
Finally, there are various implementations of the Immutable interfaces.
Most of those implementations (beginning with Persistent___) are copied from Clojure.