Package net.sf.jga.util

Provides Facade objects for working with the algorithm functors, and a variety of utility iterators for various purposes.

See:
Description

Class Summary

Algorithms	Facade for the Algorithms adapted from STL, defined to work primarily with collections.
ArrayIterator<T>	Iterates over an array of objects.
Arrays	Miscellaneous utilities for working with arrays.
CachingIterator<T>	Iterator that allows the program to retain the last few elements returned.
ChainedComparator<T>	Comparator wrapper that uses a pair of comparators internally.
ComparableComparator<T extends Comparable<? super T>>	Comparator used for objects that extend Comparable.
EmptyIterator<T>	Iterator over an empty set of elements.
EnumerationIterator<T>	Adapts an Enumeration to the Iterator and Iterable interfaces.
FilterIterator<T>	Iterator that only returns elements that meet the given selection criteria.
FindAllIterator<T>	Iterator that applies one of the FindX functors as many times as possible.
FindIterator<T>	Iterator that provides the ability to skip to the first/next element that meets a particular criteria.
GenericComparator<T,R extends Comparable<R>>	Comparator that applies a functor to each argument, then compares the results.
Iterables	Facade for the Iterators in this package, supporting the new forloop syntax.
IteratorComparator<T>	Comparator used to compare iterations lexically.
Iterators	Facade for the Algorithms adapted from STL, defined to work primarily with iterators.
LookAheadIterator<T>	Iterator that allows the program to look at and operate on the next few elements without consuming them.
MergeIterator<T>	Iterator that merges the contents of two input iterators.
SingletonIterator<T>	Iterates over a single item.
StringTokenizerIterator	Adapts a StringTokenizer to the Iterator interface.
TransformAdjacentIterator<T,R>	Iterator that applies a given BinaryFunctor to successive pairs of elements from a given iterator, returning the results as elements.
TransformBinaryIterator<T1,T2,R>	Iterator that returns the results of applying the given functor to corresponding elements of two given iterators.
TransformIterator<T,R>	Iterator that returns the results of applying the given functor to the elements of the given iterator.
UniqueIterator<T>	Iterator that will not return the same element twice in succession.

Package net.sf.jga.util Description

Provides Facade objects for working with the algorithm functors, and a variety of utility iterators for various purposes.

The functionality that is adapted from STL is provided by a set of functors in the net.sf.jga.fn.algorithm package operate on iterators. To ease the transition to this approach, there are two facade objects whose methods correspond to the algorithms provided by STL.

The first, Algorithms, operates on collections, and is appropriate for getting easy answers to common questions over collections. The second, Iterators, is closer conceptually to the implementation, and is more appropriate if the same function is to be called several times for a given collection. Most of the methods in these two facades are a single logical statement (although sometimes the singe statement is broken up for formatting reasons) that constructs and invokes the appropriate algorithm functor.

The summary of the functions adapted from STL is as follows:

STL Function name	Facade method name	functor
accumulate()	accumulate()	Accumulate
adjacentDiff()	adjacentDiff()	TransformAdjacent(Minus)
adjacent_find()	findAdjacent()	FindAdjacent
count()	count()	Count
count_if()	count()	Count
equal()	equal()	varies based on form (3)
find()	find()	Find
find_first_of()	findElement()	FindElement
find_if()	find()	Find
for_each()	forEach()	ForEach (2)
lexicographical_compare()	lessThan()	varies based on form (3)
max()	maximum()	Find,MaxValue (4)
max_element()	maximumValue()	MaxValue [collection] Accumulate [iteration]
merge()	merge()	Merge
min()	minimum()	Find,MinValue (4)
min_element()	minimumValue()	MaxValue [collection] Accumulate [iteration]
mismatch()	mismatch()	FindMismatch
remove()	removeAll	n/a(5)
remove_if()	removeAll	RemoveAll
remove_copy()	removeAllCopy	RemoveAll(6)
remove_copy_if()	removeAllCopy	RemoveAll(6)
replace()	replaceAll	n/a(5)
replace_if()	replaceAll	ReplaceAll
replace_copy()	replaceAllCopy	ReplaceAll(6)
replace_copy_if()	replaceAllCopy	ReplaceAll(6)
search()	match()	FindSequence
search_n()	findRepeated()	FindRepeated
transform (unary form)	transformCopy	TransformUnary
transform (binary form)	transformCopy	TransformUnary
unique()	unique	n/a(5)
unique_copy()	uniqueCopy	Unique(6)

⁽²⁾ - The ForEach functor returns the result of the final call to the given functor, where the method returns the given functor.
⁽³⁾ - The comparison operations are not implemented in terms of functors found in net.sf.jga.fn.algorithm: they are generally implemented via Comparators defined in net.sf.jga.util and comparison functors from net.sf.jga.fn.comparison.
⁽⁴⁾ - Only supported for collections, not for iterations. Again, we'd need to be able to clone iterators in order to support them.
⁽⁵⁾ - Works with Lists only (not general Collections). The only option available for updating in place is via a ListIterator.
⁽⁶⁾ - Unlike C++, the X_copy forms append to the output collection, instead of overwriting it. In C++, the implementations can't assume the right to enlarge the output collection (it might be an array or some other fixed size structure) while in Java, the collections aren't inherently fixed size (if the user passes a fixed size or capped size collection to one of these methods, we'll pass through the appropriate exception, if necessary)