Package org.organicdesign.fp

Class StaticImports

  • public final class StaticImports
extends Object

    A mini data definition language composed of short methods like vec(), tup(), map(), set(), plus xform() which makes java.util collections transformable.

    import org.organicdesign.fp.StaticImports.*

// Create a new vector of integers
vec(1, 2, 3, 4);

// Create a new set of Strings
set("a", "b", "c");

// Create a tuple of an int and a string (a type-safe heterogeneous container)
tup("a", 1);

// Create a map with a few key value pairs
map(tup("a", 1),
    tup("b", 2),
    tup("c", 3));

    There are only a few methods in this project to take varargs and they are all in this file. Writing out versions that took multiple type-safe arguments caused IntelliJ to present all of them for auto-completion which was overwhelming, so I reverted to varargs. Also, varargs relax some type safety rules (variance) for data definition in a generally helpful (rarely dangerous) way.

    If you're used to Clojure/JSON, you'll find that what's a map (dictionary) in those languages sometimes becomes a tuple in Paguro and sometimes becomes a map. A map in a type-safe language is homogeneous, meaning that every member is of the same type (or a descendant of a common ancestor). Tuples are designed to contain unrelated data types and enforce those types.

    As with any usage of import *, there could be issues if you import 2 different versions of this file in your classpath, or if a method is ever removed from this file. Java needs a data definition language so badly that I think it is worth this small risk.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <K,​V>
      @NotNull ImMap<K,​V>      		 map​(@Nullable Map.Entry<K,​V>... kvPairs)
      Returns a new PersistentHashMap of the given keys and their paired values.
      static <K,​V>
      @NotNull MutMap<K,​V>      		 mutableMap​(@Nullable Map.Entry<K,​V>... kvPairs)
      Returns a new MutMap of the given keys and their paired values.
      static <T> @NotNull RrbTree.MutRrbt<T> mutableRrb​(T... items)
      Returns a mutable RRB Tree RrbTree of the given items.
      static <T> @NotNull MutSet<T> mutableSet​(T... items)
      Returns a new MutSet of the values.
      static <T> @NotNull MutList<T> mutableVec​(T... items)
      Returns a MutVector of the given items.
      static <T> @NotNull RrbTree.ImRrbt<T> rrb​(T... items)
      Returns a new immutable RRB Tree RrbTree.ImRrbt of the given items.
      static <T> @NotNull ImSet<T> set​(T... items)
      Returns a new PersistentHashSet of the values.
      static <K extends Comparable<K>,​V>
      @NotNull ImSortedMap<K,​V>      		 sortedMap​(Iterable<Map.Entry<K,​V>> kvPairs)
      Returns a new PersistentTreeMap of the given comparable keys and their paired values, sorted in the default ordering of the keys.
      static <K,​V>
      @NotNull ImSortedMap<K,​V>      		 sortedMap​(Comparator<? super K> comp, Iterable<Map.Entry<K,​V>> kvPairs)
      Returns a new PersistentTreeMap of the specified comparator and the given key/value pairs.
      static <T extends Comparable<T>>
      @NotNull ImSortedSet<T>      		 sortedSet​(Iterable<T> items)
      Returns a new PersistentTreeSet of the given comparable items.
      static <T> @NotNull ImSortedSet<T> sortedSet​(Comparator<? super T> comp, Iterable<T> elements)
      Returns a new PersistentTreeSet of the given comparator and items.
      static <T,​U>
      @NotNull Tuple2<T,​U>      		 tup​(T t, U u)
      Returns a new Tuple2 of the given items.
      static <T,​U,​V>
      @NotNull Tuple3<T,​U,​V>      		 tup​(T t, U u, V v)
      Returns a new Tuple3 of the given items.
      static <T> @NotNull ImList<T> vec​(T... items)
      Returns a new PersistentVector of the given items.
      static <T> @NotNull UnmodIterable<T> xform​(@Nullable Iterable<T> iterable)
      If you need to wrap a regular Java collection or other iterable outside this project to perform a transformation on it, this method is the most convenient, efficient way to do so.
      static <T> @NotNull UnmodIterable<T> xformArray​(T... items)
      If you need to wrap a regular Java array outside this project to perform a transformation on it, this method is the most convenient, efficient way to do so.
      static @NotNull UnmodIterable<Character> xformChars​(CharSequence seq)
      Wrap a String (or CharSequence) to perform a Character-by-Character transformation on it.

    • Method Detail

      • map

        @SafeVarargs
@NotNull
public static <K,​V> @NotNull ImMap<K,​V> map​(@Nullable
                                                        @Nullable Map.Entry<K,​V>... kvPairs)
        Returns a new PersistentHashMap of the given keys and their paired values. Use the tup(Object, Object) method to define those key/value pairs briefly and easily.
        Parameters:
        kvPairs - Key/value pairs (to go into the map). In the case of a duplicate key, later values in the input list overwrite the earlier ones. The resulting map can contain zero or one null key and any number of null values. Null k/v pairs will be silently ignored.
        Returns:
        a new PersistentHashMap of the given key/value pairs

      • mutableMap

        @SafeVarargs
@NotNull
public static <K,​V> @NotNull MutMap<K,​V> mutableMap​(@Nullable
                                                                @Nullable Map.Entry<K,​V>... kvPairs)
        Returns a new MutMap of the given keys and their paired values. Use the tup(Object, Object) method to define those key/value pairs briefly and easily.
        Parameters:
        kvPairs - Key/value pairs (to go into the map). In the case of a duplicate key, later values in the input list overwrite the earlier ones. The resulting map can contain zero or one null key and any number of null values. Null k/v pairs will be silently ignored.
        Returns:
        a new MutMap of the given key/value pairs

      • mutableRrb

        @SafeVarargs
@NotNull
public static <T> @NotNull RrbTree.MutRrbt<T> mutableRrb​(T... items)
        Returns a mutable RRB Tree RrbTree of the given items. The RRB Tree is a list-type data structure that supports random inserts, split, join, and remove. (the PersistentVector does not). The mutable RRB Tree append() method is only about half as fast as the PersistentVector method of the same name. The RRB tree get() method may be about 5x slower. Otherwise, performance is about the same.

      • mutableSet

        @SafeVarargs
@NotNull
public static <T> @NotNull MutSet<T> mutableSet​(T... items)
        Returns a new MutSet of the values. If the input contains duplicate elements, later values overwrite earlier ones.

      • mutableVec

        @SafeVarargs
@NotNull
public static <T> @NotNull MutList<T> mutableVec​(T... items)
        Returns a MutVector of the given items. If you require inserts or join operations, use mutableRrb(T...) instead.

      • rrb

        @SafeVarargs
@NotNull
public static <T> @NotNull RrbTree.ImRrbt<T> rrb​(T... items)
        Returns a new immutable RRB Tree RrbTree.ImRrbt of the given items. An RRB Tree is an immutable vector (list) that supports random inserts, split, join, and remove (the PersistentVector does not). The RRB tree get() method may be about 5x slower. Otherwise, performance is about the same.

      • set

        @SafeVarargs
@NotNull
public static <T> @NotNull ImSet<T> set​(T... items)
        Returns a new PersistentHashSet of the values. If the input contains duplicate elements, later values overwrite earlier ones.

      • sortedMap

        @NotNull
public static <K,​V> @NotNull ImSortedMap<K,​V> sortedMap​(Comparator<? super K> comp,
                                                                    Iterable<Map.Entry<K,​V>> kvPairs)
        Returns a new PersistentTreeMap of the specified comparator and the given key/value pairs. Use the tup() method to define those key/value pairs briefly and easily. The keys are sorted according to the comparator you provide.
        Parameters:
        comp - A comparator (on the keys) that defines the sort order inside the new map. This becomes a permanent part of the map and all sub-maps or appended maps derived from it. If you want to use a null key, make sure the comparator treats nulls correctly in all circumstances!
        kvPairs - Key/value pairs (to go into the map). In the case of a duplicate key, later values in the input list overwrite the earlier ones. The resulting map can contain zero or one null key (if your comparator knows how to sort nulls) and any number of null values. Null k/v pairs will be silently ignored.
        Returns:
        a new PersistentTreeMap of the specified comparator and the given key/value pairs

      • sortedMap

        @NotNull
public static <K extends Comparable<K>,​V> @NotNull ImSortedMap<K,​V> sortedMap​(Iterable<Map.Entry<K,​V>> kvPairs)
        Returns a new PersistentTreeMap of the given comparable keys and their paired values, sorted in the default ordering of the keys. Use the tup() method to define those key/value pairs briefly and easily.
        Parameters:
        kvPairs - Key/value pairs (to go into the map). In the case of a duplicate key, later values overwrite earlier ones.
        Returns:
        a new PersistentTreeMap of the specified comparator and the given key/value pairs which uses the default comparator defined on the element type.

      • sortedSet

        @NotNull
public static <T> @NotNull ImSortedSet<T> sortedSet​(Comparator<? super T> comp,
                                                    Iterable<T> elements)
        Returns a new PersistentTreeSet of the given comparator and items.
        Parameters:
        comp - A comparator that defines the sort order of elements in the new set. This becomes part of the set (it's not for pre-sorting).
        elements - items to go into the set. In the case of duplicates, later elements overwrite earlier ones.
        Returns:
        a new PersistentTreeSet of the specified comparator and the given elements

      • sortedSet

        @NotNull
public static <T extends Comparable<T>> @NotNull ImSortedSet<T> sortedSet​(Iterable<T> items)
        Returns a new PersistentTreeSet of the given comparable items.

      • tup

        @NotNull
public static <T,​U> @NotNull Tuple2<T,​U> tup​(T t,
                                                         U u)
        Returns a new Tuple2 of the given items.

      • tup

        @NotNull
public static <T,​U,​V> @NotNull Tuple3<T,​U,​V> tup​(T t,
                                                                         U u,
                                                                         V v)
        Returns a new Tuple3 of the given items.

      • vec

        @SafeVarargs
@NotNull
public static <T> @NotNull ImList<T> vec​(T... items)
        Returns a new PersistentVector of the given items. If you require inserts or join operations, use rrb(T...) instead.

      • xform

        @NotNull
public static <T> @NotNull UnmodIterable<T> xform​(@Nullable
                                                  @Nullable Iterable<T> iterable)
        If you need to wrap a regular Java collection or other iterable outside this project to perform a transformation on it, this method is the most convenient, efficient way to do so.

      • xformArray

        @SafeVarargs
@NotNull
public static <T> @NotNull UnmodIterable<T> xformArray​(T... items)
        If you need to wrap a regular Java array outside this project to perform a transformation on it, this method is the most convenient, efficient way to do so.

      • xformChars

        @NotNull
public static @NotNull UnmodIterable<Character> xformChars​(CharSequence seq)
        Wrap a String (or CharSequence) to perform a Character-by-Character transformation on it.