com.programix.util
Class ObjectTools

java.lang.Object
  com.programix.util.ObjectTools

public class ObjectTools
extends Object

Method Summary

static <T> T[]	changeArraySize(T[] src, int newLength) Returns a new array of the same type as the passed array but with the length of the new array set to newLength.
static <T> T[]	changeArraySize(T[] src, int newLength, T pad) Returns a new array of the same type as the passed array but with the length of the new array set to newLength.
static int	findMatch(Object lookFor, Object[] list) Returns the index into list where the first isSame(lookFor, list[i]) returns true.
static int	findMatch(Object lookFor, Object[] list, int offset) Returns the index into list where the first isSame(lookFor, list[i]) returns true—starting with offset.
static boolean	isAnySlotEmpty(Object[] obj) Returns true if the passed parameter is null, points to a zero-length array, or if any slot in that array contains null.
static boolean	isDifferent(Object a, Object b) Compares two references to see if they are "different".
static boolean	isDifferentArray(Object[] a, Object[] b) Compares two arrays to see if they are "different".
static boolean	isEmpty(Object[] obj) Returns true if array is either null or has a length of zero.
static boolean	isEverySlotEmpty(Object[] obj) Returns true if the passed parameter is null, points to a zero-length array, or if every slot in that array contains null.
static boolean	isNoSlotEmpty(Object[] obj) Returns true if the passed array does not have any "empty" (null) slots.
static boolean	isNotEmpty(Object[] obj) Returns true if array is not null and has a length greater than zero.
static boolean	isSame(Object a, Object b) Compares two references to see if they are "the same".
static boolean	isSameArray(Object[] a, Object[] b) Compares two arrays to see if they are "the same".
static Object	paramNullCheck(Object param) Used as a helper to check passed parameters for prohibited null values in other methods.
static Object	paramNullCheck(Object param, String paramName) Used as a helper to check passed parameters for prohibited null values in other methods.
static String	printArray(Object[] obj, String name) Returns a String with a dump of the contents of the specified array.
static Object[]	removeFromArray(Object[] src, Object item) Removes all occurrences of the specified item from the specified array.
static <T> T	typeCheck(Object value, Class<T> targetType) Checks that the passed value is not null and can be cast into the specified targetType.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isSame

public static boolean isSame(Object a,
                             Object b)

Compares two references to see if they are "the same". Returns true if a is the same as b. Specifically, they considered to be the same if any of the following are true:

• a == b (two references to the same object)
• ( a == null ) && ( b == null ) (both are null)
• ( a != null ) && ( b != null ) && ( a.equals(b) == true )

Parameters:

a - the first Object

b - the second Object

Returns:

true if the objects are the same.

See Also:

isDifferent(Object, Object)

isDifferent

public static boolean isDifferent(Object a,
                                  Object b)

Compares two references to see if they are "different". Returns true if a is different than b. Specifically, they considered to be different if any of the following are true:

• ( a == null ) && ( b != null )
• ( a != null ) && ( b == null )
• ( a != null ) && ( b != null ) && ( a.equals(b) == false )

Parameters:

a - the first Object

b - the second Object

Returns:

true if the objects are different.

See Also:

isSame(Object, Object)

isSameArray

public static boolean isSameArray(Object[] a,
                                  Object[] b)

Compares two arrays to see if they are "the same". Returns true if a is the same as b. Specifically, they considered to be the same if any of the following are true:

• a == b (two references to the same object)
• ( a == null ) && ( b == null ) (both are null)
• ( a != null ) && ( b != null ) && ( a.length == b.length ) && ("each element isSame"

Parameters:

a - the first array

b - the second array

Returns:

true if the arrays are the same.

See Also:

isDifferentArray(Object[], Object[])

isDifferentArray

public static boolean isDifferentArray(Object[] a,
                                       Object[] b)

Compares two arrays to see if they are "different". See isSameArray(Object[], Object[]) to see what is considered to be "the same", and this method returns the opposite.

isEmpty

public static boolean isEmpty(Object[] obj)

Returns true if array is either null or has a length of zero.

isNotEmpty

public static boolean isNotEmpty(Object[] obj)

Returns true if array is not null and has a length greater than zero.

isEverySlotEmpty

public static boolean isEverySlotEmpty(Object[] obj)

Returns true if the passed parameter is null, points to a zero-length array, or if every slot in that array contains null.

isAnySlotEmpty

public static boolean isAnySlotEmpty(Object[] obj)

Returns true if the passed parameter is null, points to a zero-length array, or if any slot in that array contains null.

isNoSlotEmpty

public static boolean isNoSlotEmpty(Object[] obj)

Returns true if the passed array does not have any "empty" (null) slots. If a zero-length array is passed in, then this method also returns true as none of the zero slots are empty. If null is passed in, then false is returned.

changeArraySize

public static <T> T[] changeArraySize(T[] src,
                                      int newLength,
                                      T pad)
                           throws IllegalArgumentException

Returns a new array of the same type as the passed array but with the length of the new array set to newLength. If newLength is smaller than the current length, then a new array is returned as a truncated version or src. If newLength is larger than the current length, then a new array is returned with the contents of src followed by the specified pad in the remaining slots. If newLength is same as the current length, then a clone of src is returned.

Parameters:

src - array to copy from and to sense the type from, must not be null (but it is OK if it has a zero-length).

newLength - the length of the returned array.

pad - if needed, this reference is copied into the additional slots.

Returns:

a new array with the element type of src and a length of newLength.

Throws:

IllegalArgumentException - if src is null or if newLength is negative.

changeArraySize

public static <T> T[] changeArraySize(T[] src,
                                      int newLength)
                           throws IllegalArgumentException

Returns a new array of the same type as the passed array but with the length of the new array set to newLength. If newLength is smaller than the current length, then a new array is returned as a truncated version or src. If newLength is larger than the current length, then a new array is returned with the contents of src followed by null in the remaining slots. If newLength is same as the current length, then a clone of src is returned.

Parameters:

src - array to copy from and to sense the type from, must not be null (but it is OK if it has a zero-length).

newLength - the length of the returned array.

Returns:

a new array with the element type of src and a length of newLength.

Throws:

IllegalArgumentException - if src is null or if newLength is negative.

removeFromArray

public static Object[] removeFromArray(Object[] src,
                                       Object item)
                                throws IllegalArgumentException

Removes all occurrences of the specified item from the specified array. Matching is done via the equals method (however, if item is null then all null slots are removed from the array). If there are no matches, then the original array is returned (note: not a clone!). If there are any matches, then a new, smaller array is returned.

Parameters:

src - array to copy from and to sense the type from, must not be null (but it is OK if it has a zero-length). This array is never modified by this method.

item - the one to match for removal. If null then all null slots in the array are removed.

Returns:

an array with all occurrences of item removed. If no matches were found, then src is simply returned. If any matches were found, then a new, smaller array of the same type as src is returned.

Throws:

IllegalArgumentException - if src is null.

findMatch

public static int findMatch(Object lookFor,
                            Object[] list,
                            int offset)

Returns the index into list where the first isSame(lookFor, list[i]) returns true—starting with offset. Returns -1 if no match is found from the specified offset to the end of the array. The list passed in does not need to be sorted as the search is sequential starting at offset.

findMatch

public static int findMatch(Object lookFor,
                            Object[] list)

Returns the index into list where the first isSame(lookFor, list[i]) returns true. Returns -1 if not found. The list passed in does not need to be sorted as the search is sequential from the beginning.

printArray

public static String printArray(Object[] obj,
                                String name)

Returns a String with a dump of the contents of the specified array. The output uses the passed name when referring to the array. The toString() method is used on each element in the array; if any element is null, then the word null is appended instead.

Parameters:

obj - the array for format. OK to pass null and OK to pass a zero-length array (there will be some output).

name - the name of the array to use in the output.

Returns:

a String with the formatted array contents.

paramNullCheck

public static Object paramNullCheck(Object param,
                                    String paramName)
                             throws IllegalArgumentException

Used as a helper to check passed parameters for prohibited null values in other methods. If param is not null, then param is simply and quietly returned from this method.

Parameters:

param - the parameter value to check.

paramName - the optional name of the parameter being checked. If present, paramName is used to enhance the text of the exception.

Returns:

the passed param if param is not null.

Throws:

IllegalArgumentException - if param is null.

paramNullCheck

public static Object paramNullCheck(Object param)
                             throws IllegalArgumentException

Used as a helper to check passed parameters for prohibited null values in other methods. If param is not null, then param is simply and quietly returned from this method.

Parameters:

param - the parameter value to check.

Returns:

the passed param if param is not null.

Throws:

IllegalArgumentException - if param is null.

typeCheck

public static <T> T typeCheck(Object value,
                              Class<T> targetType)
                   throws ClassCastException

Checks that the passed value is not null and can be cast into the specified targetType.

Parameters:

value - the value to check

targetType - the type be check against. If null, then the type Object is assumed.

Returns:

the passed value for method chaining convenience.

Throws:

ClassCastException - if the passed value is null or if it can't be cast into the specified targetType.