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.
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.