org.tbull.util
Class Collections

Object
  org.tbull.util.Collections

public class Collections
extends Object

Utilities for dealing with Collections and alike.

Instead of insisting on Collections or even more specific structures like Lists, the tools here deal with Iterables (each Collection is just another Iterable) and Iterators. This helps you in using the tools on your custom collections-like structures that don't actually implement Collection, but do implement Iterable. If your source material is not even iterable (like Maps), you may still get hold of an Iterator somehow (like Map.keySet().iterator()), and you can still use the alternative incarnation of each of the functions.

Ah yes, the declarations look kind of scary with all the generic type parameters, but don't be afraid, it's actually quite easy. Some examples:

Grepping

      import org.tbull.util.Collections;
      import org.tbull.util.Grepper;

      /* a Grepper defines what properties elements need to have to get grepped
       *  this grepper choses each Node which is collapsed (not expanded)
       *  (the Node class is kindly provided by your imagination)
       */
      private static class CollapsedGrepper implements Grepper {
          public @Override boolean grep(Node element) {
              return !element.expanded();
          }
      }

      /* grep elements satisfying the collapsed condition from the nodes list */
      List nodes, collapsed_nodes;
      nodes = ... (get it from somewhere)
      collapsed_nodes = Collections.grep(new CollapsedGrepper(), nodes);

      /* the same with a self-supplied destination list */
      collapsed_nodes = new LinkedList();
      Collections.grep(collapsed_nodes, new CollapsedGrepper(), nodes);
          // returns collapsed_nodes for your convenience

      /* with multiple input lists */
      collapsed_nodes = Collections.grep(new CollapsedGrepper(), nodes, nodes2, nodes3);

      /* for frequent use of grep in a compilation unit, consider static import */
      import static org.tbull.util.Collections.grep;
      collapsed_nodes = grep(new CollapsedGrepper(), nodes);

      /* iterators and chaining */
      // TODO



      /* count only */
      // TODO

  

If you want to grep Strings that match a regular expression, give Grepper.RegexGrepper a shot.

Mapping

Unchecked cast warnings

When using these functions, upto and including Java 6 the compiler will issue warnings over type safety, like "A generic array of Iterable<Integer> is created for a varargs parameter". Don't blame yourself, this warning is not your fault. It's due to a conceptual incompatibility of Java arrays and generics (and variable length argument lists are passed as an array to the function). The only thing you can do is to add the annotation

   @SuppressWarnings("unchecked")

to the method from which you invoke these functions.

Beginning with Java 7, these warnings are no longer generated.

ToDo:

finish class documentation, provide docs for map family of functions, tests for map family of functions

Ceterum censeo HTML in Javadoc is the dumbest idea ever.

Nested Class Summary

static class	Collections.LazyGrepIterator<E> An iterator that provides the grepLazy functionality.
static class	Collections.LazyMapIterator<I,O> An iterator that provides the mapLazy functionality.

Constructor Summary

Collections()

Method Summary

static <E> List<E>	grep(Grepper<? super E> grepper, Iterable<E>... lists) Greps through one or more Iterables, returning the results in a list.
static <E> List<E>	grep(Grepper<? super E> grepper, Iterator<E>... iterators) Greps from one or more Iterators, returning the results in a list.
static <E> List<? super E>	grep(List<? super E> dest, Grepper<? super E> grepper, Iterable<E>... lists) Greps through one or more Iterables, writing the results to a destination list.
static <E> List<? super E>	grep(List<? super E> dest, Grepper<? super E> grepper, Iterator<E>... iterators) Greps from one or more Iterators, writing the results to a destination list.
static <E> int	grepCount(Grepper<? super E> grepper, Iterable<E>... lists) Counts how many items the grepper picks from the input elements.
static <E> int	grepCount(Grepper<? super E> grepper, Iterator<E>... iterators) Counts how many items the grepper picks from the input elements.
static <E> IterableIterator<E>	grepLazy(Grepper<? super E> grepper, Iterable<E>... lists) Greps through one or more Iterables, returning one result element at a time.
static <E> IterableIterator<E>	grepLazy(Grepper<? super E> grepper, Iterator<E>... iterators) Greps through one or more Iterators, returning one result element at a time.
static <I,O> List<? super O>	map(List<? super O> dest, Mapper<? super I,? extends O> mapper, Iterable<I>... lists)
static <I,O> List<? super O>	map(List<? super O> dest, Mapper<? super I,? extends O> mapper, Iterator<I>... iterators)
static <I,O> List<O>	map(Mapper<? super I,? extends O> mapper, Iterable<I>... lists)
static <I,O> List<O>	map(Mapper<? super I,? extends O> mapper, Iterator<I>... iterators)
static <I,O> IterableIterator<O>	mapLazy(Mapper<? super I,? extends O> mapper, Iterable<I>... lists)
static <I,O> IterableIterator<O>	mapLazy(Mapper<? super I,? extends O> mapper, Iterator<I>... iterators)

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Collections

public Collections()

Method Detail

grep

public static <E> List<E> grep(Grepper<? super E> grepper,
                               Iterable<E>... lists)

Greps through one or more Iterables, returning the results in a list.

This is potentially less efficient than grep(List, Grepper, Iterable...) because the result list has to be allocated and grown.

In case you supply a handcrafted array in place of the lists vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the list elements

Parameters:

grepper - The grepper that is asked for each element if the grep condition is met.

lists - input list(s) to grep from

Returns:

A List containing the elements that made it through the Grepper.

grep

public static <E> List<E> grep(Grepper<? super E> grepper,
                               Iterator<E>... iterators)

Greps from one or more Iterators, returning the results in a list.

Use this if you got hold of an Iterator without having access to a backing Collection (or whatever Iterable).

This is potentially less efficient than grep(List, Grepper, Iterator...) because the result list has to be allocated and grown.

In case you supply a handcrafted array in place of the iterators vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the elements the iterator returns

Parameters:

grepper - The grepper that is asked for each element if the grep condition is met.

iterators - input iterator(s) to grep from

Returns:

A List containing the elements that made it through the Grepper.

grep

public static <E> List<? super E> grep(List<? super E> dest,
                                       Grepper<? super E> grepper,
                                       Iterable<E>... lists)

Greps through one or more Iterables, writing the results to a destination list.

This is potentially more efficient than grep(Grepper, Iterable...) because the caller can supply a pre-allocated List with the expected necessary capacity. Use this, if you can estimate how many elements will make it through the Grepper, or if you need the result in a specific implementation of List.

In case you supply a handcrafted array in place of the lists vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the list elements

Parameters:

dest - destination list to which to add the results to

grepper - The grepper that is asked for each element if the grep condition is met.

lists - input list(s) to grep from

Returns:

The destination list dest, for chaining.

grep

public static <E> List<? super E> grep(List<? super E> dest,
                                       Grepper<? super E> grepper,
                                       Iterator<E>... iterators)

Greps from one or more Iterators, writing the results to a destination list. Use this if you got hold of an Iterator without having access to a backing Collection (or whatever Iterable).

This is potentially more efficient than grep(Grepper, Iterator...) because the caller can supply a pre-allocated List with the expected necessary capacity. Use this, if you can estimate how many elements will make it through the Grepper, or if you need the result in a specific implementation of List.

In case you supply a handcrafted array in place of the iterators vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the elements the iterator returns

Parameters:

dest - destination list to which to add the results to

grepper - The grepper that is asked for each element if the grep condition is met.

iterators - input iterator(s) to grep from

Returns:

The destination list dest, for chaining.

grepLazy

public static <E> IterableIterator<E> grepLazy(Grepper<? super E> grepper,
                                               Iterable<E>... lists)

Greps through one or more Iterables, returning one result element at a time. Hands you a LazyGrepIterator which returns the individual result elements. See there for details of behaviour.

Elements from the input lists are only fetched when necessary to compute the result of a call to the returned iterator's hasNext() or next(). Also, an input list is not queried before the input before it is exhausted.

This is particularly useful if you have large amounts of material to grep through, or if it's in the input's nature to make up one element at a time and dumping them all at once prior to further processing would impose a peak level of stress on the generating unit (like the results of an SQL query).

In case you supply a handcrafted array in place of the lists vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the list elements

Parameters:

grepper - The grepper that is asked for each element if the grep condition is met.

lists - input list(s) to grep from

Returns:

A properly set up instance of Collections.LazyGrepIterator.

grepLazy

public static <E> IterableIterator<E> grepLazy(Grepper<? super E> grepper,
                                               Iterator<E>... iterators)

Greps through one or more Iterators, returning one result element at a time. Hands you a LazyGrepIterator which returns the individual result elements. See there for details of behaviour.

Elements from the input iterators are only fetched when necessary to compute the result of a call to the returned iterator's hasNext() or next(). Also, an input list is not queried before the input before it is exhausted.

This is particularly useful if you have large amounts of material to grep through, or if it's in the input's nature to make up one element at a time and dumping them all at once prior to further processing would impose a peak level of stress on the generating unit (like the results of an SQL query).

In case you supply a handcrafted array in place of the iterators vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the elements the iterator returns

Parameters:

grepper - The grepper that is asked for each element if the grep condition is met.

iterators - input iterator(s) to grep from

Returns:

A properly set up instance of Collections.LazyGrepIterator.

grepCount

public static <E> int grepCount(Grepper<? super E> grepper,
                                Iterable<E>... lists)

Counts how many items the grepper picks from the input elements. This is logically equivalent to
grep(Grepper, Iterable...).size(), but doesn't catch the results, only counts them.

Note: It is not recommended to use this solely to find out which capacity a result list should be allocated for, it's far too expensive for that.

In case you supply a handcrafted array in place of the lists vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the list elements

Parameters:

grepper - The grepper that is asked for each element if the grep condition is met.

lists - input list(s) to grep from

Returns:

how many elements made it through the grepper.

grepCount

public static <E> int grepCount(Grepper<? super E> grepper,
                                Iterator<E>... iterators)

Counts how many items the grepper picks from the input elements. This is logically equivalent to
grep(Grepper, Iterator...).size(), but doesn't catch the results, only counts them.

Note: It is not recommended to use this solely to find out which capacity a result list should be allocated for, it's far too expensive for that.

In case you supply a handcrafted array in place of the iterators vararg parameter, be advised that null pointers are forbidden.

Type Parameters:

E - type of the elements the iterator returns

Parameters:

grepper - The grepper that is asked for each element if the grep condition is met.

iterators - input iterator(s) to grep from

Returns:

how many elements made it through the grepper.

map

public static <I,O> List<O> map(Mapper<? super I,? extends O> mapper,
                                Iterable<I>... lists)

map

public static <I,O> List<O> map(Mapper<? super I,? extends O> mapper,
                                Iterator<I>... iterators)

map

public static <I,O> List<? super O> map(List<? super O> dest,
                                        Mapper<? super I,? extends O> mapper,
                                        Iterable<I>... lists)

map

public static <I,O> List<? super O> map(List<? super O> dest,
                                        Mapper<? super I,? extends O> mapper,
                                        Iterator<I>... iterators)

mapLazy

public static <I,O> IterableIterator<O> mapLazy(Mapper<? super I,? extends O> mapper,
                                                Iterable<I>... lists)

mapLazy

public static <I,O> IterableIterator<O> mapLazy(Mapper<? super I,? extends O> mapper,
                                                Iterator<I>... iterators)