ElementComparator.java
01 /*
02  * Java Genetic Algorithm Library (jenetics-5.1.0).
03  * Copyright (c) 2007-2019 Franz Wilhelmstötter
04  *
05  * Licensed under the Apache License, Version 2.0 (the "License");
06  * you may not use this file except in compliance with the License.
07  * You may obtain a copy of the License at
08  *
09  *      http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  * Author:
18  *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
19  */
20 package io.jenetics.ext.moea;
21 
22 import java.util.Comparator;
23 import java.util.function.Function;
24 
25 /**
26  * Defines the order of two elements of a given <em>vector</em> type {@code V}.
27  * The following example creates an {@code ElementComparator} function for a
28  * {@code double[] array}:
29  <pre>{@code
30  * final ElementComparator<double[]> comp =
31  *     (u, v, i) -> Double.compare(u[i], v[i]);
32  * }</pre>
33  *
34  @param <V> the vector type
35  *
36  @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
37  @version 4.1
38  @since 4.1
39  */
40 @FunctionalInterface
41 public interface ElementComparator<V> {
42 
43     /**
44      * Compares the components of {@code a} and {@code b} at the given
45      * {@code index}. E.g.
46      <pre>{@code
47      * final ElementComparator<double[]> comp =
48      *     (u, v, i) -> Double.compare(u[i], v[i]);
49      * }</pre>
50      *
51      @param u the first vector
52      @param v the second vector
53      @param index the vector index
54      @return a negative integer, zero, or a positive integer as the
55      *         first argument is less than, equal to, or greater than the
56      *         second.
57      @throws NullPointerException if either {@code a} or {@code b} is
58      *        {@code null}
59      @throws IndexOutOfBoundsException if the index is out of range
60      *         {@code (index < 0 || index >= length(a)  || index >= length(b))}
61      */
62     public int compare(final V u, final V v, final int index);
63 
64     /**
65      * Returns a comparator that imposes the reverse ordering of this
66      * comparator.
67      *
68      @return a comparator that imposes the reverse ordering of this
69      *         comparator.
70      */
71     public default ElementComparator<V> reversed() {
72         return (u, v, i-> compare(v, u, i);
73     }
74 
75     /**
76      * Return an element comparator for the mapped type {@code T}.
77      *
78      @param mapper the mapper function
79      @param <T> the new comparator type
80      @return an element comparator for the mapped type {@code T}
81      */
82     public default <T> ElementComparator<T>
83     map(final Function<? super T, ? extends V> mapper) {
84         return (u, v, i-> compare(mapper.apply(u), mapper.apply(v), i);
85     }
86 
87     /**
88      * Return a comparator which takes the component at the give {@code index}
89      * for comparison two objects of type {@code T}.
90      *
91      @param index the component index
92      @return the component comparator for the given {@code index}
93      */
94     public default Comparator<V> ofIndex(final int index) {
95         return (a, b-> compare(a, b, index);
96     }
97 
98 }