xbn.array
Class UtilArray

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.array.UtilArray

public class UtilArray

extends XBNObject

Random functions to create, manipulate and analyze arrays.

Source code: UtilArray.java. Unit tests: xbn_junit.array.JUTUtilArray.java.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

UtilArray()
Create a UtilArray.

Method Summary

void	appendTSList(StringOrBuffer str_orBfr, Object[] a_object, String s_prefix, String s_divider, String s_postfix, String s_ifNull, String s_ifEmpty, String s_ifLmntNull) Append the list of toStrings for an array of objects onto the provided StringOrBuffer.
boolean[]	getAOBClone(boolean[] a_boolean) Get a full (deep) copy of the provided boolean array.
char[]	getAOCClone(char[] a_char) Get a full (deep) copy of the provided char array.
int[]	getAOIClone(int[] a_int) Get a full (deep) copy of the provided int array.
Object[]	getAOOShallowClone(Object[] a_object) Get a shallow clone of the provided object array.
AOSLookup	getAOSLFromAOS(String[] a_string) Create an AOSLookup from the string array.
AOSLookup	getAOSLFromAOS(String[] a_string, boolean b_listUnqStrs) Create an AOSLookup from the string array.
AOSLookup	getAOSLFromPA(PrimitiveArray primitive_array) Create an AOSLookup from the PrimitiveArray.
AOSLookup	getAOSLFromPA(PrimitiveArray primitive_array, boolean b_listUnqStrs) Create an AOSLookup from the PrimitiveArray.
String[]	getAOSShallowClone(String[] a_string) Get a shallow clone of the provided string array.
int	getMiddleIdx(int i_idxLeft, int i_idxRight) Get the array index in the center of the provided indexes.
int	getMiddleIdx(int i_idxLeft, int i_idxRight, boolean b_roundLowHigh) Get the array index in the center of the provided indexes.

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

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

Constructor Detail

UtilArray

public UtilArray()

Create a UtilArray. This constructor does nothing.

Method Detail

getMiddleIdx

public int getMiddleIdx(int i_idxLeft,
                        int i_idxRight)

Get the array index in the center of the provided indexes.

Returns:

getMiddleIdx(i_idxLeft, i_idxRight, true)

getMiddleIdx

public int getMiddleIdx(int i_idxLeft,
                        int i_idxRight,
                        boolean b_roundLowHigh)

Get the array index in the center of the provided indexes. This is useful when doing a binary search (see BinarySearchData).

Parameters:

i_idxLeft - The left-most (starting) index bound.

i_idxRight - The right-most (ending) index bound. This is an inclusive bound (meaning this index is truly the right-most index search, and not the index after it).

b_roundLowHigh - If true, then the returned value will be rounded down (this is the default behavior of int division, and is therefore more efficient). If false, the returned value is rounded up.

Returns:

-1 If i_idxRight - i_idxLeft is less than zero.
i_idxLeft If i_idxRight - i_idxLeft is equal to zero.
((i_idxLeft / i_idxRight) + i_idxLeft) If otherwise. Rounding is taken care of, depending on the value of b_roundLowHigh..

getAOSShallowClone

public final String[] getAOSShallowClone(String[] a_string)

Get a shallow clone of the provided string array.

Is there any difference between "shallow" and "deep" when it comes to string arrays? My guess is, yes, there is. A deep copy would create new string elements (new String("bla")), where the shallow clone is smart enough to reference the same string objects.

Returns:

An array that is a clone of a_string, where the array is a copy, but the elements pointed to are the same as in a_string.

getAOOShallowClone

public final Object[] getAOOShallowClone(Object[] a_object)

Get a shallow clone of the provided object array.

Returns:

An array that is a clone of a_object, where the array is a copy, but the elements pointed to are the same as in a_object.

getAOBClone

public final boolean[] getAOBClone(boolean[] a_boolean)

Get a full (deep) copy of the provided boolean array.

Returns:

An array that is a full (deep) copy of a_boolean.

getAOCClone

public final char[] getAOCClone(char[] a_char)

Get a full (deep) copy of the provided char array.

Returns:

An array that is a full (deep) copy of a_char.

getAOIClone

public final int[] getAOIClone(int[] a_int)

Get a full (deep) copy of the provided int array.

Returns:

An array that is a full (deep) copy of a_int.

getAOSLFromAOS

public final AOSLookup getAOSLFromAOS(String[] a_string)

Create an AOSLookup from the string array.

Returns:

getAOSLFromAOS(a_string, true)

getAOSLFromAOS

public final AOSLookup getAOSLFromAOS(String[] a_string,
                                      boolean b_listUnqStrs)

Create an AOSLookup from the string array.

Returns:

getAOSLFromPA((new PASString(a_string)), b_listUnqStrs)

getAOSLFromPA

public final AOSLookup getAOSLFromPA(PrimitiveArray primitive_array)

Create an AOSLookup from the PrimitiveArray.

Returns:

getAOSLFromPA(primitive_array, true)

getAOSLFromPA

public final AOSLookup getAOSLFromPA(PrimitiveArray primitive_array,
                                     boolean b_listUnqStrs)

Create an AOSLookup from the PrimitiveArray.

Parameters:

primitive_array - The PrimitiveArray. May not be null, primitive_array.isNull must be false and primitive_array.getLength may not be zero.

Returns:

If primitive_array.wasValidated() equals true and primitive_array.getPrimitiveArrayRule().getPARDupNullLen().areDupsOk() equals false, then the AOSLCreator is created with the following constructor parameters: (false, primitive_array.getLength(), b_listUnqStrs). If either of these two conditions are not met, then the AOSLCreator is created with the constructor parameters: (true, b_listUnqStrs). The former's internal Hashtable is optimized from the start. The latter recreates (optimizes) the Hashtable after all strings have been added.

appendTSList

public final void appendTSList(StringOrBuffer str_orBfr,
                               Object[] a_object,
                               String s_prefix,
                               String s_divider,
                               String s_postfix,
                               String s_ifNull,
                               String s_ifEmpty,
                               String s_ifLmntNull)

Append the list of toStrings for an array of objects onto the provided StringOrBuffer.

Parameters:

str_orBfr - The StringOrBuffer to append to. May not be null.

a_object - The array of objects to generate toStrings on.

s_prefix - The prefix to append before the toString list, only if a_object is non-null and at least one element in length. If null, then nothing is put before the list (meaning null is the same empty string [''], only faster). If non-null, then this is concatenated to str_orBfr before the toString list.

s_divider - The text to put between each element's toString.

s_postfix - Same as s_prefix, except this is put at the end, after the toString list.

s_ifNull - If a_object is null, then this is the (only) string appended onto str_orBfr. All other string parameters are ignored when a_object is null.

s_ifEmpty - If a_object has zero elements, then this is the (only) string appended onto str_orBfr. All other string parameters are ignored when a_object is zero elements in length.

s_ifLmntNull - When an element within a_object is null, this is the value to appended in place of that element's toString.