Orbital library

orbital.util
Class Utility

java.lang.Object
  extended by orbital.util.Utility

public final class Utility
extends java.lang.Object

A general Utility class containing static methods for common tasks like assertion checking etc.

Author:
André Platzer
See Also:
MathUtilities, Setops, UIUtilities, ClassicalLogic.Utilities
Stereotype:
Utilities

Field Summary
static BinaryPredicate instanceOf
          Predicate for x instanceof y.
 
Method Summary
static java.util.Collection asCollection(java.lang.Object o)
          Get a collection view of the object o.
static java.util.Iterator asIterator(java.lang.Object a)
          Get an iterator view of a generalized iteratable object, if possible.
static int compare(java.lang.Object a, java.lang.Object b)
          Compares its two arguments for order.
static boolean containsIdenticalTo(java.lang.Object[] a, java.lang.Object x)
          Check whether an array contains an object that is identical to x.
static int[] dimensions(java.lang.Object a)
          Get the dimensions of a multi-dimensional array.
static int[] dimensions(java.lang.Object[] a)
           
static boolean equals(java.lang.Object a, java.lang.Object b)
          Check whether two objects are equal.
static boolean equalsAll(java.lang.Object a, java.lang.Object b)
          Check whether two objects are equal (and their array components, as well).
static boolean flip(java.util.Random r, double probability)
          Flips to true with a given probability.
static boolean forallMembers(java.lang.Object o, Predicate pred)
          Applies a Predicate to all member fields of an object, as long as the predicate returns true.
static boolean forallPublicMembers(java.lang.Object o, Predicate pred)
          Applies a Predicate to all public member fields of an object, as long as the predicate returns true.
static java.lang.String format(java.lang.String delimiter, java.lang.Object iteratable)
          Format a generalized iteratable inserting delimiters between the individual elements.
static java.lang.Object getPart(java.lang.Object[] a, int[] partSpecification)
           
static java.lang.Object getPart(java.lang.Object a, int[] partSpecification)
          Get the element in the (possibly multi-dimensional) array a specified by the part specification.
static int hashCode(java.lang.Object a)
          Get the hashCode of an object.
static int hashCodeAll(java.lang.Object o)
          Get the hashCode of an object (considering all its array components, as well).
static int hashCodeArray(java.lang.Object[] a)
          Get the hashCode of a one-dimensional array.
static int hashCodeSet(java.lang.Object o)
          Get the hashCode of an object (considering all its array components, as sets, as well).
static boolean isIteratable(java.lang.Object a)
          Checks whether the given object is generalized iteratable.
static int matchingBrace(java.lang.String text, int pos)
          Utility returning the index of the brace matching the brace at pos in text.
static java.lang.Object newIteratableLike(java.lang.Object a)
          Get a new instance of generalized iteratable object of the same type as the one specified.
static void pre(boolean test, java.lang.String description)
          Call to make a precondition assertion.
static int rank(java.lang.Object a)
          Get the number of indices required to reach the component type.
static int rank(java.lang.Object[] a)
           
static java.lang.String readLine(java.io.InputStream is)
          Read a line from an InputStream in human-readable-form as a String.
static java.lang.String readLine(java.io.Reader rd)
          Read a line from an InputStream in human-readable-form as a String.
static void setPart(java.lang.Object[] a, int[] partSpecification, java.lang.Object value)
           
static void setPart(java.lang.Object a, int[] partSpecification, java.lang.Object value)
          Set the element in the (possibly multi-dimensional) array a specified by the part specification.
static boolean sorted(double[] a, boolean asc)
          Checks whether an array is sorted.
static boolean sorted(java.util.List a, java.util.Comparator cmp)
          Checks whether a list is sorted.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

instanceOf

public static final BinaryPredicate instanceOf
Predicate for x instanceof y.

See Also:
Class.isInstance(Object)
Method Detail

pre

public static void pre(boolean test,
                       java.lang.String description)
Call to make a precondition assertion.

Can be used to check parameter restrictions of a method. It will throw an IllegalArgumentException for invalid arguments.

 Utility.pre(0<=x && x<=maximum_size, "numbers in range");
 // can be used instead of
 if (x<0 || x>maximum_size)
     throw new IllegalArgumentException("number should not exceed range");
 

Note that per general contract of argument checking in Java this assertion will be performed even if all other assertion checks are set to be skipped.

Parameters:
test - assertion predicate expression. If this logical expression evaluates to true, the assertion passes. If it evaluates to false, the assertion fails.
description - specifies additional information for the assertion that will appear in an exception.
Throws:
java.lang.IllegalArgumentException - if test evaluates to false.
Preconditions:
test
Postconditions:
test

containsIdenticalTo

public static final boolean containsIdenticalTo(java.lang.Object[] a,
                                                java.lang.Object x)
Check whether an array contains an object that is identical to x.

Returns:
true iff. ∃i∈{0,..,a.length} a[i] == x.

equals

public static final boolean equals(java.lang.Object a,
                                   java.lang.Object b)
Check whether two objects are equal.

This method is just a shortcut to simplify assertion statements.

Returns:
an optimized version of a == null ? b == null : a.equals(b). Namely a == b || (a != null && a.equals(b)).
See Also:
hashCode(Object)
Preconditions:
a == b → a.equals(b)
Postconditions:
a == b || (a != null && a.equals(b))

equalsAll

public static final boolean equalsAll(java.lang.Object a,
                                      java.lang.Object b)
Check whether two objects are equal (and their array components, as well).

Returns:
whether a and b are equal. Or if a and b are both arrays, whether they are equal element-wise, i.e. all their elements are equal.
See Also:
hashCodeAll(Object)
Preconditions:
a == b → a.equals(b)
Postconditions:
?

hashCode

public static final int hashCode(java.lang.Object a)
Get the hashCode of an object.

This method is just a shortcut to simplify assertion statements.

Returns:
an optimized version of a == null ? 0 : a.hashCode().
See Also:
equals(Object, Object)

compare

public static final int compare(java.lang.Object a,
                                java.lang.Object b)
Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

Compares two objects with null being the smallest object. Contrary to the specified NullPointerException behaviour f Comparable.compareTo(Object)!

See Also:
equals(Object, Object)

hashCodeAll

public static final int hashCodeAll(java.lang.Object o)
Get the hashCode of an object (considering all its array components, as well). Contrary to hashCodeSet(Object), the order of elements plays a role.

Parameters:
o - the object whose hashCode to calculate.
Returns:
the hashCode of o, or all its elements if o is a (multi-dimensional) array.
See Also:
equalsAll(Object, Object), Arrays.equals(Object[], Object[]), Functionals.foldRight(orbital.logic.functor.BinaryFunction, Object, Object[])
Note:
this implementation does not necessarily fit to the hashCode defined by List, nor, of course, Set.

hashCodeArray

public static final int hashCodeArray(java.lang.Object[] a)
Get the hashCode of a one-dimensional array. Contrary to hashCodeAll(Object), does not descend recursively.

Parameters:
a - the object whose hashCode to calculate.
Returns:
the hashCode of all elements of a.

hashCodeSet

public static final int hashCodeSet(java.lang.Object o)
Get the hashCode of an object (considering all its array components, as sets, as well). Contrary to hashCodeAll(Object), the order of elements plays no role.

Parameters:
o - the object whose hashCode to calculate.
Returns:
the hashCode of o, or all its elements if o is a (multi-dimensional) array.
See Also:
equalsAll(Object, Object), Arrays.equals(Object[], Object[]), Functionals.foldRight(orbital.logic.functor.BinaryFunction, Object, Object[])
Note:
this implementation does not necessarily fit to the hashCode defined by Set, nor, of cours,e List.

sorted

public static final boolean sorted(double[] a,
                                   boolean asc)
Checks whether an array is sorted.

Parameters:
a - the array to be checked.
asc - whether to check for ascending order (true), or descending order (false).
Returns:
whether a is sorted.

sorted

public static final boolean sorted(java.util.List a,
                                   java.util.Comparator cmp)
Checks whether a list is sorted.

Parameters:
a - the list to be checked.
cmp - the comparator used (for ascending order). If null, natural order is used (by using Comparable).
Returns:
whether a is sorted.
See Also:
ReverseComparator

rank

public static final int rank(java.lang.Object[] a)
See Also:
rank(Object)

rank

public static final int rank(java.lang.Object a)
Get the number of indices required to reach the component type.

Postconditions:
RES == dimensions(a).length
Note:
does not check rectangularity of a

dimensions

public static final int[] dimensions(java.lang.Object[] a)
See Also:
dimensions(Object)

dimensions

public static final int[] dimensions(java.lang.Object a)
Get the dimensions of a multi-dimensional array.

Note:
does not check rectangularity of a

getPart

public static java.lang.Object getPart(java.lang.Object[] a,
                                       int[] partSpecification)
See Also:
getPart(Object,int[])

getPart

public static java.lang.Object getPart(java.lang.Object a,
                                       int[] partSpecification)
Get the element in the (possibly multi-dimensional) array a specified by the part specification. Contrary to getPart(Object[],int[]), also accepts primitive type arrays.

Parameters:
partSpecification - the part specification p (multi-index into the multi-dimensional array a).
Returns:
a[p[0]][p[1]]...[p[p.length-1]]
Preconditions:
partSpecification.length is not lower than the number of dimensions for partialSolutions.

setPart

public static void setPart(java.lang.Object[] a,
                           int[] partSpecification,
                           java.lang.Object value)
See Also:
setPart(Object[],int[],Object)

setPart

public static void setPart(java.lang.Object a,
                           int[] partSpecification,
                           java.lang.Object value)
Set the element in the (possibly multi-dimensional) array a specified by the part specification. Contrary to setPart(Object[],int[],Object), also accepts primitive type arrays. Sets a[p[0]][p[1]]...[p[p.length-1]] := value.

Parameters:
partSpecification - the part specification p (multi-index into the multi-dimensional array a).
Preconditions:
partSpecification.length is not lower than the number of dimensions for partialSolutions.

flip

public static boolean flip(java.util.Random r,
                           double probability)
Flips to true with a given probability. Works like flipping coins.

Parameters:
probability - the probabilty ranging from 0 to 1 with that flip returns true.
Returns:
true with a given probability (nondeterministic).
See Also:
Random.nextDouble()
Preconditions:
probability is a probability

matchingBrace

public static int matchingBrace(java.lang.String text,
                                int pos)
Utility returning the index of the brace matching the brace at pos in text. f.ex. (a(b)c)


forallPublicMembers

public static boolean forallPublicMembers(java.lang.Object o,
                                          Predicate pred)
                                   throws java.lang.IllegalAccessException
Applies a Predicate to all public member fields of an object, as long as the predicate returns true.

Parameters:
o - the object whose member public fields are desired.
pred - the predicate to be applied for every public member field.
Returns:
whether the predicate was true for all public member fields.
Throws:
java.lang.IllegalAccessException

forallMembers

public static boolean forallMembers(java.lang.Object o,
                                    Predicate pred)
                             throws java.lang.IllegalAccessException
Applies a Predicate to all member fields of an object, as long as the predicate returns true. Will loop over all superclasses declared fields. This method requires a java.lang.reflect.ReflectPermission of suppressAccessChecks to work for all superclasses.

Parameters:
o - the object whose member fields are desired.
pred - the predicate to be applied for every member field.
Returns:
whether the predicate was true for all member fields.
Throws:
java.lang.SecurityException - if the java.lang.reflect.ReflectPermission of suppressAccessChecks is not permitted.
java.lang.IllegalAccessException

asCollection

public static java.util.Collection asCollection(java.lang.Object o)
Get a collection view of the object o.

Returns:
a list of the elements of o, if o is an array, o, if o is a collection, a list containing o, otherwise.
See Also:
asIterator(Object)
Postconditions:
RES == null <=> o == null

isIteratable

public static boolean isIteratable(java.lang.Object a)
Checks whether the given object is generalized iteratable.

Generalized iteratable objects are objects that somehow support iteration of their components, like Iterator, Collection, Object[], or Tensor (including Vector, and Matrix), as well as (even multi-dimensional) primitive type arrays. Multi-dimensional arrays of primitive or structured component type are iterated over component-wise. Although the order will usually be row-wise, this is not a strict requirement.

Unfortunately, these classes do not implement a common interface "Iteratable", or "Iterable", or "Enumerable" so we must rely on implicit interfaces. Additionally, some iteratable classes may support ListIterators others Iterators, so covariant return-types would be required for defining such a common interface in a convenient way that avoids casting.


asIterator

public static java.util.Iterator asIterator(java.lang.Object a)
                                     throws NotIteratableException
Get an iterator view of a generalized iteratable object, if possible.

Returns:
an iterator or list iterator view of a, whenever possible.
Throws:
NotIteratableException - if a is not generalized iteratable.
See Also:
isIteratable(Object), asCollection(Object), newIteratableLike(Object)
Postconditions:
RES == null <=> o == null

newIteratableLike

public static java.lang.Object newIteratableLike(java.lang.Object a)
                                          throws NotIteratableException
Get a new instance of generalized iteratable object of the same type as the one specified.

Throws:
NotIteratableException - if a is not generalized iteratable.
See Also:
isIteratable(Object), Setops.newCollectionLike(Collection)
Postconditions:
RES == null <=> a == null

format

public static final java.lang.String format(java.lang.String delimiter,
                                            java.lang.Object iteratable)
Format a generalized iteratable inserting delimiters between the individual elements.

Parameters:
delimiter - the delimiter string to insert between successive elements of iteratable.
Returns:
iteratable[0] delimiter iteratable[1] delimiter iteratable[n]
Throws:
NotIteratableException - if a is not generalized iteratable.

readLine

public static java.lang.String readLine(java.io.InputStream is)
                                 throws java.io.IOException
Read a line from an InputStream in human-readable-form as a String. Reading stops at LF ('\n') or EOF and skips CR ('\r').

Returns:
the line read or null if no single character could be read.
Throws:
java.io.IOException
See Also:
readLine(java.io.InputStream)

readLine

public static java.lang.String readLine(java.io.Reader rd)
                                 throws java.io.IOException
Read a line from an InputStream in human-readable-form as a String. Reading stops at LF ('\n') or EOF and skips CR ('\r').

Prefer using

 BufferedReader rd = new BufferedReader(inner_reader);
 // forget about using the inner reader since rd is buffered!
 inner_reader = null;
 String l = rd.readLine();
 
whenever possible.

Returns:
the line read or null if no single character could be read.
Throws:
java.io.IOException
See Also:
BufferedReader.readLine()

Orbital library
1.3.0: 11 Apr 2009

Copyright © 1996-2009 André Platzer
All Rights Reserved.