Package org.organicdesign.fp.collections
Interface UnmodIterable<T>
-
- All Superinterfaces:
Iterable<T>
,Transformable<T>
- 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>
,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 UnmodIterable<T> extends Iterable<T>, Transformable<T>
An unmodifiable Iterable, without any guarantee about order.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
UnmodIterable.UnIterable
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default @NotNull UnmodIterable<T>
concat(@Nullable Iterable<? extends T> list)
Add items to the end of this Transformable (precat() adds to the beginning)default @NotNull UnmodIterable<T>
drop(long n)
Ignore the first n items and return only those that come after.default @NotNull UnmodIterable<T>
dropWhile(@NotNull Fn1<? super T,Boolean> predicate)
Ignore leading items until the given predicate returns false.static <T> @NotNull UnmodIterable<T>
emptyUnmodIterable()
We only ever need one empty iterable in memory.default @NotNull UnmodIterable<T>
filter(@NotNull Fn1<? super T,Boolean> f)
Return only the items for which the given predicate returns true.default <B> @NotNull UnmodIterable<B>
flatMap(@NotNull Fn1<? super T,Iterable<B>> f)
Transform each item into zero or more new items using the given function.default <B> B
fold(B ident, @NotNull Fn2<? super B,? super T,B> reducer)
Apply the function to each item, accumulating the result in u.default <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().static int
hash(@NotNull Iterable<?> is)
This is correct, but O(n).default @NotNull Option<T>
head()
The first item in this iterable.@NotNull UnmodIterator<T>
iterator()
A one-time use, mutable, not-thread-safe way to get each value of the underling collection in turn.default <B> @NotNull UnmodIterable<B>
map(@NotNull Fn1<? super T,? extends B> f)
Transform each item into exactly one new item using the given function.default @NotNull UnmodIterable<T>
precat(@Nullable Iterable<? extends T> list)
Add items to the beginning of this Transformable ("precat" is a PREpending version of conCAT).default @NotNull UnmodIterable<T>
take(long numItems)
Return only the first n items.default @NotNull UnmodIterable<T>
takeWhile(@NotNull Fn1<? super T,Boolean> f)
Return items from the beginning until the given predicate returns false.static @NotNull String
toString(@NotNull String name, @NotNull Iterable<?> iterable)
Computes a reasonable to-string.default @NotNull UnmodIterable<T>
whereNonNull()
Return only the items which are non-null-
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Methods inherited from interface org.organicdesign.fp.xform.Transformable
any, toImList, toImMap, toImRrbt, toImSet, toImSortedMap, toImSortedSet, toMutList, toMutMap, toMutRrbt, toMutSet, toMutSortedMap, toMutSortedSet
-
-
-
-
Method Detail
-
emptyUnmodIterable
@NotNull static <T> @NotNull UnmodIterable<T> emptyUnmodIterable()
We only ever need one empty iterable in memory.
-
hash
static int hash(@NotNull @NotNull 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
@NotNull static @NotNull String toString(@NotNull @NotNull String name, @NotNull @NotNull Iterable<?> iterable)
Computes a reasonable to-string.
-
iterator
@NotNull @NotNull 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.
-
concat
@NotNull default @NotNull UnmodIterable<T> concat(@Nullable @Nullable Iterable<? extends T> list)
Add items to the end of this Transformable (precat() adds to the beginning)- Specified by:
concat
in interfaceTransformable<T>
- Parameters:
list
- the items to add- Returns:
- a new Transformable with the items added.
-
precat
@NotNull default @NotNull UnmodIterable<T> precat(@Nullable @Nullable Iterable<? extends T> list)
Add items to the beginning of this Transformable ("precat" is a PREpending version of conCAT).- Specified by:
precat
in interfaceTransformable<T>
- Parameters:
list
- the items to add- Returns:
- a new Transformable with the items added.
-
drop
@NotNull default @NotNull 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 interfaceTransformable<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.
-
dropWhile
@NotNull default @NotNull UnmodIterable<T> dropWhile(@NotNull @NotNull Fn1<? super T,Boolean> predicate)
Ignore leading items until the given predicate returns false.- Specified by:
dropWhile
in interfaceTransformable<T>
- Parameters:
predicate
- the predicate (test function)- Returns:
- a Transformable with the matching leading items ignored.
-
fold
default <B> B fold(B ident, @NotNull @NotNull Fn2<? super 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 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().- Specified by:
fold
in interfaceTransformable<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.
-
foldUntil
@NotNull default <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.- Specified by:
foldUntil
in interfaceTransformable<T>
- 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 theOr.good()
is an eagerly evaluated result andOr.bad()
is whatever terminateWhen returned.
-
filter
@NotNull default @NotNull UnmodIterable<T> filter(@NotNull @NotNull Fn1<? super T,Boolean> f)
Return only the items for which the given predicate returns true.- Specified by:
filter
in interfaceTransformable<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.
-
whereNonNull
@NotNull default @NotNull UnmodIterable<T> whereNonNull()
Return only the items which are non-null- Specified by:
whereNonNull
in interfaceTransformable<T>
- Returns:
- a Transformable of only the non-null items.
-
flatMap
@NotNull default <B> @NotNull UnmodIterable<B> flatMap(@NotNull @NotNull Fn1<? 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. fold is the other, but flatMap is lazy while fold is eager.- Specified by:
flatMap
in interfaceTransformable<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
@NotNull default <B> @NotNull UnmodIterable<B> map(@NotNull @NotNull Fn1<? super T,? extends B> f)
Transform each item into exactly one new item using the given function.- Specified by:
map
in interfaceTransformable<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
@NotNull default @NotNull UnmodIterable<T> take(long numItems)
Return only the first n items.- Specified by:
take
in interfaceTransformable<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
@NotNull default @NotNull UnmodIterable<T> takeWhile(@NotNull @NotNull Fn1<? super T,Boolean> f)
Return items from the beginning until the given predicate returns false.- Specified by:
takeWhile
in interfaceTransformable<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
@NotNull default @NotNull Option<T> head()
The first item in this iterable.- Specified by:
head
in interfaceTransformable<T>
- Returns:
- an eagerly evaluated result which is a single item.
-
-