org.organicdesign.fp.collections

Interface UnmodIterable<T>

All Superinterfaces:

Iterable<T>, Transformable<T>

All Known Subinterfaces:

ImList<E>, ImMap<K,V>, ImMapTrans<K,V>, ImSet<E>, ImSortedMap<K,V>, ImSortedSet<E>, ImUnsortedMap<K,V>, ImUnsortedSet<E>, MutableList<E>, MutableUnsortedMap<K,V>, MutableUnsortedSet<E>, UnmodCollection<E>, UnmodList<E>, UnmodMap<K,V>, UnmodSet<E>, UnmodSortedCollection<E>, UnmodSortedIterable<T>, UnmodSortedMap<K,V>, UnmodSortedSet<E>

All Known Implementing Classes:

FunctionUtils.UnmodifiableCollection, FunctionUtils.UnmodifiableList, FunctionUtils.UnmodifiableMap, FunctionUtils.UnmodifiableSet, FunctionUtils.UnmodifiableSortedMap, FunctionUtils.UnmodifiableSortedSet, PersistentHashMap, PersistentHashMap.MutableHashMap, PersistentHashSet, PersistentHashSet.MutableHashSet, PersistentTreeMap, PersistentTreeSet, PersistentVector, PersistentVector.MutableVector, RangeOfInt, UnmodIterable.AbstractUnmodIterable, UnmodList.AbstractUnmodList, UnmodMap.AbstractUnmodMap, UnmodSet.AbstractUnmodSet, Xform

public interface UnmodIterable<T>
extends Iterable<T>, Transformable<T>

An unmodifiable Iterable, without any guarantee about order.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	UnmodIterable.AbstractUnmodIterable<T> Implements equals and hashCode() methods compatible with all java.util collections (this algorithm is not order-dependent) and toString which takes the name of the sub-class.

Method Summary

Modifier and Type	Method and Description
default UnmodIterable<T>	concat(Iterable<? extends T> list) Add items to the end of this Transformable (precat() adds to the beginning)
default UnmodIterable<T>	drop(long n) Ignore the first n items and return only those that come after.
default UnmodIterable<T>	filter(Function1<? super T,Boolean> f) Return only the items for which the given predicate returns true.
default <B> UnmodIterable<B>	flatMap(Function1<? super T,Iterable<B>> f) Transform each item into zero or more new items using the given function.
default <B> B	foldLeft(B ident, Function2<B,? super T,B> reducer) Apply the function to each item, accumulating the result in u.
default <B> B	foldLeft(B ident, Function2<B,? super T,B> reducer, Function1<? super B,Boolean> terminateWhen) 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 foldLeft().
static int	hash(Iterable is) This is correct, but O(n).
static int	hashCode(Iterable is) Deprecated.
default Option<T>	head() The first item in this sequence.
UnmodIterator<T>	iterator() A one-time use, mutable, not-thread-safe way to get each value of the underling collection in turn.
default <B> UnmodIterable<B>	map(Function1<? super T,? extends B> f) Transform each item into exactly one new item using the given function.
default UnmodIterable<T>	precat(Iterable<? extends T> list) Add items to the beginning of this Transformable ("precat" is a PREpending version of conCAT).
default UnmodIterable<T>	take(long numItems) Return only the first n items.
default UnmodIterable<T>	takeWhile(Function1<? super T,Boolean> f) Return items from the beginning until the given predicate returns false.
static String	toString(String name, Iterable iterable) Computes a reasonable to-string.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface org.organicdesign.fp.xform.Transformable

toImList, toImMap, toImSet, toImSortedMap, toImSortedSet, toMutableList, toMutableMap, toMutableSet, toMutableSortedMap, toMutableSortedSet

Method Detail

hashCode

@Deprecated
static int hashCode(Iterable is)

Deprecated.

Renamed to hash(Iterable) to avoid confusion with instance method Object.hashCode() 2016-09-17

hash

static int hash(Iterable is)

This is correct, but O(n). It also works regardless of the order of the items because a + b = b + a, even when an overflow occurs.

toString

static String toString(String name,
                       Iterable iterable)

Computes a reasonable to-string.

iterator

UnmodIterator<T> iterator()

A one-time use, mutable, not-thread-safe way to get each value of the underling collection in turn. I experimented with various thread-safe alternatives, but the JVM is optimized around iterators so this is the lowest common denominator of collection iteration, even though iterators are inherently mutable.

Specified by:

iterator in interface Iterable<T>

concat

default UnmodIterable<T> concat(Iterable<? extends T> list)

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

Specified by:

concat in interface Transformable<T>

Parameters:

list - the items to add

Returns:

a new Transformable with the items added.

precat

default UnmodIterable<T> precat(Iterable<? extends T> list)

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

Specified by:

precat in interface Transformable<T>

Parameters:

list - the items to add

Returns:

a new Transformable with the items added.

drop

default UnmodIterable<T> drop(long n)

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.

Specified by:

drop in interface Transformable<T>

Parameters:

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

Returns:

a Transformable with the specified number of items ignored.

foldLeft

default <B> B foldLeft(B ident,
                       Function2<B,? super T,B> 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 foldLeft provides. This implementation follows the convention that foldLeft processes items *in order* unless those items are a linked list, and in this case, they are not. FoldLeft 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 foldLeft is eager while flatMap is lazy. FoldLeft can also produce a single (scalar) value. In that form, it is often called reduce().

Specified by:

foldLeft in interface Transformable<T>

Parameters:

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

foldLeft

default <B> B foldLeft(B ident,
                       Function2<B,? super T,B> reducer,
                       Function1<? super B,Boolean> terminateWhen)

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 foldLeft(). If foldLeft replaces a loop, and return is a more general form of break, then this function can do anything a loop can do.

Specified by:

foldLeft in interface Transformable<T>

Parameters:

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

terminateWhen - returns true when the termination condition is reached and will stop processing the input at that time, returning the latest u.

Returns:

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

filter

default UnmodIterable<T> filter(Function1<? super T,Boolean> f)

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

Specified by:

filter in interface Transformable<T>

Parameters:

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

Returns:

a Transformable of only the filtered items.

flatMap

default <B> UnmodIterable<B> flatMap(Function1<? super T,Iterable<B>> 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. foldLeft is the other, but flatMap is lazy while foldLeft is eager.

Specified by:

flatMap in interface Transformable<T>

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.

map

default <B> UnmodIterable<B> map(Function1<? super T,? extends B> f)

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

Specified by:

map in interface Transformable<T>

Parameters:

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

take

default UnmodIterable<T> take(long numItems)

Return only the first n items.

Specified by:

take in interface Transformable<T>

Parameters:

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

Returns:

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

takeWhile

default UnmodIterable<T> takeWhile(Function1<? super T,Boolean> f)

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

Specified by:

takeWhile in interface Transformable<T>

Parameters:

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

head

default Option<T> head()

The first item in this sequence. This was originally called first() but that conflicted with SortedSet.first() which did not return an Option and threw an exception when the set was empty.