orbital.util
Class Utility

java.lang.Object
  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()