JarCastingSome common iterables for Java
Overview
This is a collection of companion iterables for some commonly useful Iterator implementations for the following use cases:
- Filtering and Converting
- Combining multiple
Iterators - Inserting affix values
- Looking ahead
- Handling of
nullvalues - Handling of
remove()operation - Iterating over single values
- Iterating over multiple values
- Iterating over primitive arrays
- Iterating over non-primitive arrays
- Iterating over other objects
- Iterating infinitely
- Keeping track of iteration index
- Counting up and down
This library is hosted in the Maven Central Repository. You can use it with the following coordinates:
<dependency>
<groupId>net.markenwerk</groupId>
<artifactId>commons-iterables</artifactId>
<version>3.2.1</version>
</dependency>
Consult the usage description and Javadoc for further information.
Usage
Filtering and Converting
This library provides the generic FilteredIterable that takes an existing Iterable and a Predicate and generates Iterators that filter out all values yielded by an Iterator generated by the given Iterable that don't satisfy the given Predicate.
Iterable<Foo> iterable = ...
// generated iterable yield every foo from from iterator that matches the condition
Iterable<Foo> filteringIterable = new filteringIterable<>(iterable, new Predicate<Foo>(){
@Override
public boolean test(Object object) throws PredicateException {
return ...; // some condition
}
});
This library provides the generic ConvertingIterable that takes an existing Iterable and a Converter and generates Iterator that convert all values yielded by an Iterators generated by the given Iterable and yield the converted values.
Iterable<Foo> iterable = ...
// generated iterators yield a bar for every foo from a iterator generated by iterable
Iterable<Bar> convertingIterable = new ConvertingIterable<>(iterable, new Converter<Foo, Bar>(){
@Override
public Bar convert(Foo foo) throws ConverterException {
return ...; // some conversion
}
});
Combining multiple Iterators
This library provides the generic CombinedIterable that takes multiple existing Iterables and combines them into a single Iterable that generates Iterators that yield all values from Iterators generated by the given Iterables.
It can be constructed from an array or an arbitrary amount of known Iterables.
Iterable<Foo> iterable1 = ...
Iterable<Foo> iterable2 = ...
// generated iterators yield every foo from iterators generated by iterable1 and iterable2
Iterable<Foo> combinedIterable = new CombinedIterable<>(iterable1, iterable2);
It can be constructed from an Iterable of Iterables (i.e. a List).
List<Iterable<Foo>>[] iterables = ...
// generated iterable yield every foo from every iterator from iterators
Iterable<Foo> combinedIterable = new CombinedIterable<>(iterables);
Inserting affix values
This library provides the generic PrefixedIterable that takes an existing Iterable and prefix values and generates Iterators that yield the given prefix values before every value yielded by an Iterator generated by the given Iterable.
Foo prefix = ...
Iterable<Foo> iterable = ...
// generated iterable yields every foo from iterator, interspersed with the infix
Iterable<Foo> prefixedIterable = new PrefixedIterable<>(iterable, prefix);
This library provides the generic InfixedIterable that takes an existing Iterable and infix values and generates Iterators that yield the given infix values between every value yielded by an Iterator generated by the given Iterable.
Foo infix = ...
Iterable<Foo> iterable = ...
// generated iterable yields every foo from iterator, interspersed with the infix
Iterable<Foo> infixedIterable = new InfixedIterable<>(iterable, infix);
This library provides the generic SuffixedIterable that takes an existing Iterable and suffix values and generates Iterators that yield the given suffix values after every value yielded by an Iterator generated by the given Iterable.
Foo suffix = ...
Iterable<Foo> iterable = ...
// generated iterable yields every foo from iterator, interspersed with the infix
Iterable<Foo> suffixedIterable = new SuffixedIterable<>(iterable, suffix);
Looking ahead
This library provides the generic LookAheadIterable that takes an existing Iterable and generates Iterators that yield every value yielded by an Iterator generated by the given Iterable wrapped in a LookAhead that also contains the next value. This allows to peak into the future, while iterating through the given Iterable.
Iterable<Foo> iterable = ...
// generated iterator yields a look ahead for every foo from iterator
Iterable<LookAhead<Foo>> lookAheadIterable = new LookAheadIterable<>(iterator);
A LookAheadIterable can be used to easily perform actions between every element yielded by the original Iterable.
for (LookAhead<Foo> lookAhead : lookAheadIterable) {
// returns the current foo
Foo currentFoo = lookAhead.get()
doForEveryFoo(currentFoo);
// returns whether the look ahead has a next value
if (lookAhead.hasNext()) {
// returns the next foo
Foo nextFoo = lookAhead.getNext();
doBetweenFoos(currentFoo, nextFoo);
}
}
Handling of null values
For situations where it is necessary to provide an Iterable, but no meaningful Iterable is available, it might be useful to create an EmptyIterable. An EmptyIterable generates Iterators that don't yield any values, but fulfill the Iterator contract.
// generated iterable yield nothing
Iterable<Foo> emptyIterable = new EmptyIterable<>();
For situations where some Iterable is obtained and passed along, it might be useful to wrap the obtained Iterable in a NullSaveIterable. A NullSaveIterable always generates an Iterator, even if it is constructed from a null Iterable.
Iterable<Foo> iterable = ...
// generated iterators yield every foo from iterator generated by iterable
// of nothing, if iterable is null
Iterable<Foo> nullSaveIterable = new NullSaveIterable<>(iterable);
For situations where some Iterable is obtained, it might be useful to wrap the obtained Iterable in a NullFreeIterable. A NullFreeIterable generates Iterators that tilter out all null values yielded by the obtained Iterable.
Iterable<Foo> iterable = ...
// generated iterators yield every non-null foo from iterator generated by iterable
Iterable<Foo> nullFreeIterable = new NullFreeIterable<>(iterable);
Handling of remove() operation
This library provides the ProtectedIterable interface. A ProtectedIterable is an Iterable that must generate ProtectedIterators, when iterator() is called.
This library provides the ProtectingIterable that takes an existing Iterable and generates Iterators that yield every value yielded by an Iterator generated by the given Iterable, but throw a UnsupportedoperationException, if remove() is called.
Iterable<Foo> iterable = ...
// generated iterators yield every foo from iterator generated by iterable, but don't allow removing
ProtectingIterable<Foo> protectingIterable = new ProtectingIterable<>(iterator);
This library provides the RemoveHandlerIterable that takes an existing Iterable and a Handler and generates Iterables that yields all values yielded by an Iterator generated by the given Iterable, but call the given handler with the last yielded value, instead of calling remove() on the generated Iterator.
Iterable<Foo> iterable = ...
// generated iterators yield every foo from iterator generated by iterable, but intercepts removing
Iterable<Foo> removeHandlerIterable = new RemoveHandlerIterable<>(iterable, new Handler<Foo>(){
@Override
public void handle(Foo foo) {
System.out.println(foo + " has been removed"); // some handling
}
});
Iterating over single values
This library provides the ObjectIterable and OptionalIterable that take an existing object and generate Iterators that yield the given object. An ObjectIterable generates Iterators that always yields the given object, whereas an OptionalIterable generates Iterators that only yields the given object, if it isn't null.
Foo foo = ...
// generated iterable yield foo, even if foo is null
Iterable<Foo> objectIterable = new ObjectIterable<>(foo);
// generated iterable yield foo or nothing, if foo is null
Iterable<Foo> optionalIterable = new OptionalIterable<>(foo);
Iterating over multiple values
This library provides the generic PairIterable that takes a Pair and generates Iterators that yields both values of the given Pair.
Pair<Foo> pair = ...
// generated iterators yield both foos from pair
Iterable<Foo> pairIterable = new PairIterable(pair);
This library provides the generic TupleIterable that takes a Tuple with elements of a similar type and generates Iterators that yields both values of the given Tuple.
Tuple<Foo, Foo> tuple = ...
// generated iterators yield both foos from tuple
Iterable<Foo> tupleIterable = new TupleIterable(tuple);
This library provides the generic TripleIterable that takes a Triple with elements of a similar type and generates Iterators that yields all values of the given Triple.
Triple<Foo, Foo> triple = ...
// generated iterators yield all foos from triple
Iterable<Foo> tripleIterable = new TripleIterable(triple);
Iterating over primitive Arrays
This library provides the following Iterables that take existing primitive arrays and generate Iterators that yield all elements of the given array:
BooleanArrayIterableByteArrayIterableCharacterArrayIterableDoubleArrayIterableFloatArrayIterableIntegerArrayIterableLongArrayIterableShortArrayIterable
boolean[] booleans = ...
// generated iterables yield every boolean from booleans
Iterable<Boolean> arrayIterable = new BooleanArrayIterable(booleans);
Iterating over non-primitive Arrays
This library provides the generic ArrayIterable that takes an existing array and generates Iterators that yield all elements of the given array:
Foo[] foos = ...
// generated iterables yield every foo from foos
Iterable<Foo> arrayIterable = new ArrayIterable<>(foos);
Iterating over other objects
This library provides the generic EnumerationIterable that takes a Provider for Enumerations and generates Iterators that yields every value yielded by an Enumeration generated by the given Provider.
Provider<Enumeration<Foo>> provider = ...
// generated iterators yield every foo from an enumeration generated by provider
Iterable<Foo> enumerationIterable = new EnumerationIterable<>(provider);
This library provides the NodeListIterable that takes a NodeList and generates Iterators that yields every Node of the given NodeList.
NodeList nodeList = ...
// generated iterators yield every node from nodeList
Iterable<Node> nodeListIterable = new NodeListIterable(nodeList);
This library provides the StringTokenizerIterable that takes a Provider for StringTokenizers and generates Iterators that yields every string yielded by a StringTokenizer generated by the given Provider.
Provider<StringTokenizer> provider = ...
// generated iterators yield every string from a tokenizer generated by provider
Iterable<String> tokenizerIterable = new StringTokenizerIterable(provider);
Iterating infinitely
This library provides the generic InfiniteIterable that takes a Provider for and generates Iterators that infinitely yields values yielded by the given Provider.
Provider<Foo> provider = ...
// generated iterators yield provided foos forever
Iterable<Foo> infiniteIterable = new InfiniteIterable<>(provider);
Keeping track of iteration index
This library provides the generic IndexedIterable that takes an existing Iterable and generates Iterators that yield every value yielded by an Iterator generated by the given Iterable wrapped in an Entry whose key is the iteration index of the yielded element.
Iterable<Foo> iterable = ...
// generated iterators yield an entry for every foo from an iterator generated by iterable
Iterable<Entry<Integer, Foo>> indexedIterable = new IndexedIterable<>(iterable);
for(Entry<Integer, Foo> entry : indexedIterable) {
System.out.println(entry.getValue() + " at index " entry.getKey());
}
Counting up and down
This library provides the CountDownIterable and CountUpIterable that take two integer values as bounds generate and generate Iterators that yield every integer value between the given bounds, going downwards or upwards respectively.
// generated iterables yield 10, 9, ..., 1, 0
Iterable<Integer> countUpIterable = new CountDownIterable(10, 0);
// generated iterables yield 0, 1, ..., 9, 10
Iterable<Integer> countDownIterable = new CountUpIterable(0, 10);
