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.util;
021 
022 import static java.lang.String.format;
023 import static java.util.Objects.requireNonNull;
024 
025 import java.util.Arrays;
026 import java.util.Objects;
027 
028 import javax.measure.Measurable;
029 import javax.measure.quantity.Duration;
030 import javax.measure.unit.SI;
031 
032 import org.jenetics.internal.util.DefaultHashCodeBuilder;
033 
034 /**
035  * Some helper methods for creating hash codes and comparing values.
036  *
037  @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
038  @since 1.0
039  @version 1.3 &mdash; <em>$Date: 2014-03-01 $</em>
040  *
041  @deprecated Will be (re)moved; internal use only.
042  */
043 @Deprecated
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 final <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 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 final 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      * Checks that the specified object reference is not {@code null}.
136      *
137      @param obj the object to check.
138      @param message the error message.
139      @return {@code obj} if not {@code null}.
140      @throws NullPointerException if {@code obj} is {@code null}.
141      *
142      @deprecated Use {@link java.util.Objects#requireNonNull(Object, String)}
143      *             instead.
144      */
145     @Deprecated
146     public static <T> T nonNull(final T obj, final String message) {
147         if (obj == null) {
148             throw new NullPointerException(message + " must not be null.");
149         }
150         return obj;
151     }
152 
153     /**
154      * Checks that the specified object reference is not {@code null}.
155      *
156      @param obj the object to check.
157      @return {@code obj} if not {@code null}.
158      @throws NullPointerException if {@code obj} is {@code null}.
159      *
160      @deprecated Use {@link java.util.Objects#requireNonNull(Object)} instead.
161      */
162     @Deprecated
163     public static <T> T nonNull(final T obj) {
164         return nonNull(obj, "Object");
165     }
166 
167     /**
168      * Check if the specified value is not negative.
169      *
170      @param value the value to check.
171      @param message the exception message.
172      @return the given value.
173      @throws IllegalArgumentException if {@code value < 0}.
174      */
175     public static double nonNegative(final double value, final String message) {
176         if (value < 0) {
177             throw new IllegalArgumentException(format(
178                     "%s must not negative: %f.", message, value
179                 ));
180         }
181         return value;
182     }
183 
184     /**
185      * Check if the specified value is not negative.
186      *
187      @param value the value to check.
188      @return the given value.
189      @throws IllegalArgumentException if {@code value < 0}.
190      */
191     public static double nonNegative(final double value) {
192         return nonNegative(value, "Value");
193     }
194 
195     /**
196      * Check if the given integer is negative.
197      *
198      @param length the value to check.
199      @throws NegativeArraySizeException if the given {@code length} is smaller
200      *           than zero.
201      */
202     public static int nonNegative(final int length) {
203         if (length < 0) {
204             throw new NegativeArraySizeException(
205                 "Length must be greater than zero, but was " + length + ". "
206             );
207         }
208         return length;
209     }
210 
211     /**
212      * Check if the given double value is within the closed range {@code [0, 1]}.
213      *
214      @param p the probability to check.
215      @return p if it is a valid probability.
216      @throws IllegalArgumentException if {@code p} is not a valid probability.
217      */
218     public static double checkProbability(final double p) {
219         if (p < 0.0 || p > 1.0) {
220             throw new IllegalArgumentException(format(
221                 "The given probability is not in the range [0, 1]: %f", p
222             ));
223         }
224         return p;
225     }
226 
227     /**
228      * Create a HashCodeBuilder for the given type.
229      *
230      @param type the type the HashCodeBuilder is created for.
231      @return a new HashCodeBuilder.
232      *
233      @deprecated Will be (re)moved; internal use only.
234      */
235     @Deprecated
236     public static HashCodeBuilder hashCodeOf(final Class<?> type) {
237         return new DefaultHashCodeBuilder(type);
238     }
239 
240     /**
241      * Compares the two given {@code boolean} values.
242      *
243      @param a first value to compare.
244      @param b second value to compare.
245      @return {@code true} if the given values are equal, {@code false}
246      *          otherwise.
247      */
248     public static boolean eq(final boolean a, final boolean b) {
249         return a == b;
250     }
251 
252     /**
253      * Compares the two given {@code boolean} arrays.
254      *
255      @param a first value to compare.
256      @param b second value to compare.
257      @return {@code true} if the given values are equal, {@code false}
258      *          otherwise.
259      */
260     public static boolean eq(final boolean[] a, final boolean[] b) {
261         return Arrays.equals(a, b);
262     }
263 
264     /**
265      * Compares the two given {@code byte} values.
266      *
267      @param a first value to compare.
268      @param b second value to compare.
269      @return {@code true} if the given values are equal, {@code false}
270      *          otherwise.
271      */
272     public static boolean eq(final byte a, final byte b) {
273         return a == b;
274     }
275 
276     /**
277      * Compares the two given {@code byte} arrays.
278      *
279      @param a first value to compare.
280      @param b second value to compare.
281      @return {@code true} if the given values are equal, {@code false}
282      *          otherwise.
283      */
284     public static boolean eq(final byte[] a, final byte[] b) {
285         return Arrays.equals(a, b);
286     }
287 
288     /**
289      * Compares the two given {@code char} values.
290      *
291      @param a first value to compare.
292      @param b second value to compare.
293      @return {@code true} if the given values are equal, {@code false}
294      *          otherwise.
295      */
296     public static boolean eq(final char a, final char b) {
297         return a == b;
298     }
299 
300     /**
301      * Compares the two given {@code char} arrays.
302      *
303      @param a first value to compare.
304      @param b second value to compare.
305      @return {@code true} if the given values are equal, {@code false}
306      *          otherwise.
307      */
308     public static boolean eq(final char[] a, final char[] b) {
309         return Arrays.equals(a, b);
310     }
311 
312     /**
313      * Compares the two given {@code short} values.
314      *
315      @param a first value to compare.
316      @param b second value to compare.
317      @return {@code true} if the given values are equal, {@code false}
318      *          otherwise.
319      */
320     public static boolean eq(final short a, final short b) {
321         return a == b;
322     }
323 
324     /**
325      * Compares the two given {@code short} arrays.
326      *
327      @param a first value to compare.
328      @param b second value to compare.
329      @return {@code true} if the given values are equal, {@code false}
330      *          otherwise.
331      */
332     public static boolean eq(final short[] a, final short[] b) {
333         return Arrays.equals(a, b);
334     }
335 
336     /**
337      * Compares the two given {@code int} values.
338      *
339      @param a first value to compare.
340      @param b second value to compare.
341      @return {@code true} if the given values are equal, {@code false}
342      *          otherwise.
343      */
344     public static boolean eq(final int a, final int b) {
345         return a == b;
346     }
347 
348     /**
349      * Compares the two given {@code int} arrays.
350      *
351      @param a first value to compare.
352      @param b second value to compare.
353      @return {@code true} if the given values are equal, {@code false}
354      *          otherwise.
355      */
356     public static boolean eq(final int[] a, final int[] b) {
357         return Arrays.equals(a, b);
358     }
359 
360     /**
361      * Compares the two given {@code long} values.
362      *
363      @param a first value to compare.
364      @param b second value to compare.
365      @return {@code true} if the given values are equal, {@code false}
366      *          otherwise.
367      */
368     public static boolean eq(final long a, final long b) {
369         return a == b;
370     }
371 
372     /**
373      * Compares the two given {@code long} arrays.
374      *
375      @param a first value to compare.
376      @param b second value to compare.
377      @return {@code true} if the given values are equal, {@code false}
378      *          otherwise.
379      */
380     public static boolean eq(final long[] a, final long[] b) {
381         return Arrays.equals(a, b);
382     }
383 
384     /**
385      * Compares the two given {@code float} values.
386      *
387      @param a first value to compare.
388      @param b second value to compare.
389      @return {@code true} if the given values are equal, {@code false}
390      *          otherwise.
391      */
392     public static boolean eq(final float a, final float b) {
393         return Float.floatToIntBits(a== Float.floatToIntBits(b);
394     }
395 
396     /**
397      * Compares the two given {@code float} arrays.
398      *
399      @param a first value to compare.
400      @param b second value to compare.
401      @return {@code true} if the given values are equal, {@code false}
402      *          otherwise.
403      */
404     public static boolean eq(final float[] a, final float[] b) {
405         return Arrays.equals(a, b);
406     }
407 
408     /**
409      * Compares the two given {@code double} values.
410      *
411      @param a first value to compare.
412      @param b second value to compare.
413      @return {@code true} if the given values are equal, {@code false}
414      *          otherwise.
415      */
416     public static boolean eq(final double a, final double b) {
417         return Double.doubleToLongBits(a== Double.doubleToLongBits(b);
418     }
419 
420     /**
421      * Compares the two given {@code double} arrays.
422      *
423      @param a first value to compare.
424      @param b second value to compare.
425      @return {@code true} if the given values are equal, {@code false}
426      *          otherwise.
427      */
428     public static boolean eq(final double[] a, final double[] b) {
429         return Arrays.equals(a, b);
430     }
431 
432     /**
433      * Compares the two given {@code Enum} values.
434      *
435      @param a first value to compare.
436      @param b second value to compare.
437      @return {@code true} if the given values are equal, {@code false}
438      *          otherwise.
439      */
440     public static boolean eq(final Enum<?> a, final Enum<?> b) {
441         return a == b;
442     }
443 
444     /**
445      * Compares the two given {@code Object} values.
446      *
447      @param a first value to compare.
448      @param b second value to compare.
449      @return {@code true} if the given values are equal, {@code false}
450      *          otherwise.
451      */
452     public static boolean eq(final Object a, final Object b) {
453         return (a != null ? a.equals(b: b == null);
454     }
455 
456     public static boolean eq(final Measurable<Duration> a, final Measurable<Duration> b) {
457         if (a == null && b == null) {
458             return true;
459         }
460         return a != null && b != null &&
461             a.longValue(SI.NANO(SI.SECOND)) == b.longValue(SI.NANO(SI.SECOND));
462     }
463 
464     /**
465      * Compares the two given {@code Object} arrays.
466      *
467      @param a first value to compare.
468      @param b second value to compare.
469      @return {@code true} if the given values are equal, {@code false}
470      *          otherwise.
471      */
472     public static boolean eq(final Object[] a, final Object[] b) {
473         return Arrays.equals(a, b);
474     }
475 
476     /**
477      * Compares the two given {@code Seq} values.
478      *
479      @param a first value to compare.
480      @param b second value to compare.
481      @return {@code true} if the given values are equal, {@code false}
482      *          otherwise.
483      */
484     public static boolean eq(final Seq<?> a, final Seq<?> b) {
485         return arrays.equals(a, b);
486     }
487 
488     /**
489      * Returns the result of calling toString for a non-null argument and "null"
490      * for a null argument.
491      *
492      @see Objects#toString(Object)
493      *
494      @param a the object.
495      @return the result of calling toString for a non-null argument and "null"
496      *          for a null argument
497      *
498      @deprecated Use {@link Objects#toString(Object)} instead.
499      */
500     @Deprecated
501     public static String str(final Object a) {
502         return Objects.toString(a);
503     }
504 
505     /**
506      * Print a binary representation of the given byte array. The printed string
507      * has the following format:
508      <pre>
509      *  Byte:       3        2        1        0
510      *              |        |        |        |
511      *  Array: "11110011|10011101|01000000|00101010"
512      *          |                 |        |      |
513      *  Bit:    23                15       7      0
514      </pre>
515      <i>Only the array string is printed.</i>
516      *
517      @param data the byte array to convert to a string.
518      @return the binary representation of the given byte array.
519      *
520      @deprecated Use {@link bit#toByteString(byte...)} instead.
521      */
522     @Deprecated
523     public static String str(final byte... data) {
524         return bit.toByteString(data);
525     }
526 
527 }