net.sourceforge.cilib.util.selection
Class Selection<E>

java.lang.Object
  net.sourceforge.cilib.util.selection.Selection<E>

Type Parameters:

E - The comparable type.

All Implemented Interfaces:

SelectionSyntax<E>

public final class Selection<E>
extends Object
implements SelectionSyntax<E>

A Selection is an abstraction that allows operations to be applied to a collection instace that result in a selection of list elements, based on a varied of potential combination of operators.

The Selection is implemented to be a fluent interface that is easily understandable and for which the intent of the selection is clear.

As an example, applying tournament selection on a list of Entity instances would be done as follows:

 List selection = Selection.from(population).orderBy(new RandomOrdering()).first(tournamentSize)
          .orderBy(new SortedOrdering()).last().select();

 return selection.get(0);
 

where T is a Comparable type. The above performs the following steps:

1. From the provided list of entities, order the entities randomly.
2. From the randomized list, select the first tournamentSize entities.
3. From the subset of elements, order them from smallest to largest, based on fitness.
4. Finally, select the entity that is the "most fit" and then return it as the winner of the tournament.

Author:

gpampara

Nested Class Summary

static class

Selection.Entry<E> This class provides the notion of an entry within a list for the selection process.

Method Summary

List<Selection.Entry<E>>	entries() Obtain the list of internal Entry instances.
SelectionSyntax<E>	first() Obtain the first result from the current selection.
SelectionSyntax<E>	first(int number) Obtain the frist number of elements from the current selection.
static <T> Selection<T>	from(List<? extends T> elements) Create a selection that will operate on the provided collection.
SelectionSyntax<E>	last() Obtain the last element contained within the current selection.
SelectionSyntax<E>	last(int number) Obtain the last number of elements from the current selection.
SelectionSyntax<E>	orderBy(Ordering<E> ordering) Apply the provided ordering on the current selection.
static <T> T	randomFrom(List<? extends T> elements, Random random) Obtain a random element from the provided list.
static <T> List<T>	randomFrom(List<? extends T> elements, Random random, int number) Obtain a random element sublist from the provided list.
List<E>	select() Obtain the result of the selection.
E	singleSelect() Obtain the first result of the selection.
SelectionSyntax<E>	weigh(Weighing<E> weighing) Apply the provided weighing on the current selection.

Methods inherited from class java.lang.Object

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

Method Detail

from

public static <T> Selection<T> from(List<? extends T> elements)

Create a selection that will operate on the provided collection.

Type Parameters:

T - The comparable type.

Parameters:

elements - The collection of elements to operate on.

Returns:

A selection based on the provided collection.

randomFrom

public static <T> T randomFrom(List<? extends T> elements,
                               Random random)

Obtain a random element from the provided list. This is a convenience method that allows the selection of a random element from a provided list, based on a provided Random.

This method terminates the selection.

Type Parameters:

T - The type of the selection.

Parameters:

elements - The element from which the selection is to be performed.

random - The random number to be used in the selection.

Returns:

A random element within elements.

randomFrom

public static <T> List<T> randomFrom(List<? extends T> elements,
                                     Random random,
                                     int number)

Obtain a random element sublist from the provided list. This is a convenience method that allows the selection of random elements from a provided list, based on a provided Random.

This method terminates the selection.

Type Parameters:

T - The selection type.

Parameters:

elements - The elements from which the selection is to be performed.

random - The random number to be used in the selection.

number - The number of elements to select.

Returns:

A list of random elements contained in elements.

orderBy

public SelectionSyntax<E> orderBy(Ordering<E> ordering)

Apply the provided ordering on the current selection. The result of the operation will result in a modified selection.

Specified by:

orderBy in interface SelectionSyntax<E>

Parameters:

ordering - The ordering to orderBy.

Returns:

A selection upon which the ordering has been applied.

Throws:

UnsupportedOperationException - if the ordering cannot be applied.

weigh

public SelectionSyntax<E> weigh(Weighing<E> weighing)

Apply the provided weighing on the current selection. The result of the operation will result in new weighed selection.

Specified by:

weigh in interface SelectionSyntax<E>

Parameters:

weighing - The weighing to weighWith.

Returns:

A selection upon which the weighing has been applied.

first

public SelectionSyntax<E> first()

Obtain the first result from the current selection. These elements are returned from the front of the current selection.

Specified by:

first in interface SelectionSyntax<E>

Returns:

A selection containing the first element.

first

public SelectionSyntax<E> first(int number)

Obtain the frist number of elements from the current selection. These elements are returned from the front of the current selection.

Specified by:

first in interface SelectionSyntax<E>

Parameters:

number - The number of elements to return.

Returns:

A selection containing the first number elements.

last

public SelectionSyntax<E> last()

Obtain the last element contained within the current selection.

Specified by:

last in interface SelectionSyntax<E>

Returns:

A selection containing the last element.

last

public SelectionSyntax<E> last(int number)

Obtain the last number of elements from the current selection.

Specified by:

last in interface SelectionSyntax<E>

Parameters:

number - The number of elements to select.

Returns:

A selection containing the last number of elements.

select

public List<E> select()

Obtain the result of the selection.

Specified by:

select in interface SelectionSyntax<E>

Returns:

A list of elements that the selection has selected.

singleSelect

public E singleSelect()

Obtain the first result of the selection.

Specified by:

singleSelect in interface SelectionSyntax<E>

Returns:

The first element returned by the selection.

entries

public List<Selection.Entry<E>> entries()

Obtain the list of internal Entry instances.

Specified by:

entries in interface SelectionSyntax<E>

Returns:

The list of internal Entry instances.