JBIterable (Unofficial IntelliJ Community Edition API docs)

java.lang.Object
- com.intellij.util.containers.JBIterable<E>

All Implemented Interfaces:

java.lang.Iterable<E>
```
public abstract class JBIterable<E>
extends java.lang.Object
implements java.lang.Iterable<E>
```
An in-house and immutable version of com.google.common.collect.FluentIterable with some insights from Clojure. Added bonus is that the JBIterator instances are preserved during most transformations, a feature employed by JBTreeTraverser.
The original JavaDoc ('FluentIterable' replaced by 'JBIterable'):
JBIterable provides a rich interface for manipulating Iterable instances in a chained fashion. A JBIterable can be created from an Iterable, or from a set of elements. The following types of methods are provided on JBIterable:
- chained methods which return a new JBIterable based in some way on the contents of the current one (for example map(com.intellij.util.Function<? super E, ? extends T>))
- conversion methods which copy the JBIterable's contents into a new collection or array (for example toList())
- element extraction methods which facilitate the retrieval of certain elements (for example last())
Here is an example that merges the lists returned by two separate database calls, transforms it by invoking toString() on each element, and returns the first 10 elements as a List:
```
   
   JBIterable
       .from(database.getClientList())
       .filter(activeInLastMonth())
       .map(Functions.toStringFunction())
       .toList();
```
Anything which can be done using JBIterable could be done in a different fashion (often with Iterables), however the use of JBIterable makes many sets of operations significantly more concise.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`JBIterable.SCond<T>` Stateful `Conditions`: a separate cloned instance is used for each iterator.
`static class`	`JBIterable.SFun<S,T>` Stateful `Function`: a separate cloned instance is used for each iterator.
`static class`	`JBIterable.Split`
`static class`	`JBIterable.Stateful<Self extends JBIterable.Stateful<?>>`

Constructor Summary

Constructors
Modifier Constructor and Description

protected JBIterable()
Constructor for use by subclasses.

Constructors
Modifier	Constructor and Description
`protected`	`JBIterable()` Constructor for use by subclasses.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`<C extends java.util.Collection<? super E>> C`	`addAllTo(C collection)` Collects all items to the specified collection and returns it.
`JBIterable<E>`	`append(E element)` Returns a `JBIterable` which iterators traverse first the elements of this iterable, followed by `element` if it is not null.
`JBIterable<E>`	`append(E [] elements)` Returns a `JBIterable` which iterators traverse first the elements of this iterable, followed by the `elements`.
`JBIterable<E>`	`append(java.lang.Iterable<? extends E> other)` Returns a `JBIterable` which iterators traverse first the elements of this iterable, followed by those of `other`.
`<T> JBIterable<E>`	`append(java.lang.Iterable<? extends T> other, Function<? super T,? extends java.lang.Iterable<? extends E>> fun)`
`JBIterable<E>`	`collect()` Collects all items into an `ArrayList` and returns it wrapped in a new `JBIterable`.
`JBIterable<E>`	`collect(java.util.Collection<E> collection)` Collects all items into the specified collection and returns it wrapped in a new `JBIterable`.
`void`	`consumeEach(Consumer<? super E> consumer)`
`boolean`	`contains(java.lang.Object element)` Returns `true` if this iterable contains any object for which `equals(element)` is true.
`static <E> JBIterable<E>`	`create(java.util.function.Supplier<? extends java.util.Iterator<E>> producer)` Lambda-friendly construction method.
`static <E> JBIterable<E>`	`empty()`
`<T> JBIterable<T>`	`filter(java.lang.Class<T> type)` Returns the elements from this iterable that are instances of class `type`.
`JBIterable<E>`	`filter(Condition<? super E> condition)` Returns the elements from this iterable that satisfy a condition.
`<T> JBIterable<T>`	`filterMap(Function<? super E,? extends T> function)` Synonym for `map(..).filter(notNull())`.
`E`	`find(Condition<? super E> condition)` Returns the first matching element.
`E`	`first()` Returns the first element in this iterable or null.
`<T> JBIterable<T>`	`flatMap(Function<? super E,? extends java.lang.Iterable<? extends T>> function)` "Maps" and "flattens" this iterable.
`<T> JBIterable<T>`	`flatten(Function<? super E,? extends java.lang.Iterable<? extends T>> function)` Returns a `JBIterable` that applies `function` to each element of this iterable and concatenates the produced iterables in one.
`static <E> JBIterable<E>`	`from(java.lang.Iterable<? extends E> iterable)` Returns a `JBIterable` that wraps `iterable`, or `iterable` itself if it is already a `JBIterable`.
`static <E> JBIterable<E>`	`generate(E first1, E first2, PairFunction<? super E,? super E,? extends E> generator)`
`static <E> JBIterable<E>`	`generate(E first, Function<? super E,? extends E> generator)` Returns a `JBIterable` that is generated by `generator` function applied to a previous element, the first element is produced by the supplied `first` value.
`E`	`get(int index)` Returns element at index if it is present; otherwise `null`
`int`	`indexOf(Condition<? super E> condition)` Returns the index of the matching element.
`<T> JBIterable<T>`	`intercept(Function<? super java.util.Iterator<? extends E>,? extends java.util.Iterator<? extends T>> function)` The most generic iterator transformation.
`boolean`	`isEmpty()` Determines whether this iterable is empty.
`boolean`	`isNotEmpty()` Determines whether this iterable is not empty.
`JBIterable<E>`	`join(E separator)` Returns the iterable which elements are interleaved with the separator.
`E`	`last()` Returns the last element in this iterable or null.
`<T> JBIterable<T>`	`map(Function<? super E,? extends T> function)` Returns a `JBIterable` that applies `function` to each element of this iterable.
`static <E> JBIterable<E>`	`of(E... elements)` Returns a `JBIterable` containing `elements` in the specified order.
`static <E> JBIterable<E>`	`of(E element)` Returns a `JBIterable` containing the one `element` if is not null.
`static <E> JBIterable<E>`	`once(java.util.Iterator<? extends E> iterator)`
`boolean`	`processEach(Processor<? super E> processor)`
`E`	`reduce(PairFunction<? super E,? super E,? extends E> function)` Perform calculation over this iterable.
`<T> T`	`reduce(T first, PairFunction<? super T,? super E,? extends T> function)` Perform calculation over this iterable.
`JBIterable<E>`	`repeat(int count)`
`E`	`single()` Returns the first element if it is the only one, otherwise null.
`int`	`size()` Returns the number of elements in this iterable.
`JBIterable<E>`	`skip(int count)`
`JBIterable<E>`	`skipWhile(Condition<? super E> condition)`
`JBIterable<E>`	`sort(java.util.Comparator<? super E> comparator)` Collects all items into an `ArrayList`, sorts it and returns it wrapped in a new `JBIterable`.
`JBIterable<E>`	`sorted(java.util.Comparator<? super E> comparator)` Deprecated. use `sort(Comparator)` instead
`JBIterable<JBIterable<E>>`	`split(int size)` Splits this `JBIterable` into iterable of iterables of the specified size.
`JBIterable<java.util.List<E>>`	`split(int size, boolean strict)` Splits this `JBIterable` into iterable of lists of the specified size.
`JBIterable<JBIterable<E>>`	`split(JBIterable.Split mode, Condition<? super E> separator)` Splits this `JBIterable` into iterable of iterables with separators matched by the specified condition.
`JBIterable<E>`	`take(int count)`
`JBIterable<E>`	`takeWhile(Condition<? super E> condition)`
`E []`	`toArray(E [] array)` Synonym for `toList().toArray(array)`.
`java.util.List<E>`	`toList()` Collects all items into an immutable `List` and returns it.
`<K,V> java.util.Map<K,V>`	`toMap(Convertor<? super E,? extends K> toKey, Convertor<? super E,? extends V> toValue)` Returns a `Map` for which the keys and values are defined by the specified converters.
`<V> java.util.Map<E,V>`	`toMap(Convertor<? super E,? extends V> toValue)` A synonym for `toMap(Convertor.SELF, toValue)`
`<K> java.util.Map<K,E>`	`toReverseMap(Convertor<? super E,? extends K> toKey)` A synonym for `toMap(toKey, Convertor.SELF)`
`java.util.Set<E>`	`toSet()` Collects all items into an immutable `Set` and returns it.
`java.lang.String`	`toString()` Returns a string representation of this iterable for debugging purposes.
`<T> JBIterable<T>`	`transform(Function<? super E,? extends T> function)` A synonym for `map(Function)`.
`<T extends java.util.Iterator<E>> T`	`typedIterator()` Returns iterator, useful for graph traversal.
`JBIterable<E>`	`unique()` Filters out duplicate items.
`JBIterable<E>`	`unique(Function<? super E,?> identity)` Filters out duplicate items, where an element identity is provided by the specified function.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator

Constructor Detail
- JBIterable
```
protected JBIterable()
```
  Constructor for use by subclasses.

Method Detail

create

public static <E> JBIterable<E> create(java.util.function.Supplier<? extends java.util.Iterator<E>> producer)

Lambda-friendly construction method.

from
```
public static <E> JBIterable<E> from(java.lang.Iterable<? extends E> iterable)
```
Returns a JBIterable that wraps iterable, or iterable itself if it is already a JBIterable.

generate
```
public static <E> JBIterable<E> generate(E first,
                                         Function<? super E,? extends E> generator)
```
Returns a JBIterable that is generated by generator function applied to a previous element, the first element is produced by the supplied first value. Iteration stops when null is encountered.

generate

public static <E> JBIterable<E> generate(E first1,
                                         E first2,
                                         PairFunction<? super E,? super E,? extends E> generator)

of
```
public static <E> JBIterable<E> of(E element)
```
Returns a JBIterable containing the one element if is not null.

of

@SafeVarargs
public static <E> JBIterable<E> of(E... elements)

Returns a JBIterable containing elements in the specified order.

empty

public static <E> JBIterable<E> empty()

once

public static <E> JBIterable<E> once(java.util.Iterator<? extends E> iterator)

typedIterator
```
public <T extends java.util.Iterator<E>> T typedIterator()
```
Returns iterator, useful for graph traversal.

See Also:

TreeTraversal.TracingIt

processEach

public final boolean processEach(Processor<? super E> processor)

consumeEach

public final void consumeEach(Consumer<? super E> consumer)

toString
```
public java.lang.String toString()
```
Returns a string representation of this iterable for debugging purposes.

Overrides:

toString in class java.lang.Object

size
```
public final int size()
```
Returns the number of elements in this iterable.

contains
```
public final boolean contains(java.lang.Object element)
```
Returns true if this iterable contains any object for which equals(element) is true.

get
```
public final E get(int index)
```
Returns element at index if it is present; otherwise null

repeat

public final JBIterable<E> repeat(int count)

append
```
public final JBIterable<E> append(java.lang.Iterable<? extends E> other)
```
Returns a JBIterable which iterators traverse first the elements of this iterable, followed by those of other. The iterators are not polled until necessary.

append

public final <T> JBIterable<E> append(java.lang.Iterable<? extends T> other,
                                      Function<? super T,? extends java.lang.Iterable<? extends E>> fun)

append
```
public final JBIterable<E> append(E [] elements)
```
Returns a JBIterable which iterators traverse first the elements of this iterable, followed by the elements.

append
```
public final JBIterable<E> append(E element)
```
Returns a JBIterable which iterators traverse first the elements of this iterable, followed by element if it is not null.

filter

public final JBIterable<E> filter(Condition<? super E> condition)

Returns the elements from this iterable that satisfy a condition.

filter
```
public final <T> JBIterable<T> filter(java.lang.Class<T> type)
```
Returns the elements from this iterable that are instances of class type.

Parameters:

type - the type of elements desired

take

public final JBIterable<E> take(int count)

takeWhile

public final JBIterable<E> takeWhile(Condition<? super E> condition)

skip

public final JBIterable<E> skip(int count)

skipWhile

public final JBIterable<E> skipWhile(Condition<? super E> condition)

map

public final <T> JBIterable<T> map(Function<? super E,? extends T> function)

Returns a JBIterable that applies function to each element of this iterable.

transform
```
public final <T> JBIterable<T> transform(Function<? super E,? extends T> function)
```
A synonym for map(Function). Note: map is shorter and shall be preferred.

See Also:

map(Function)

flatten
```
public <T> JBIterable<T> flatten(Function<? super E,? extends java.lang.Iterable<? extends T>> function)
```
Returns a JBIterable that applies function to each element of this iterable and concatenates the produced iterables in one. Nulls are supported and silently skipped.

unique
```
public final JBIterable<E> unique()
```
Filters out duplicate items.

unique
```
public final JBIterable<E> unique(Function<? super E,?> identity)
```
Filters out duplicate items, where an element identity is provided by the specified function.

intercept

public final <T> JBIterable<T> intercept(Function<? super java.util.Iterator<? extends E>,? extends java.util.Iterator<? extends T>> function)

The most generic iterator transformation.

first
```
public final E first()
```
Returns the first element in this iterable or null.

single
```
public final E single()
```
Returns the first element if it is the only one, otherwise null.

last
```
public final E last()
```
Returns the last element in this iterable or null.

reduce

public final <T> T reduce(T first,
                          PairFunction<? super T,? super E,? extends T> function)

Perform calculation over this iterable.

reduce

public final E reduce(PairFunction<? super E,? super E,? extends E> function)

Perform calculation over this iterable.

find

public final E find(Condition<? super E> condition)

Returns the first matching element.

indexOf

public final int indexOf(Condition<? super E> condition)

Returns the index of the matching element.

filterMap

public final <T> JBIterable<T> filterMap(Function<? super E,? extends T> function)

Synonym for map(..).filter(notNull()).

See Also:: map(Function), filter(Condition)

flatMap

public final <T> JBIterable<T> flatMap(Function<? super E,? extends java.lang.Iterable<? extends T>> function)

"Maps" and "flattens" this iterable.

See Also:: map(Function), flatten(Function)

join
```
public final JBIterable<E> join(E separator)
```
Returns the iterable which elements are interleaved with the separator.

split
```
public final JBIterable<java.util.List<E>> split(int size,
                                                 boolean strict)
```
Splits this JBIterable into iterable of lists of the specified size. If 'strict' flag is true only groups of size 'n' are returned.

split
```
public final JBIterable<JBIterable<E>> split(int size)
```
Splits this JBIterable into iterable of iterables of the specified size. All iterations are performed in-place without data copying.

split

public final JBIterable<JBIterable<E>> split(JBIterable.Split mode,
                                             Condition<? super E> separator)

Splits this JBIterable into iterable of iterables with separators matched by the specified condition. All iterations are performed in-place without data copying.

isEmpty
```
public final boolean isEmpty()
```
Determines whether this iterable is empty.

isNotEmpty
```
public final boolean isNotEmpty()
```
Determines whether this iterable is not empty.

collect
```
public final JBIterable<E> collect(java.util.Collection<E> collection)
```
Collects all items into the specified collection and returns it wrapped in a new JBIterable. This is equivalent to calling JBIterable.from(addAllTo(c)).

collect
```
public final JBIterable<E> collect()
```
Collects all items into an ArrayList and returns it wrapped in a new JBIterable.

See Also:

collect(Collection)

sort
```
public final JBIterable<E> sort(java.util.Comparator<? super E> comparator)
```
Collects all items into an ArrayList, sorts it and returns it wrapped in a new JBIterable.

See Also:

collect(Collection)

sorted

@Deprecated
public final JBIterable<E> sorted(java.util.Comparator<? super E> comparator)

Deprecated. use sort(Comparator) instead

toList
```
public final java.util.List<E> toList()
```
Collects all items into an immutable List and returns it.

toSet
```
public final java.util.Set<E> toSet()
```
Collects all items into an immutable Set and returns it.

toArray
```
public final E [] toArray(E [] array)
```
Synonym for toList().toArray(array).

See Also:

List.toArray(Object[])

toMap

public final <K,V> java.util.Map<K,V> toMap(Convertor<? super E,? extends K> toKey,
                                            Convertor<? super E,? extends V> toValue)

Returns a Map for which the keys and values are defined by the specified converters. {@link LinkedHashMap} is used, so the order is preserved.

toMap

public final <V> java.util.Map<E,V> toMap(Convertor<? super E,? extends V> toValue)

A synonym for toMap(Convertor.SELF, toValue)

See Also:: toMap(Convertor, Convertor)

toReverseMap

public final <K> java.util.Map<K,E> toReverseMap(Convertor<? super E,? extends K> toKey)

A synonym for toMap(toKey, Convertor.SELF)

See Also:: toMap(Convertor, Convertor)

addAllTo

public final <C extends java.util.Collection<? super E>> C addAllTo(C collection)

Collects all items to the specified collection and returns it.

Class JBIterable<E>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

JBIterable

Method Detail

create

from

generate

generate

of

of

empty

once

typedIterator

processEach

consumeEach

toString

size

contains

get

repeat

append

append

append

append

filter

filter

take

takeWhile

skip

skipWhile

map

transform

flatten

unique

unique

intercept

first

single

last

reduce

reduce

find

indexOf

filterMap

flatMap

join

split

split

split

isEmpty

isNotEmpty

collect

collect

sort

sorted

toList

toSet

toArray

toMap

toMap

toReverseMap

addAllTo