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

Interface Summary

Formattable<T>

Interface for classes that can support the formatting of values via a UnaryFunctor.

Class Summary

Algorithms	Deprecated. everything likely to be of value has been moved to static classes in the net.sf.jga.algorithms package
ArrayUtils	Miscellaneous utilities for working with arrays.
ArrayUtils.ArrayIterable<T>	Iterable wrapper around a given array.
ArrayUtils.ArrayIterator<T>	Iterates over an array of objects.
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.
CollectionUtils	General utilites for working with collections.
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.
FindIterator<T>	Iterator that provides the ability to skip to the first/next element that meets a particular criteria.
GenericComparator<T,R extends Comparable<? super R>>	Comparator that applies a functor to each argument, then compares the results.
IteratorComparator<T>	Deprecated. Moved to a nested class of net.sf.jga.algorithms.Compare
Iterators	Deprecated. all of the remaining functionality has been moved into
LookAheadIterator<T>	Iterator that allows the program to look at and operate on the next few elements without consuming them.
NullComparator<T>	Comparator Decorator used to gracefully compare null and non-null values.
SingletonIterator<T>	Iterates over a single item.
StringTokenizerIterator	Adapts a StringTokenizer to the Iterator interface.

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)