Intro

The purpose of this project is to provide an extension to Java Collections adding the visitor semantics to substitute the usage of loops(for and while) by a method call on the collection where the code block to be executed is passed encapsulated as a visitor class.

Thus instead of:

    Collection<String> collection = ...
    for(String name : collection ) {
        [code block to execute over]
    }

With Numenius it would be:

    ExtendedCollection<String> collection = ...
    collection.each( codeBlockAsVisitor );

This allows for reuse of code blocks over other collections and singular elements.

Filters

Filtering allows the usage of Hamcrest matchers to produce new collections of equivalent kind with filtered out elements according to a given matcher.

For example, imagine a collection of movement types of which we want only the ones implementing SillyWalks:

    ExtendedCollection<Movement> movements = ...
    ExtendedCollection<Movement> sillyWalks = movements.filter( instanceOf(SillyWalk.class) );

Selectors

Selectors are just like filters but return a single element matching the matcher instead of multiple and they return the object matched instead of a collection.

There are two ways to select a element, the regular select method will deliver the first match, if any, and exit the search while the selectUnique runs through the entire collection and if it encounters more than one match it breaks into exception.

For example, to search for an possibly non-unique match:

    trueFriend = brotherhood.select( equalsTo("Samwise Gangee") );

To select an element that is guaranteed to be unique you can use selectUnique:

    trueFriend = brotherhood.selectUnique( equalsTo("Samwise Gangee") );

Finally, selectors can be defaulted, through the setDefault method an object can be used in case none is found to match. It does not need to be part of the collection.

Wrappers

In order to use original collections implementation there are wrappers for each kind of collection implemented in Numenius, lists can be wrapped in ListWrapper and sets can be wrapped by SetWrapper. In case the default constructor is used, a new related collection is created automatically

Missing Maps

You may have noticed that maps are not part of this library, they were not forgotten, they were left out on purpose. I find that maps conceal the need for a new true class, by allowing two separate entities to be related by key/value it functions as a weak type definition.

And them people do all kinds of twisting to work with it when they should have created a class that would present no need of twisting.