object.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-1.5.0).
003  * Copyright (c) 2007-2013 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 /**
029  * Some helper methods for creating hash codes and comparing values.
030  *
031  @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
032  @since 1.0
033  @version 1.3 &mdash; <em>$Date: 2013-09-06 $</em>
034  */
035 public final class object extends StaticObject {
036     private object() {}
037 
038 
039     /**
040      * A range checking predicate which can be used to check whether the elements
041      * of an array are within an given range. If not, an
042      {@link IllegalArgumentException} is thrown. If one value is {@code null},
043      * an {@link NullPointerException} is thrown.
044      <p/>
045      *
046      * The following code will throw an {@link IllegalArgumentException} if the
047      * integers in the array are smaller than zero and greater than 9.
048      * [code]
049      * final Array<Integer> array = ...
050      * arrays.forEach(CheckRange<(0, 10));
051      * [/code]
052      */
053     public static final <C extends Comparable<? super C>> Function<C, Boolean>
054     CheckRange(final C min, final C max)
055     {
056         return new Function<C,Boolean>() {
057             @Override
058             public Boolean apply(final C value) {
059                 requireNonNull(value);
060                 if (value.compareTo(min|| value.compareTo(max>= 0) {
061                     throw new IllegalArgumentException(format(
062                         "Given value %s is out of range [%s, %s)",
063                         value, min, max
064                     ));
065                 }
066                 return Boolean.TRUE;
067             }
068         };
069     }
070 
071 
072     /**
073      * Verifies {@link Verifiable} array elements. All elements are valid if the
074      * condition
075      * [code]
076      * arrays.forAll(Verify) == true
077      * [/code]
078      * is true.
079      */
080     public static final Function<Verifiable, Boolean>
081     Verify = new Function<Verifiable,Boolean>() {
082         @Override
083         public Boolean apply(final Verifiable object) {
084             return object.isValid() ? Boolean.TRUE : Boolean.FALSE;
085         }
086     };
087 
088     /**
089      * A {@code null} checking predicate which can be used to check an array
090      * for null values. The following code will throw an
091      {@link NullPointerException} if one of the array elements is {@code null}.
092      *
093      * [code]
094      * final Array<String> array = ...
095      * array.forEach(NonNull("Object"));
096      * ...
097      * final String[] array = ...
098      * arrays.forEach(array, NonNull);
099      * [/code]
100      */
101     public static final Function<Object, Boolean> NonNull = NonNull("Object");
102 
103     /**
104      * A {@code null} checking predicate which can be used to check an array
105      * for null values. The following code will throw an
106      {@link NullPointerException} if one of the array elements is {@code null}.
107      *
108      * [code]
109      * final Array<String> array = ...
110      * array.forEach(NonNull("Object"));
111      * ...
112      * final String[] array = ...
113      * arrays.forEach(array, NonNull);
114      * [/code]
115      */
116     public static final Function<Object, Boolean> NonNull(final String message) {
117         return new Function<Object,Boolean>() {
118             @Override public Boolean apply(final Object object) {
119                 requireNonNull(object, message );
120                 return Boolean.TRUE;
121             }
122         };
123     }
124 
125     /**
126      * Checks that the specified object reference is not {@code null}.
127      *
128      @param obj the object to check.
129      @param message the error message.
130      @return {@code obj} if not {@code null}.
131      @throws NullPointerException if {@code obj} is {@code null}.
132      *
133      @deprecated Use {@link java.util.Objects#requireNonNull(Object, String)}
134      *             instead.
135      */
136     @Deprecated
137     public static <T> T nonNull(final T obj, final String message) {
138         if (obj == null) {
139             throw new NullPointerException(message + " must not be null.");
140         }
141         return obj;
142     }
143 
144     /**
145      * Checks that the specified object reference is not {@code null}.
146      *
147      @param obj the object to check.
148      @return {@code obj} if not {@code null}.
149      @throws NullPointerException if {@code obj} is {@code null}.
150      *
151      @deprecated Use {@link java.util.Objects#requireNonNull(Object)} instead.
152      */
153     @Deprecated
154     public static <T> T nonNull(final T obj) {
155         return nonNull(obj, "Object");
156     }
157 
158     /**
159      * Check if the specified value is not negative.
160      *
161      @param value the value to check.
162      @param message the exception message.
163      @return the given value.
164      @throws IllegalArgumentException if {@code value < 0}.
165      */
166     public static double nonNegative(final double value, final String message) {
167         if (value < 0) {
168             throw new IllegalArgumentException(format(
169                     "%s must not negative: %f.", message, value
170                 ));
171         }
172         return value;
173     }
174 
175     /**
176      * Check if the specified value is not negative.
177      *
178      @param value the value to check.
179      @return the given value.
180      @throws IllegalArgumentException if {@code value < 0}.
181      */
182     public static double nonNegative(final double value) {
183         return nonNegative(value, "Value");
184     }
185 
186     /**
187      * Check if the given integer is negative.
188      *
189      @param length the value to check.
190      @throws NegativeArraySizeException if the given {@code length} is smaller
191      *           than zero.
192      */
193     public static int nonNegative(final int length) {
194         if (length < 0) {
195             throw new NegativeArraySizeException(
196                 "Length must be greater than zero, but was " + length + ". "
197             );
198         }
199         return length;
200     }
201 
202     /**
203      * Check if the given double value is within the closed range {@code [0, 1]}.
204      *
205      @param p the probability to check.
206      @return p if it is a valid probability.
207      @throws IllegalArgumentException if {@code p} is not a valid probability.
208      */
209     public static double checkProbability(final double p) {
210         if (p < 0.0 || p > 1.0) {
211             throw new IllegalArgumentException(format(
212                 "The given probability is not in the range [0, 1]: %f", p
213             ));
214         }
215         return p;
216     }
217 
218     /**
219      * Create a HashCodeBuilder for the given type.
220      *
221      @param type the type the HashCodebuilder is created for.
222      @return a new HashCodeBuilder.
223      */
224     public static HashCodeBuilder hashCodeOf(final Class<?> type) {
225         return new DefaultHashCodeBuilder(type);
226     }
227 
228     /**
229      * Compares the two given {@code boolean} values.
230      *
231      @param a first value to compare.
232      @param b second value to compare.
233      @return {@code true} if the given values are equal, {@code false}
234      *          otherwise.
235      */
236     public static boolean eq(final boolean a, final boolean b) {
237         return a == b;
238     }
239 
240     /**
241      * Compares the two given {@code boolean} arrays.
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 Arrays.equals(a, b);
250     }
251 
252     /**
253      * Compares the two given {@code byte} values.
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 byte a, final byte b) {
261         return a == b;
262     }
263 
264     /**
265      * Compares the two given {@code byte} arrays.
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 Arrays.equals(a, b);
274     }
275 
276     /**
277      * Compares the two given {@code char} values.
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 char a, final char b) {
285         return a == b;
286     }
287 
288     /**
289      * Compares the two given {@code char} arrays.
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 Arrays.equals(a, b);
298     }
299 
300     /**
301      * Compares the two given {@code short} values.
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 short a, final short b) {
309         return a == b;
310     }
311 
312     /**
313      * Compares the two given {@code short} arrays.
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 Arrays.equals(a, b);
322     }
323 
324     /**
325      * Compares the two given {@code int} values.
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 int a, final int b) {
333         return a == b;
334     }
335 
336     /**
337      * Compares the two given {@code int} arrays.
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 Arrays.equals(a, b);
346     }
347 
348     /**
349      * Compares the two given {@code long} values.
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 long a, final long b) {
357         return a == b;
358     }
359 
360     /**
361      * Compares the two given {@code long} arrays.
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 Arrays.equals(a, b);
370     }
371 
372     /**
373      * Compares the two given {@code float} values.
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 float a, final float b) {
381         return Float.floatToIntBits(a== Float.floatToIntBits(b);
382     }
383 
384     /**
385      * Compares the two given {@code float} arrays.
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 Arrays.equals(a, b);
394     }
395 
396     /**
397      * Compares the two given {@code double} values.
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 double a, final double b) {
405         return Double.doubleToLongBits(a== Double.doubleToLongBits(b);
406     }
407 
408     /**
409      * Compares the two given {@code double} arrays.
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 Arrays.equals(a, b);
418     }
419 
420     /**
421      * Compares the two given {@code Enum} values.
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 Enum<?> a, final Enum<?> b) {
429         return a == b;
430     }
431 
432     /**
433      * Compares the two given {@code Object} 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 Object a, final Object b) {
441         return (a != null ? a.equals(b: b == null);
442     }
443 
444     /**
445      * Compares the two given {@code Object} arrays.
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 Arrays.equals(a, b);
454     }
455 
456     /**
457      * Compares the two given {@code Seq} values.
458      *
459      @param a first value to compare.
460      @param b second value to compare.
461      @return {@code true} if the given values are equal, {@code false}
462      *          otherwise.
463      */
464     public static boolean eq(final Seq<?> a, final Seq<?> b) {
465         return arrays.equals(a, b);
466     }
467 
468     /**
469      * Returns the result of calling toString for a non-null argument and "null"
470      * for a null argument.
471      *
472      @see Objects#toString(Object)
473      *
474      @param a the object.
475      @return the result of calling toString for a non-null argument and "null"
476      *          for a null argument
477      *
478      @deprecated Use {@link Objects#toString(Object)} instead.
479      */
480     @Deprecated
481     public static String str(final Object a) {
482         return Objects.toString(a);
483     }
484 
485     /**
486      * Print a binary representation of the given byte array. The printed string
487      * has the following format:
488      <pre>
489      *  Byte:       3        2        1        0
490      *              |        |        |        |
491      *  Array: "11110011|10011101|01000000|00101010"
492      *          |                 |        |      |
493      *  Bit:    23                15       7      0
494      </pre>
495      <i>Only the array string is printed.</i>
496      *
497      @param data the byte array to convert to a string.
498      @return the binary representation of the given byte array.
499      *
500      @deprecated Use {@link bit#toByteString(byte...)} instead.
501      */
502     @Deprecated
503     public static String str(final byte... data) {
504         return bit.toByteString(data);
505     }
506 
507 }
508