Package org.organicdesign.fp.xform

Interface Transformable<T>

Type Parameters:

T - The input type to the current stage of transformation. Some transforms produce a different output type.

All Known Subinterfaces:

BaseList<E>, BaseMap<K,V>, BaseSet<E>, BaseUnsortedMap<K,V>, ImList<E>, ImMap<K,V>, ImSet<E>, ImSortedMap<K,V>, ImSortedSet<E>, MutList<E>, MutMap<K,V>, MutSet<E>, UnmodCollection<E>, UnmodIterable<T>, UnmodList<E>, UnmodMap<K,V>, UnmodSet<E>, UnmodSortedCollection<E>, UnmodSortedIterable<T>, UnmodSortedMap<K,V>, UnmodSortedSet<E>

All Known Implementing Classes:

AbstractUnmodIterable, AbstractUnmodMap, AbstractUnmodSet, PersistentHashMap, PersistentHashMap.MutHashMap, PersistentHashSet, PersistentHashSet.MutHashSet, PersistentTreeMap, PersistentTreeSet, PersistentVector, PersistentVector.MutVector, RangeOfInt, RrbTree, RrbTree.ImRrbt, RrbTree.MutRrbt, UnmodIterable.UnIterable, UnmodList.AbstractUnmodList, Xform

public interface Transformable<T>

Represents transformations to be carried out on a collection. The to___() methods were formerly defined by a separate Realizable interface that extended this one, but that never proved useful and it complicated things slightly, so I just combined Realizable into Transformable.

Method Summary

Modifier and Type	Method	Description
default boolean	any(@NotNull Fn1<? super T,Boolean> predicate)	Return only the items for which the given predicate returns true.
@NotNull Transformable<T>	concat(@Nullable Iterable<? extends T> list)	Add items to the end of this Transformable (precat() adds to the beginning)
@NotNull Transformable<T>	drop(long numItems)	Ignore the first n items and return only those that come after.
@NotNull Transformable<T>	dropWhile(@NotNull Fn1<? super T,Boolean> predicate)	Ignore leading items until the given predicate returns false.
@NotNull Transformable<T>	filter(@NotNull Fn1<? super T,Boolean> predicate)	Return only the items for which the given predicate returns true.
<U> @NotNull Transformable<U>	flatMap(@NotNull Fn1<? super T,Iterable<U>> f)	Transform each item into zero or more new items using the given function.
<U> U	fold(U accum, @NotNull Fn2<? super U,? super T,U> reducer)	Apply the function to each item, accumulating the result in u.
<G,B> @NotNull Or<G,B>	foldUntil(G accum, @Nullable Fn2<? super G,? super T,B> terminator, @NotNull Fn2<? super G,? super T,G> reducer)	Normally you want to terminate by doing a take(), drop(), or takeWhile() before you get to the fold, but if you need to terminate based on the complete result so far, you can provide your own termination condition to this version of fold().
default @NotNull Option<T>	head()	Returns the first item produced by this transform.
<U> @NotNull Transformable<U>	map(@NotNull Fn1<? super T,? extends U> func)	Transform each item into exactly one new item using the given function.
@NotNull Transformable<T>	precat(@Nullable Iterable<? extends T> list)	Add items to the beginning of this Transformable ("precat" is a PREpending version of conCAT).
@NotNull Transformable<T>	take(long numItems)	Return only the first n items.
@NotNull Transformable<T>	takeWhile(@NotNull Fn1<? super T,Boolean> predicate)	Return items from the beginning until the given predicate returns false.
default @NotNull ImList<T>	toImList()	Realize a thread-safe immutable list to access items quickly O(log32 n) by index.
default <K,V> @NotNull ImMap<K,V>	toImMap(@NotNull Fn1<? super T,Map.Entry<K,V>> f1)	Realize an unordered immutable hash map to very quickly O(1) look up values by key, but don't care about ordering.
default @NotNull RrbTree.ImRrbt<T>	toImRrbt()	Realize a thread-safe immutable RRB-Tree to access items quickly O(log32 n) by index.
default @NotNull ImSet<T>	toImSet()	Realize an unordered immutable hash set to remove duplicates or very quickly O(1) tell whether the set contains various items, but don't care about ordering.
default <K,V> @NotNull ImSortedMap<K,V>	toImSortedMap(Comparator<? super K> comp, @NotNull Fn1<? super T,Map.Entry<K,V>> f1)	Realize an immutable, ordered (tree) map to quickly O(log2 n) look up values by key, but still retrieve entries in key order.
default @NotNull ImSortedSet<T>	toImSortedSet(Comparator<? super T> comparator)	Realize an immutable, sorted (tree) set to quickly O(log2 n) test it contains items, but still retrieve entries in order.
default @NotNull MutList<T>	toMutList()	Realize a mutable list.
default <K,V> @NotNull MutMap<K,V>	toMutMap(@NotNull Fn1<? super T,Map.Entry<K,V>> f1)	Realize a mutable hash map.
default @NotNull RrbTree.MutRrbt<T>	toMutRrbt()	Realize a mutable RRB-Tree.
default @NotNull MutSet<T>	toMutSet()	Realize a mutable hash set.
default <K,V> @NotNull SortedMap<K,V>	toMutSortedMap(@Nullable Comparator<? super K> comp, @NotNull Fn1<? super T,Map.Entry<K,V>> f1)	Realize a mutable tree map.
default @NotNull SortedSet<T>	toMutSortedSet(@Nullable Comparator<? super T> comparator)	Returns a mutable tree set.
@NotNull Transformable<T>	whereNonNull()	Return only the items which are non-null

Method Detail

any

default boolean any(@NotNull
                    @NotNull Fn1<? super T,Boolean> predicate)

Return only the items for which the given predicate returns true.

Parameters:

predicate - a function that returns true for items to keep, false for items to drop

Returns:

a Transformable of only the filtered items.

concat

@NotNull
@NotNull Transformable<T> concat(@Nullable
                                 @Nullable Iterable<? extends T> list)

Add items to the end of this Transformable (precat() adds to the beginning)

Parameters:

list - the items to add

Returns:

a new Transformable with the items added.

drop

@NotNull
@NotNull Transformable<T> drop(long numItems)

Ignore the first n items and return only those that come after. The Xform API is designed to allow dropping items with a single pointer addition if the data source is a List, but that feature is not implemented yet. For best results, drop as early in your chain of functions as practical.

Parameters:

numItems - the number of items at the beginning of this Transformable to ignore

Returns:

a Transformable with the specified number of items ignored.

dropWhile

@NotNull
@NotNull Transformable<T> dropWhile(@NotNull
                                    @NotNull Fn1<? super T,Boolean> predicate)

Ignore leading items until the given predicate returns false.

Parameters:

predicate - the predicate (test function)

Returns:

a Transformable with the matching leading items ignored.

filter

@NotNull
@NotNull Transformable<T> filter(@NotNull
                                 @NotNull Fn1<? super T,Boolean> predicate)

Return only the items for which the given predicate returns true.

Parameters:

predicate - a function that returns true for items to keep, false for items to drop

Returns:

a Transformable of only the filtered items.

whereNonNull

@NotNull
@NotNull Transformable<T> whereNonNull()

Return only the items which are non-null

Returns:

a Transformable of only the non-null items.

head

@NotNull
default @NotNull Option<T> head()

Returns the first item produced by this transform. If the source is unordered, there is no guarantee about which item will make it through the transform first. This was going to be called first(), but that conflicts with SortedSet.first() which is used by SortedMap.entrySet(). The contract for that is to return the first item or null, so that if it returns null, you don't know whether that means the set is empty or that the first item is null. I guess your comparator would have to understand nulls, but it could happen.

Returns:

an eagerly evaluated result which is a single item.

flatMap

@NotNull
<U> @NotNull Transformable<U> flatMap(@NotNull
                                      @NotNull Fn1<? super T,Iterable<U>> f)

Transform each item into zero or more new items using the given function. One of the two higher-order functions that can produce more output items than input items. fold is the other, but flatMap is lazy while fold is eager.

Parameters:

f - yields a Transformable of 0 or more results for each input item.

Returns:

a lazily evaluated collection which is expected to be larger than the input collection. For a collection that's the same size, map() is more efficient. If the expected return is smaller, use filter followed by map if possible, or vice versa if not.

fold

<U> U fold(U accum,
           @NotNull
           @NotNull Fn2<? super U,? super T,U> reducer)

Apply the function to each item, accumulating the result in u. Other transformations can be implemented with just this one function, but it is clearer (and allows lazy evaluation) to use the most specific transformations that meet your needs. Still, sometimes you need the flexibility fold provides. This is techincally a fold-left because it processes items in order* unless those items are a linked list. Fold is one of the two higher-order functions that can produce more output items than input items (when u is a collection). FlatMap is the other, but fold is eager while flatMap is lazy. Fold can also produce a single (scalar) value. In that form, it is often called reduce().

Parameters:

accum - the accumulator and starting value. This will be passed to the function on the first iteration to be combined with the first member of the underlying data source. For some operations you'll need to pass an identity, e.g. for a sum, pass 0, for a product, pass 1 as this parameter.

reducer - combines each value in the list with the result so far. The initial result is u.

Returns:

an eagerly evaluated result which could be a single value like a sum, or a collection.

foldUntil

@NotNull
<G,B> @NotNull Or<G,B> foldUntil(G accum,
                                             @Nullable
                                             @Nullable Fn2<? super G,? super T,B> terminator,
                                             @NotNull
                                             @NotNull Fn2<? super G,? super T,G> reducer)

Normally you want to terminate by doing a take(), drop(), or takeWhile() before you get to the fold, but if you need to terminate based on the complete result so far, you can provide your own termination condition to this version of fold(). This function can do anything a loop can do. One use case is to accumulate a map and stop if it finds a duplicate key, before overwriting that element in the map. It could then return the map so far, an error, or whatever you like.

Parameters:

accum - the accumulator and starting value. This will be passed to the function on the first iteration to be combined with the first member of the underlying data source. For some operations you'll need to pass an identity, e.g. for a sum, pass 0, for a product, pass 1 as this parameter.

terminator - return null to continue processing. Return non-null to terminate the foldUntil and return Or.bad of this value. This function is called at the beginning of each "loop", thus it's first called with the original value of accum and the first item to process. Returning non-null immediately will prevent the reducer from ever being called.

reducer - combines each value in the list with the result so far. The initial result is u.

Returns:

an Or where the Or.good() is an eagerly evaluated result and Or.bad() is whatever terminateWhen returned.

map

@NotNull
<U> @NotNull Transformable<U> map(@NotNull
                                  @NotNull Fn1<? super T,? extends U> func)

Transform each item into exactly one new item using the given function.

Parameters:

func - a function that returns a new value for any value in the input

Returns:

a Transformable of the same size as the input (may contain duplicates) containing the return values of the given function in the same order as the input values.

precat

@NotNull
@NotNull Transformable<T> precat(@Nullable
                                 @Nullable Iterable<? extends T> list)

Add items to the beginning of this Transformable ("precat" is a PREpending version of conCAT).

Parameters:

list - the items to add

Returns:

a new Transformable with the items added.

take

@NotNull
@NotNull Transformable<T> take(long numItems)

Return only the first n items.

Parameters:

numItems - the maximum number of items in the returned view.

Returns:

a Transformable containing no more than the specified number of items.

takeWhile

@NotNull
@NotNull Transformable<T> takeWhile(@NotNull
                                    @NotNull Fn1<? super T,Boolean> predicate)

Return items from the beginning until the given predicate returns false.

Parameters:

predicate - the predicate (test function)

Returns:

a lazy transformable containing the longest un-interrupted run of items, from the beginning of the transformable, that satisfy the given predicate. This could be 0 items to the entire transformable.

toImList

@NotNull
default @NotNull ImList<T> toImList()

Realize a thread-safe immutable list to access items quickly O(log32 n) by index.

toImRrbt

@NotNull
default @NotNull RrbTree.ImRrbt<T> toImRrbt()

Realize a thread-safe immutable RRB-Tree to access items quickly O(log32 n) by index.

toImMap

@NotNull
default <K,V> @NotNull ImMap<K,V> toImMap(@NotNull
                                                      @NotNull Fn1<? super T,Map.Entry<K,V>> f1)

Realize an unordered immutable hash map to very quickly O(1) look up values by key, but don't care about ordering. In the case of a duplicate key, later values from this transform will overwrite the earlier ones. The resulting map can contain zero or one null key and any number of null values.

Parameters:

f1 - Maps each item in this collection to a key/value pair. If the collection is composed of Map.Entries (or Tuple2's), you can pass Fn1.identity() here. This function must never return null (filter out nulls in an earlier step of the transform if necessary).

Returns:

An immutable map

toImSet

@NotNull
default @NotNull ImSet<T> toImSet()

Realize an unordered immutable hash set to remove duplicates or very quickly O(1) tell whether the set contains various items, but don't care about ordering. If the input contains duplicate elements, later values overwrite earlier ones.

Returns:

An immutable set (with duplicates removed)

toImSortedMap

@NotNull
default <K,V> @NotNull ImSortedMap<K,V> toImSortedMap(Comparator<? super K> comp,
                                                                  @NotNull
                                                                  @NotNull Fn1<? super T,Map.Entry<K,V>> f1)

Realize an immutable, ordered (tree) map to quickly O(log2 n) look up values by key, but still retrieve entries in key order. 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!

f1 - Maps each item in this collection to a key/value pair. If the collection is composed of Map.Entries, you can pass Fn1.identity() here. In the case of a duplicate key, later values in transform 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. This function must never return null (filter out nulls in an earlier step of the transform if necessary).

Returns:

a new PersistentTreeMap of the specified comparator and the given key/value pairs

toImSortedSet

@NotNull
default @NotNull ImSortedSet<T> toImSortedSet(Comparator<? super T> comparator)

Realize an immutable, sorted (tree) set to quickly O(log2 n) test it contains items, but still retrieve entries in order.

Parameters:

comparator - Determines the ordering. If T implements Comparable, you can pass Fn2.defaultComparator() here.

Returns:

An immutable set (with duplicates removed). Null elements are not allowed.

toMutList

@NotNull
default @NotNull MutList<T> toMutList()

Realize a mutable list. Use toImList unless you need to modify the list in-place.

toMutRrbt

@NotNull
default @NotNull RrbTree.MutRrbt<T> toMutRrbt()

Realize a mutable RRB-Tree. Use toImRrbt unless you need to modify the list in-place.

toMutMap

@NotNull
default <K,V> @NotNull MutMap<K,V> toMutMap(@NotNull
                                                        @NotNull Fn1<? super T,Map.Entry<K,V>> f1)

Realize a mutable hash map. Use toImMap() unless you need to modify the map in-place.

Parameters:

f1 - Maps keys to values. This function must never return null (filter out nulls in an earlier step of the transform if necessary).

Returns:

A map with the keys from the given set, mapped to values using the given function.

toMutSortedMap

@NotNull
default <K,V> @NotNull SortedMap<K,V> toMutSortedMap(@Nullable
                                                                 @Nullable Comparator<? super K> comp,
                                                                 @NotNull
                                                                 @NotNull Fn1<? super T,Map.Entry<K,V>> f1)

Realize a mutable tree map. Use toImSortedMap() unless you need to modify the map in-place.

Parameters:

comp - A comparator (on the keys) that defines the sort order inside the new map. Null keys are probably not allowed.

f1 - Maps keys to values. This should never return null.

Returns:

A map with the keys from the given set, mapped to values using the given function.

toMutSet

@NotNull
default @NotNull MutSet<T> toMutSet()

Realize a mutable hash set. Use toImSet() unless you need to modify the set in-place.

Returns:

A mutable set (with duplicates removed)

toMutSortedSet

@NotNull
default @NotNull SortedSet<T> toMutSortedSet(@Nullable
                                             @Nullable Comparator<? super T> comparator)

Returns a mutable tree set. Use toImSortedSet unless you need to modify the set in-place.

Parameters:

comparator - Determines the ordering. If T implements Comparable, you can pass Fn2.defaultComparator() here.

Returns:

A mutable sorted set