object.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-1.6.0).
003  * Copyright (c) 2007-2014 Franz Wilhelmstötter
004  *
005  * Licensed under the Apache License, Version 2.0 (the "License");
006  * you may not use this file except in compliance with the License.
007  * You may obtain a copy of the License at
008  *
009  *      http://www.apache.org/licenses/LICENSE-2.0
010  *
011  * Unless required by applicable law or agreed to in writing, software
012  * distributed under the License is distributed on an "AS IS" BASIS,
013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014  * See the License for the specific language governing permissions and
015  * limitations under the License.
016  *
017  * Author:
018  *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmx.at)
019  */
020 package org.jenetics.internal.util;
021 
022 import static java.lang.String.format;
023 import static java.util.Objects.requireNonNull;
024 
025 import java.util.Arrays;
026 
027 import javax.measure.Measurable;
028 import javax.measure.quantity.Duration;
029 import javax.measure.unit.SI;
030 
031 import org.jenetics.util.Function;
032 import org.jenetics.util.Seq;
033 import org.jenetics.util.StaticObject;
034 import org.jenetics.util.Verifiable;
035 import org.jenetics.util.arrays;
036 
037 /**
038  * Some helper methods for creating hash codes and comparing values.
039  *
040  @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
041  @since 1.0
042  @version 1.6 &mdash; <em>$Date: 2014-03-01 $</em>
043  */
044 public final class object extends StaticObject {
045     private object() {}
046 
047 
048     /**
049      * A range checking predicate which can be used to check whether the elements
050      * of an array are within an given range. If not, an
051      {@link IllegalArgumentException} is thrown. If one value is {@code null},
052      * an {@link NullPointerException} is thrown.
053      <p/>
054      *
055      * The following code will throw an {@link IllegalArgumentException} if the
056      * integers in the array are smaller than zero and greater than 9.
057      * [code]
058      * final Array<Integer> array = ...
059      * arrays.forEach(CheckRange<(0, 10));
060      * [/code]
061      */
062     public static <C extends Comparable<? super C>> Function<C, Boolean>
063     CheckRange(final C min, final C max)
064     {
065         return new Function<C,Boolean>() {
066             @Override
067             public Boolean apply(final C value) {
068                 requireNonNull(value);
069                 if (value.compareTo(min|| value.compareTo(max>= 0) {
070                     throw new IllegalArgumentException(format(
071                         "Given value %s is out of range [%s, %s)",
072                         value, min, max
073                     ));
074                 }
075                 return Boolean.TRUE;
076             }
077         };
078     }
079 
080 
081     /**
082      * Verifies {@link org.jenetics.util.Verifiable} array elements. All elements are valid if the
083      * condition
084      * [code]
085      * arrays.forAll(Verify) == true
086      * [/code]
087      * is true.
088      */
089     public static final Function<Verifiable, Boolean>
090         Verify = new Function<Verifiable,Boolean>() {
091         @Override
092         public Boolean apply(final Verifiable object) {
093             return object.isValid() ? Boolean.TRUE : Boolean.FALSE;
094         }
095     };
096 
097     /**
098      * A {@code null} checking predicate which can be used to check an array
099      * for null values. The following code will throw an
100      {@link NullPointerException} if one of the array elements is {@code null}.
101      *
102      * [code]
103      * final Array<String> array = ...
104      * array.forEach(NonNull("Object"));
105      * ...
106      * final String[] array = ...
107      * arrays.forEach(array, NonNull);
108      * [/code]
109      */
110     public static final Function<Object, Boolean> NonNull = NonNull("Object");
111 
112     /**
113      * A {@code null} checking predicate which can be used to check an array
114      * for null values. The following code will throw an
115      {@link NullPointerException} if one of the array elements is {@code null}.
116      *
117      * [code]
118      * final Array<String> array = ...
119      * array.forEach(NonNull("Object"));
120      * ...
121      * final String[] array = ...
122      * arrays.forEach(array, NonNull);
123      * [/code]
124      */
125     public static Function<Object, Boolean> NonNull(final String message) {
126         return new Function<Object,Boolean>() {
127             @Override public Boolean apply(final Object object) {
128                 requireNonNull(object, message );
129                 return Boolean.TRUE;
130             }
131         };
132     }
133 
134     /**
135      * Check if the specified value is not negative.
136      *
137      @param value the value to check.
138      @param message the exception message.
139      @return the given value.
140      @throws IllegalArgumentException if {@code value < 0}.
141      */
142     public static double nonNegative(final double value, final String message) {
143         if (value < 0) {
144             throw new IllegalArgumentException(format(
145                 "%s must not negative: %f.", message, value
146             ));
147         }
148         return value;
149     }
150 
151     /**
152      * Check if the specified value is not negative.
153      *
154      @param value the value to check.
155      @return the given value.
156      @throws IllegalArgumentException if {@code value < 0}.
157      */
158     public static double nonNegative(final double value) {
159         return nonNegative(value, "Value");
160     }
161 
162     /**
163      * Check if the given integer is negative.
164      *
165      @param length the value to check.
166      @throws NegativeArraySizeException if the given {@code length} is smaller
167      *           than zero.
168      */
169     public static int nonNegative(final int length) {
170         if (length < 0) {
171             throw new NegativeArraySizeException(
172                 "Length must be greater than zero, but was " + length + ". "
173             );
174         }
175         return length;
176     }
177 
178     /**
179      * Check if the given double value is within the closed range {@code [0, 1]}.
180      *
181      @param p the probability to check.
182      @return p if it is a valid probability.
183      @throws IllegalArgumentException if {@code p} is not a valid probability.
184      */
185     public static double checkProbability(final double p) {
186         if (p < 0.0 || p > 1.0) {
187             throw new IllegalArgumentException(format(
188                 "The given probability is not in the range [0, 1]: %f", p
189             ));
190         }
191         return p;
192     }
193 
194     /**
195      * Compares the two given {@code boolean} values.
196      *
197      @param a first value to compare.
198      @param b second value to compare.
199      @return {@code true} if the given values are equal, {@code false}
200      *          otherwise.
201      */
202     public static boolean eq(final boolean a, final boolean b) {
203         return a == b;
204     }
205 
206     /**
207      * Compares the two given {@code boolean} arrays.
208      *
209      @param a first value to compare.
210      @param b second value to compare.
211      @return {@code true} if the given values are equal, {@code false}
212      *          otherwise.
213      */
214     public static boolean eq(final boolean[] a, final boolean[] b) {
215         return Arrays.equals(a, b);
216     }
217 
218     /**
219      * Compares the two given {@code byte} values.
220      *
221      @param a first value to compare.
222      @param b second value to compare.
223      @return {@code true} if the given values are equal, {@code false}
224      *          otherwise.
225      */
226     public static boolean eq(final byte a, final byte b) {
227         return a == b;
228     }
229 
230     /**
231      * Compares the two given {@code byte} arrays.
232      *
233      @param a first value to compare.
234      @param b second value to compare.
235      @return {@code true} if the given values are equal, {@code false}
236      *          otherwise.
237      */
238     public static boolean eq(final byte[] a, final byte[] b) {
239         return Arrays.equals(a, b);
240     }
241 
242     /**
243      * Compares the two given {@code char} values.
244      *
245      @param a first value to compare.
246      @param b second value to compare.
247      @return {@code true} if the given values are equal, {@code false}
248      *          otherwise.
249      */
250     public static boolean eq(final char a, final char b) {
251         return a == b;
252     }
253 
254     /**
255      * Compares the two given {@code char} arrays.
256      *
257      @param a first value to compare.
258      @param b second value to compare.
259      @return {@code true} if the given values are equal, {@code false}
260      *          otherwise.
261      */
262     public static boolean eq(final char[] a, final char[] b) {
263         return Arrays.equals(a, b);
264     }
265 
266     /**
267      * Compares the two given {@code short} values.
268      *
269      @param a first value to compare.
270      @param b second value to compare.
271      @return {@code true} if the given values are equal, {@code false}
272      *          otherwise.
273      */
274     public static boolean eq(final short a, final short b) {
275         return a == b;
276     }
277 
278     /**
279      * Compares the two given {@code short} arrays.
280      *
281      @param a first value to compare.
282      @param b second value to compare.
283      @return {@code true} if the given values are equal, {@code false}
284      *          otherwise.
285      */
286     public static boolean eq(final short[] a, final short[] b) {
287         return Arrays.equals(a, b);
288     }
289 
290     /**
291      * Compares the two given {@code int} values.
292      *
293      @param a first value to compare.
294      @param b second value to compare.
295      @return {@code true} if the given values are equal, {@code false}
296      *          otherwise.
297      */
298     public static boolean eq(final int a, final int b) {
299         return a == b;
300     }
301 
302     /**
303      * Compares the two given {@code int} arrays.
304      *
305      @param a first value to compare.
306      @param b second value to compare.
307      @return {@code true} if the given values are equal, {@code false}
308      *          otherwise.
309      */
310     public static boolean eq(final int[] a, final int[] b) {
311         return Arrays.equals(a, b);
312     }
313 
314     /**
315      * Compares the two given {@code long} values.
316      *
317      @param a first value to compare.
318      @param b second value to compare.
319      @return {@code true} if the given values are equal, {@code false}
320      *          otherwise.
321      */
322     public static boolean eq(final long a, final long b) {
323         return a == b;
324     }
325 
326     /**
327      * Compares the two given {@code long} arrays.
328      *
329      @param a first value to compare.
330      @param b second value to compare.
331      @return {@code true} if the given values are equal, {@code false}
332      *          otherwise.
333      */
334     public static boolean eq(final long[] a, final long[] b) {
335         return Arrays.equals(a, b);
336     }
337 
338     /**
339      * Compares the two given {@code float} values.
340      *
341      @param a first value to compare.
342      @param b second value to compare.
343      @return {@code true} if the given values are equal, {@code false}
344      *          otherwise.
345      */
346     public static boolean eq(final float a, final float b) {
347         return Float.floatToIntBits(a== Float.floatToIntBits(b);
348     }
349 
350     /**
351      * Compares the two given {@code float} arrays.
352      *
353      @param a first value to compare.
354      @param b second value to compare.
355      @return {@code true} if the given values are equal, {@code false}
356      *          otherwise.
357      */
358     public static boolean eq(final float[] a, final float[] b) {
359         return Arrays.equals(a, b);
360     }
361 
362     /**
363      * Compares the two given {@code double} values.
364      *
365      @param a first value to compare.
366      @param b second value to compare.
367      @return {@code true} if the given values are equal, {@code false}
368      *          otherwise.
369      */
370     public static boolean eq(final double a, final double b) {
371         return Double.doubleToLongBits(a== Double.doubleToLongBits(b);
372     }
373 
374     /**
375      * Compares the two given {@code double} arrays.
376      *
377      @param a first value to compare.
378      @param b second value to compare.
379      @return {@code true} if the given values are equal, {@code false}
380      *          otherwise.
381      */
382     public static boolean eq(final double[] a, final double[] b) {
383         return Arrays.equals(a, b);
384     }
385 
386     /**
387      * Compares the two given {@code Enum} values.
388      *
389      @param a first value to compare.
390      @param b second value to compare.
391      @return {@code true} if the given values are equal, {@code false}
392      *          otherwise.
393      */
394     public static boolean eq(final Enum<?> a, final Enum<?> b) {
395         return a == b;
396     }
397 
398     /**
399      * Compares the two given {@code Object} values.
400      *
401      @param a first value to compare.
402      @param b second value to compare.
403      @return {@code true} if the given values are equal, {@code false}
404      *          otherwise.
405      */
406     public static boolean eq(final Object a, final Object b) {
407         return (a != null ? a.equals(b: b == null);
408     }
409 
410     public static boolean eq(final Measurable<Duration> a, final Measurable<Duration> b) {
411         if (a == null && b == null) {
412             return true;
413         }
414         return a != null && b != null &&
415             a.longValue(SI.NANO(SI.SECOND)) == b.longValue(SI.NANO(SI.SECOND));
416     }
417 
418     /**
419      * Compares the two given {@code Object} arrays.
420      *
421      @param a first value to compare.
422      @param b second value to compare.
423      @return {@code true} if the given values are equal, {@code false}
424      *          otherwise.
425      */
426     public static boolean eq(final Object[] a, final Object[] b) {
427         return Arrays.equals(a, b);
428     }
429 
430     /**
431      * Compares the two given {@code Seq} values.
432      *
433      @param a first value to compare.
434      @param b second value to compare.
435      @return {@code true} if the given values are equal, {@code false}
436      *          otherwise.
437      */
438     public static boolean eq(final Seq<?> a, final Seq<?> b) {
439         return arrays.equals(a, b);
440     }
441 
442 }