org.pkl.thirdparty.paguro.collections.package.html Maven / Gradle / Ivy
Show all versions of pkl-tools Show documentation
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 {@link org.organicdesign.fp.xform.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.