er.extensions
Class ERXArrayUtilities

java.lang.Object
  er.extensions.ERXArrayUtilities

public class ERXArrayUtilities

extends Object

Collection of NSArray utilities.

Field Summary

static String

NULL_GROUPING_KEY Holds the null grouping key for use when grouping objects based on a key that might return null and nulls are allowed

Constructor Summary

ERXArrayUtilities()

Method Summary

static void	addObjectsFromArrayWithoutDuplicates(NSMutableArray a1, NSArray a2) Adds all of the non-duplicate elements from the second array to the mutable array.
static NSArray	arrayByAddingObjectsFromArrayWithoutDuplicates(NSArray a1, NSArray a2) Creates an array preserving order by adding all of the non-duplicate values from the second array to the first.
static boolean	arrayContainsAnyObjectFromArray(NSArray array, NSArray objects) Function to determine if an array contains any of the elements of another array.
static boolean	arrayContainsArray(NSArray array, NSArray objects) Function to determine if an array contains all of the elements of another array.
static NSArray	arrayForKeysPath(NSArray array, NSArray keys) Returns an array of dictionaries containing the key/value pairs for the given paths.
static NSArray	arrayFromPropertyList(String name, NSBundle bundle) Creates an NSArray from a resource associated with a given bundle that is in property list format.
static NSDictionary	arrayGroupedByKeyPath(NSArray objects, String keyPath) Groups an array of objects by a given key path.
static NSDictionary	arrayGroupedByKeyPath(NSArray eos, String keyPath, boolean includeNulls, String extraKeyPathForValues) Groups an array of objects by a given key path.
static NSDictionary	arrayGroupedByToManyKeyPath(NSArray eos, String keyPath, boolean includeNulls) Groups an array of objects by a given to-many key path, where every single item in the to-many will put the object in the corresponding group.
static NSArray	arrayMinusArray(NSArray main, NSArray minus) Subtracts the contents of one array from another.
static NSArray	arrayMinusObject(NSArray main, Object object) Subtracts a single object from an array.
static boolean	arraysAreIdenticalSets(NSArray a1, NSArray a2) Simple comparision method to see if two array objects are identical sets.
static NSArray	arrayWithoutDuplicateKeyValue(NSArray eos, String key) Filters out duplicates of an array of enterprise objects based on the value of the given key off of those objects.
static NSArray	arrayWithoutDuplicates(NSArray anArray) Filters out all of the duplicate objects in a given array.
static NSArray	batchedArrayWithSize(NSArray array, int batchSize) Batches an NSArray into sub-arrays of the given size.
static NSArray	filteredArrayWithEntityFetchSpecification(NSArray array, String fetchSpec, String entity) Filters a given array with a named fetch specification.
static NSArray	filteredArrayWithEntityFetchSpecification(NSArray array, String entity, String fetchSpec, NSDictionary bindings) Filters a given array with a named fetch specification and bindings.
static NSArray	filteredArrayWithFetchSpecificationNamedEntityNamed(NSArray array, String fetchSpec, String entity) Deprecated.
static NSArray	filteredArrayWithFetchSpecificationNamedEntityNamedBindings(NSArray array, String fetchSpec, String entity, NSDictionary bindings) Deprecated.
static NSArray	filteredArrayWithQualifierEvaluation(Enumeration enumeration, EOQualifierEvaluation qualifier) Filters any kinds of collections that implements Enumeration interface such as NSArray, NSSet, Vector and Hashtable using the EOQualifierEvaluation interface.
static NSArray	filteredArrayWithQualifierEvaluation(Iterator iterator, EOQualifierEvaluation qualifier) Filters any kind of collections that implements Iterator interface such as ArrayList, HashMap, SortedSet and TreeSet using the EOQualifierEvaluation interface.
static NSArray	filteredArrayWithQualifierEvaluation(NSArray array, EOQualifierEvaluation qualifier) Filters an array using the EOQualifierEvaluation interface.
static NSArray	flatten(NSArray array) Recursively flattens an array of arrays into a single array of elements.
static NSArray	flatten(NSArray array, boolean filterDuplicates) Recursively flattens an array of arrays into a single array of elements.
static String	friendlyDisplayForKeyPath(NSArray list, String attribute, String nullArrayDisplay, String separator, String finalSeparator) Displays a list of attributes off of objects in a 'friendly' manner.
static void	initialize() Will register new NSArray operators sort, sortAsc, sortDesc, sortInsensitiveAsc, sortInsensitiveDesc, unique, flatten, reverse and fetchSpec
static NSArray	intersectingElements(NSArray array1, NSArray array2) Intersects the elements of two arrays.
static String	objectArraysToString(NSArray a) pretty prints a NSArray of two dimensional Object array which is ugly when using toString
static String	objectArrayToString(Object[] o) pretty prints an Object array which is ugly when using toString
static String	objectArrayToString(Object[][] o) pretty prints a two dimensional Object array which is ugly when using toString
static NSArray	removeNullValues(NSArray a) Removes all occurencies of NSKeyValueCoding.NullValue in the provided array
static NSArray	removeNullValuesFromEnd(NSArray array) removes all occurencies of NSKeyValueCoding.Null from the end of the array
static NSArray	reverse(NSArray array) Reverses the elements of an array
static NSSet	setFromArray(NSArray array) Simply utility method to create a concreate set object from an array
static void	shiftObjectLeft(NSMutableArray array, Object object) shifts a given object in an array one value to the left (index--).
static void	shiftObjectRight(NSMutableArray array, Object object) shifts a given object in an array one value to the right (index++).
static void	sortArrayWithKey(NSMutableArray array, String key) Sorts a given mutable array with a key in place.
static void	sortArrayWithKey(NSMutableArray array, String key, NSSelector selector) Sorts a given mutable array with a key in place.
static NSArray	sortedArraySortedWithKey(NSArray array, String key) Sorts a given array with a key in ascending fashion.
static NSArray	sortedArraySortedWithKey(NSArray array, String key, NSSelector selector) Sorts a given array with a key in ascending fashion.
static NSArray	sortedArraySortedWithKeys(NSArray array, NSArray keys, NSSelector selector) Sorts a given array with a set of keys according to the given selector.
static NSMutableArray	sortedMutableArraySortedWithKey(NSArray array, String key) Sorts a given array with a key in ascending fashion and returns a mutable clone of the result.
static NSSelector	sortSelectorWithKey(String key) The qualifiers EOSortOrdering.CompareAscending.. and friends are actually 'special' and processed in a different/faster way when sorting than a selector that would be created by new NSSelector("compareAscending", ObjectClassArray).
static String[]	toStringArray(NSArray a)
static NSArray	valuesForKeyPaths(Object array, NSArray paths) Performs multiple key-value coding calls against an array.

Methods inherited from class java.lang.Object

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

Field Detail

NULL_GROUPING_KEY

public static final String NULL_GROUPING_KEY

Holds the null grouping key for use when grouping objects based on a key that might return null and nulls are allowed

See Also:

Constant Field Values

Constructor Detail

ERXArrayUtilities

public ERXArrayUtilities()

Method Detail

setFromArray

public static NSSet setFromArray(NSArray array)

Simply utility method to create a concreate set object from an array

Parameters:

array - of elements

Returns:

concreate set.

sortSelectorWithKey

public static NSSelector sortSelectorWithKey(String key)

The qualifiers EOSortOrdering.CompareAscending.. and friends are actually 'special' and processed in a different/faster way when sorting than a selector that would be created by new NSSelector("compareAscending", ObjectClassArray). This method eases the pain on creating those selectors from a string.

Parameters:

key - sort key

arrayGroupedByKeyPath

public static NSDictionary arrayGroupedByKeyPath(NSArray objects,
                                                 String keyPath)

Groups an array of objects by a given key path. The dictionary that is returned contains keys that correspond to the grouped keys values. This means that the object pointed to by the key path must be a cloneable object. For instance using the key path 'company' would not work because enterprise objects are not cloneable. Instead you might choose to use the key path 'company.name' or 'company.primaryKey', if your enterprise objects support this see ERXGenericRecord if interested.

Parameters:

objects - array of objects to be grouped

keyPath - path used to group the objects.

Returns:

a dictionary where the keys are the grouped values and the objects are arrays of the objects that have the grouped characteristic. Note that if the key path returns null then one of the keys will be the static ivar NULL_GROUPING_KEY

arrayGroupedByKeyPath

public static NSDictionary arrayGroupedByKeyPath(NSArray eos,
                                                 String keyPath,
                                                 boolean includeNulls,
                                                 String extraKeyPathForValues)

Groups an array of objects by a given key path. The dictionary that is returned contains keys that correspond to the grouped keys values. This means that the object pointed to by the key path must be a cloneable object. For instance using the key path 'company' would not work because enterprise objects are not cloneable. Instead you might choose to use the key path 'company.name' of 'company.primaryKey', if your enterprise objects support this see ERXGenericRecord if interested.

Parameters:

eos - array of objects to be grouped

keyPath - path used to group the objects.

includeNulls - determines if keyPaths that resolve to null should be allowed into the group.

extraKeyPathForValues - allows a selected object to include more objects in the group. This is going away in the future.

Returns:

a dictionary where the keys are the grouped values and the objects are arrays of the objects that have the grouped characteristic. Note that if the key path returns null then one of the keys will be the static ivar NULL_GROUPING_KEY

arrayGroupedByToManyKeyPath

public static NSDictionary arrayGroupedByToManyKeyPath(NSArray eos,
                                                       String keyPath,
                                                       boolean includeNulls)

Groups an array of objects by a given to-many key path, where every single item in the to-many will put the object in the corresponding group. The dictionary that is returned contains keys that correspond to the grouped keys values. This means that the object pointed to by the key path must be a cloneable object. For instance using the key path 'users' would not work because enterprise objects are not cloneable. Instead you might choose to use the key path 'users.name' of 'users.primaryKey', if your enterprise objects support this see ERXGenericRecord if interested.

Parameters:

eos - array of objects to be grouped

keyPath - path used to group the objects.

includeNulls - determines if keyPaths that resolve to null should be allowed into the group.

Returns:

a dictionary where the keys are the grouped values and the objects are arrays of the objects that have the grouped characteristic. Note that if the key path returns null then one of the keys will be the static ivar NULL_GROUPING_KEY

arraysAreIdenticalSets

public static boolean arraysAreIdenticalSets(NSArray a1,
                                             NSArray a2)

Simple comparision method to see if two array objects are identical sets.

Parameters:

a1 - first array

a2 - second array

Returns:

result of comparison

filteredArrayWithQualifierEvaluation

public static NSArray filteredArrayWithQualifierEvaluation(NSArray array,
                                                           EOQualifierEvaluation qualifier)

Filters an array using the EOQualifierEvaluation interface.

Parameters:

array - to be filtered

qualifier - to do the filtering

Returns:

array of filtered results.

filteredArrayWithQualifierEvaluation

public static NSArray filteredArrayWithQualifierEvaluation(Enumeration enumeration,
                                                           EOQualifierEvaluation qualifier)

Filters any kinds of collections that implements Enumeration interface such as NSArray, NSSet, Vector and Hashtable using the EOQualifierEvaluation interface.

Parameters:

enumeration - to be filtered; to obtain an enumeration, use objectEnumerator() for the collections in com.webobjects.foundation package and use elements() for the Vector and Hashtable

qualifier - to do the filtering

Returns:

array of filtered results.

filteredArrayWithQualifierEvaluation

public static NSArray filteredArrayWithQualifierEvaluation(Iterator iterator,
                                                           EOQualifierEvaluation qualifier)

Filters any kind of collections that implements Iterator interface such as ArrayList, HashMap, SortedSet and TreeSet using the EOQualifierEvaluation interface.

Parameters:

iterator - to be filtered; use iterator() to obtain an iterator from the collections

qualifier - to do the filtering

Returns:

array of filtered results.

arrayWithoutDuplicateKeyValue

public static NSArray arrayWithoutDuplicateKeyValue(NSArray eos,
                                                    String key)

Filters out duplicates of an array of enterprise objects based on the value of the given key off of those objects. Note: Current implementation depends on the key returning a cloneable object. Also the order is not preseved from the original array.

Parameters:

eos - array of enterprise objects

key - key path to be evaluated off of every enterprise object

Returns:

filter array of objects based on the value of a key-path.

arrayMinusArray

public static NSArray arrayMinusArray(NSArray main,
                                      NSArray minus)

Subtracts the contents of one array from another. The order of the array should be preseved.

Parameters:

main - array to have values removed from it.

minus - array of values to remove from the main array

Returns:

array after performing subtraction.

arrayMinusObject

public static NSArray arrayMinusObject(NSArray main,
                                       Object object)

Subtracts a single object from an array.

Parameters:

main - array to have value removed from it.

Returns:

array after performing subtraction.

arrayByAddingObjectsFromArrayWithoutDuplicates

public static NSArray arrayByAddingObjectsFromArrayWithoutDuplicates(NSArray a1,
                                                                     NSArray a2)

Creates an array preserving order by adding all of the non-duplicate values from the second array to the first.

Parameters:

a1 - first array

a2 - second array

Returns:

array containing all of the elements of the first array and all of the non-duplicate elements of the second array.

addObjectsFromArrayWithoutDuplicates

public static void addObjectsFromArrayWithoutDuplicates(NSMutableArray a1,
                                                        NSArray a2)

Adds all of the non-duplicate elements from the second array to the mutable array.

Parameters:

a1 - mutable array where non-duplicate objects are added

a2 - array to be added to a1

flatten

public static NSArray flatten(NSArray array)

Recursively flattens an array of arrays into a single array of elements.

For example:
NSArray foos; //Assume exists
NSArray bars = (NSArray)foos.valueForKey("toBars"); In this case if foos contained five elements then the array bars will contain five arrays each corresponding to what aFoo.toBars would return. To have the entire collection of bars in one single array you would call: NSArray allBars = flatten(bars)

Parameters:

array - to be flattened

Returns:

an array containing all of the elements from all of the arrays contained within the array passed in.

flatten

public static NSArray flatten(NSArray array,
                              boolean filterDuplicates)

Recursively flattens an array of arrays into a single array of elements.

For example:
NSArray foos; //Assume exists
NSArray bars = (NSArray)foos.valueForKey("toBars"); In this case if foos contained five elements then the array bars will contain five arrays each corresponding to what aFoo.toBars would return. To have the entire collection of bars in one single array you would call: NSArray allBars = flatten(bars)

Parameters:

array - to be flattened

filterDuplicates - determines if the duplicate values should be filtered

Returns:

an array containing all of the elements from all of the arrays contained within the array passed in.

arrayFromPropertyList

public static NSArray arrayFromPropertyList(String name,
                                            NSBundle bundle)

Creates an NSArray from a resource associated with a given bundle that is in property list format.

Parameters:

name - name of the file or resource.

bundle - NSBundle to which the resource belongs.

Returns:

NSArray de-serialized from the property list.

valuesForKeyPaths

public static NSArray valuesForKeyPaths(Object array,
                                        NSArray paths)

Performs multiple key-value coding calls against an array.

Parameters:

array - object to be acted upon.

paths - array of keypaths.

Returns:

returns an array containing an array of values for every keypath.

sortedMutableArraySortedWithKey

public static NSMutableArray sortedMutableArraySortedWithKey(NSArray array,
                                                             String key)

Sorts a given array with a key in ascending fashion and returns a mutable clone of the result.

Parameters:

array - array to be sorted.

key - sort key.

Returns:

mutable clone of sorted array.

sortedArraySortedWithKey

public static NSArray sortedArraySortedWithKey(NSArray array,
                                               String key)

Sorts a given array with a key in ascending fashion.

Parameters:

array - array to be sorted.

key - sort key.

Returns:

mutable clone of sorted array.

sortedArraySortedWithKey

public static NSArray sortedArraySortedWithKey(NSArray array,
                                               String key,
                                               NSSelector selector)

Sorts a given array with a key in ascending fashion.

Parameters:

array - array to be sorted.

key - sort key.

selector - sort order selector to use, if null, then sort will be ascending.

Returns:

sorted array.

sortedArraySortedWithKeys

public static NSArray sortedArraySortedWithKeys(NSArray array,
                                                NSArray keys,
                                                NSSelector selector)

Sorts a given array with a set of keys according to the given selector.

Parameters:

array - array to be sorted.

keys - sort keys

selector - sort order selector to use, if null, then sort will be ascending.

Returns:

sorted array.

sortArrayWithKey

public static void sortArrayWithKey(NSMutableArray array,
                                    String key)

Sorts a given mutable array with a key in place.

Parameters:

array - array to be sorted.

key - sort key.

sortArrayWithKey

public static void sortArrayWithKey(NSMutableArray array,
                                    String key,
                                    NSSelector selector)

Sorts a given mutable array with a key in place.

Parameters:

array - array to be sorted.

key - sort key.

selector - sort order selector to use, if null, then sort will be ascending.

initialize

public static void initialize()

Will register new NSArray operators sort, sortAsc, sortDesc, sortInsensitiveAsc, sortInsensitiveDesc, unique, flatten, reverse and fetchSpec

arrayWithoutDuplicates

public static NSArray arrayWithoutDuplicates(NSArray anArray)

Filters out all of the duplicate objects in a given array.
Preserves the order now.

Parameters:

anArray - to be filtered

Returns:

filtered array.

batchedArrayWithSize

public static NSArray batchedArrayWithSize(NSArray array,
                                           int batchSize)

Batches an NSArray into sub-arrays of the given size.

Parameters:

array - array to batch

batchSize - number of items in each batch

Returns:

NSArray of NSArrays, each with at most batchSize items

filteredArrayWithEntityFetchSpecification

public static NSArray filteredArrayWithEntityFetchSpecification(NSArray array,
                                                                String entity,
                                                                String fetchSpec,
                                                                NSDictionary bindings)

Filters a given array with a named fetch specification and bindings.

Parameters:

array - array to be filtered.

fetchSpec - name of the EOQualifierEvaluation.

entity - name of the EOEntity to which the fetch specification is associated.

bindings - bindings dictionary for qualifier variable substitution.

Returns:

array filtered and sorted by the named fetch specification.

filteredArrayWithFetchSpecificationNamedEntityNamedBindings

public static NSArray filteredArrayWithFetchSpecificationNamedEntityNamedBindings(NSArray array,
                                                                                  String fetchSpec,
                                                                                  String entity,
                                                                                  NSDictionary bindings)

Deprecated.

filteredArrayWithEntityFetchSpecification

public static NSArray filteredArrayWithEntityFetchSpecification(NSArray array,
                                                                String fetchSpec,
                                                                String entity)

Filters a given array with a named fetch specification.

Parameters:

array - array to be filtered.

fetchSpec - name of the EOQualifierEvaluation.

entity - name of the EOEntity to which the fetch specification is associated.

Returns:

array filtered and sorted by the named fetch specification.

filteredArrayWithFetchSpecificationNamedEntityNamed

public static NSArray filteredArrayWithFetchSpecificationNamedEntityNamed(NSArray array,
                                                                          String fetchSpec,
                                                                          String entity)

Deprecated.

shiftObjectLeft

public static void shiftObjectLeft(NSMutableArray array,
                                   Object object)

shifts a given object in an array one value to the left (index--).

Parameters:

array - array to be modified.

object - the object that should be moved

shiftObjectRight

public static void shiftObjectRight(NSMutableArray array,
                                    Object object)

shifts a given object in an array one value to the right (index++).

Parameters:

array - array to be modified.

object - the object that should be moved

arrayContainsAnyObjectFromArray

public static boolean arrayContainsAnyObjectFromArray(NSArray array,
                                                      NSArray objects)

Function to determine if an array contains any of the elements of another array.

Parameters:

array - to test if it contains any of the objects

objects - array of objects to test if the first array contains any of

Returns:

if the first array contains any elements from the second array

arrayContainsArray

public static boolean arrayContainsArray(NSArray array,
                                         NSArray objects)

Function to determine if an array contains all of the elements of another array.

Parameters:

array - to test if it contains all of the objects of another array

objects - array of objects to test if the first array contains all of

Returns:

if the first array contains all of the elements from the second array

intersectingElements

public static NSArray intersectingElements(NSArray array1,
                                           NSArray array2)

Intersects the elements of two arrays. This has the effect of stripping out duplicates.

Parameters:

array1 - the first array

array2 - the second array

Returns:

the intersecting elements

reverse

public static NSArray reverse(NSArray array)

Reverses the elements of an array

Parameters:

array - to be reversed

Returns:

reverse ordered array

friendlyDisplayForKeyPath

public static String friendlyDisplayForKeyPath(NSArray list,
                                               String attribute,
                                               String nullArrayDisplay,
                                               String separator,
                                               String finalSeparator)

Displays a list of attributes off of objects in a 'friendly' manner.

For example, given an array containing three user objects and the attribute key "firstName", the result of calling this method would be the string: "Max, Anjo and Patrice".

Parameters:

list - of objects to be displayed in a friendly manner

attribute - key to be called on each object in the list

nullArrayDisplay - string to be returned if the list is null or empty

separator - string to be used for the first items

finalSeparator - used between the last items

Returns:

friendly display string

arrayForKeysPath

public static NSArray arrayForKeysPath(NSArray array,
                                       NSArray keys)

Returns an array of dictionaries containing the key/value pairs for the given paths.

Parameters:

array - array of objects

keys - array of keys

Returns:

array of dictionaries containing values for the key paths

removeNullValues

public static NSArray removeNullValues(NSArray a)

Removes all occurencies of NSKeyValueCoding.NullValue in the provided array

Parameters:

a - the array from which the NullValue should be removed

Returns:

a new NSArray with the same order than the original array but without NSKeyValueCoding.NullValue objects

objectArrayToString

public static String objectArrayToString(Object[] o)

pretty prints an Object array which is ugly when using toString

Parameters:

o - the object which one wants to print as a String

Returns:

the String which can be used in lets say log.info("my array = "+ERXArrayUtilities.objectArrayToString(myArray));

objectArrayToString

public static String objectArrayToString(Object[][] o)

pretty prints a two dimensional Object array which is ugly when using toString

Parameters:

o - the object which one wants to print as a String

Returns:

the String which can be used in lets say log.info("my array = "+ERXArrayUtilities.objectArrayToString(myArray));

objectArraysToString

public static String objectArraysToString(NSArray a)

pretty prints a NSArray of two dimensional Object array which is ugly when using toString

Returns:

the String which can be used in lets say log.info("my array = "+ERXArrayUtilities.objectArrayToString(myArray));

removeNullValuesFromEnd

public static NSArray removeNullValuesFromEnd(NSArray array)

removes all occurencies of NSKeyValueCoding.Null from the end of the array

Parameters:

array - the array from which the values should be removed

Returns:

a new NSArray which does not have NSKeyValueCoding.Null instances at the end

toStringArray

public static String[] toStringArray(NSArray a)