Package net.sf.jga.util

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


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 nameFacade method namefunctor
equal()equal()varies based on form (3)
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]
min()minimum()Find,MinValue (4)
min_element()minimumValue()MaxValue [collection]
Accumulate [iteration]
transform (unary form)transformCopyTransformUnary
transform (binary form)transformCopyTransformUnary
(2) - The ForEach functor returns the result of the final call to the given functor, where the method returns the given functor.
(3) - 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.
(4) - Only supported for collections, not for iterations. Again, we'd need to be able to clone iterators in order to support them.
(5) - Works with Lists only (not general Collections). The only option available for updating in place is via a ListIterator.
(6) - 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)

Copyright © 2002-2006 David A. Hall. All Rights Reserved.