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