er.extensions.foundation
Class ERXArrayUtilities

java.lang.Object
  er.extensions.foundation.ERXArrayUtilities

public class ERXArrayUtilities
extends Object

Collection of NSArray utilities.

Nested Class Summary

static class	ERXArrayUtilities.AvgNonNullOperator Define an NSArray.Operator for the key avgNonNull. This allows for key value paths like: myArray.valueForKey("@avgNonNull.revenue"); which will sum up all values and divide by the number of nun-null entries.
static class	ERXArrayUtilities.FetchSpecOperator Define an NSArray.Operator for the key fetchSpec. This allows for key value paths like: myArray.valueForKey("@fetchSpec.fetchUsers"); Which in this case would return myArray filtered and sorted by the EOFetchSpecification named "fetchUsers" which must be a model-based fetchspec in the first object's entity.
static class	ERXArrayUtilities.FlattenOperator Define an NSArray.Operator for the key flatten. This allows for key value paths like: myArray.valueForKey("@flatten"); Which in this case would return myArray flattened if myArray is an NSArray of NSArrays (of NSArrays etc).
static class	ERXArrayUtilities.IsEmptyOperator Define an NSArray.Operator for the key isEmpty. This allows for key value paths like: myArray.valueForKey("@isEmpty");
static class	ERXArrayUtilities.LimitOperator Define an NSArray.Operator for the key limit, which is similar to subarrayWithRange except that it is always from 0 to the limit value.
static class	ERXArrayUtilities.MedianOperator Define an NSArray.Operator for the key median. This allows for key value paths like: myArray.valueForKey("@median.someMorePath"); which return the median of the array elements at the given key path.
static class	ERXArrayUtilities.ObjectAtIndexOperator Define an NSArray.Operator for the key objectAtIndex. This allows for key value paths like: myArray.valueForKey("@objectAtIndex.3.firstName");
static class	ERXArrayUtilities.RemoveNullValuesOperator Define an NSArray.Operator for the key removeNullValues. This allows for key value paths like: myArray.valueForKeyPath("@removeNullValues.someOtherPath"); Which in this case would return myArray without the occurrences of NSKeyValueCoding.Null.
static class	ERXArrayUtilities.ReverseOperator Define an NSArray.Operator for the key reverse. This allows for key value paths like: myArray.valueForKey("@reverse.someMorePath"); which return a reversed result as to you would normally get.
static class	ERXArrayUtilities.SortOperator Define an NSArray.Operator for the key sort. This allows for key value paths like: myArray.valueForKey("@sort.firstName"); myArray.valueForKey("@sort.lastName,firstName"); Which in the first case would return myArray sorted ascending by first name and the second case by lastName and then by firstName.
static class	ERXArrayUtilities.SubarrayWithRangeOperator Define an NSArray.Operator for the key subarrayWithRange. This allows for key value paths like: myArray.valueForKeyPath("@subarrayWithRange.20-3.name"); Note that the syntax is slightly misleading, implying that you provide a start and end index.
static class	ERXArrayUtilities.UniqueOperator Define an NSArray.Operator for the key unique. This allows for key value paths like: myArray.valueForKeyPath("@unique.someOtherPath"); Which in this case would return only those objects which are unique in myArray.

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 NSArray	arrayByRemovingFirstObject(NSArray array) Creates an array that has all of the objects of the parameter array without the first object.
static NSArray	arrayBySelectingInstancesOfClass(NSArray array, Class aClass) Prunes an array for only instances of the given class.
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 <T,K,V> NSDictionary<K,NSArray<V>>	arrayGroupedByKeyPath(NSArray<T> objects, ERXKey<K> keyPath, boolean includeNulls, ERXKey<V> valueKeyPath) Typesafe variant of arrayGroupedByKeyPath.
static <T,K,V> NSDictionary<K,NSArray<V>>	arrayGroupedByKeyPath(NSArray<T> objects, ERXKey<K> keyPath, K nullGroupingKey, ERXKey<V> valueKeyPath) Typesafe variant of arrayGroupedByKeyPath.
static <K,V> NSDictionary<K,NSArray<V>>	arrayGroupedByKeyPath(NSArray<V> objects, ERXKey<K> keyPath) Typesafe variant of arrayGroupedByKeyPath.
static NSDictionary	arrayGroupedByKeyPath(NSArray objects, String keyPath) Groups objects by the value returned by evaluating keyPath on the objects.
static NSDictionary	arrayGroupedByKeyPath(NSArray objects, String keyPath, boolean includeNulls, String valueKeyPath) Groups objects by the value returned by evaluating keyPath on the objects.
static NSDictionary	arrayGroupedByKeyPath(NSArray objects, String keyPath, Object nullGroupingKey, String valueKeyPath) Groups objects by the value returned by evaluating keyPath on the objects.
static <T,K,V> NSDictionary<K,NSArray<V>>	arrayGroupedByToManyKeyPath(NSArray<T> objects, ERXKey<K> keyPath, K nullGroupingKey, ERXKey<V> valueKeyPath) Typesafe variant of arrayGroupedByToManyKeyPath.
static <K,V> NSDictionary<K,NSArray<V>>	arrayGroupedByToManyKeyPath(NSArray<V> objects, ERXKey<K> keyPath, boolean includeNulls) Typesafe variant of arrayGroupedByToManyKeyPath.
static <K,V> NSDictionary<K,NSArray<V>>	arrayGroupedByToManyKeyPath(NSArray<V> objects, ERXKey<K> keyPath, K nullGroupingKey) Typesafe variant of arrayGroupedByToManyKeyPath.
static NSDictionary	arrayGroupedByToManyKeyPath(NSArray objects, 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 NSDictionary	arrayGroupedByToManyKeyPath(NSArray objects, String keyPath, Object nullGroupingKey) 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 NSDictionary	arrayGroupedByToManyKeyPath(NSArray objects, String keyPath, Object nullGroupingKey, String valueKeyPath) 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	arrayWithObjectsAtIndexesSwapped(NSArray array, int indexOfObject1, int indexOfObject2) Swaps the two objects at the given indexes in the given NSArray and returns a new NSArray.
static NSArray	arrayWithObjectsSwapped(NSArray array, Object object1, Object object2) Swaps the two given Objects in the given NSArray and returns a new NSArray.
static NSArray	arrayWithoutDuplicateKeyValue(NSArray objects, String key) Filters out duplicates of an array of objects based on the value of the given key path off of those objects.
static NSArray	arrayWithoutDuplicates(NSArray anArray) Filters out all of the duplicate objects in a given array. Preserves the order now.
static NSArray	batchedArrayWithSize(NSArray array, int batchSize) Batches an NSArray into sub-arrays of the given size.
static NSArray	deepClone(NSArray array, boolean onlyCollections)
static NSSet	deepClone(NSSet set, boolean onlyCollections)
static NSDictionary	dictionaryOfObjectsIndexedByKeyPath(NSArray array, String keyPath) Calls dictionaryOfObjectsIndexedByKeyPathThrowOnCollision() passing false for throwOnCollision.
static NSDictionary	dictionaryOfObjectsIndexedByKeyPathThrowOnCollision(NSArray array, String keyPath, boolean throwOnCollision) Given an array of objects, returns a dictionary mapping the value by performing valueForKeyPath on each object in the array to the object in the array.
static <T> NSArray<T>	distinct(NSArray<T> array) Shorter name for arrayWithoutDuplicates, which I always forget the name of.
static boolean	enumerationHasMatchWithQualifierEvaluation(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	filteredArrayWithEntityFetchSpecification(NSArray array, String entity, String fetchSpec) 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 Object	firstObject(NSArray array) Returns the first object of the array.
static Object	firstObjectWithValueForKeyPath(NSArray array, Object value, String keyPath) Finds the first object in the array with a given value for a given key path.
static NSArray	flatten(NSArray originalArray) Recursively flattens an array of arrays and individual objects 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.
static NSArray	flatten(NSArray originalArray, boolean filterDuplicates) Recursively flattens an array of arrays and individual objects 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.
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 int	indexOfFirstObjectWithValueForKeyPath(NSArray array, Object value, String keyPath) Finds the index of the first object in the array with a given value for a given keypath.
static int	indexOfObjectUsingEqualator(NSArray array, Object object, ERXEqualator equalator) Locates an object within an array using a custom equality check provided as an ERXEqualator.
static void	initialize() Will register new NSArray operators sort, sortAsc, sortDesc, sortInsensitiveAsc, sortInsensitiveDesc, unique, flatten, reverse, limit, and fetchSpec
static NSArray	intersectingElements(NSArray array1, NSArray array2) Intersects the elements of two arrays.
static boolean	iteratorHasMatchWithQualifierEvaluation(Iterator iterator, EOQualifierEvaluation qualifier) Filters any kinds of collections that implements Iterator interface such as NSArray, NSSet, Vector and Hashtable using the EOQualifierEvaluation interface.
static Number	median(NSArray array, String keypath) Calculates the median value of an array.
static String[]	objectArrayCastToStringArray(Object[] o) Converts an Object array to a String array by casting each element.
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	objectsWithValueForKeyPath(NSArray array, Object valueToLookFor, String keyPath) Walks over an array and returns an array of objects from that array that have a particular value for a particular key path.
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 void	safeAddObject(NSMutableArray array, Object object) Adds the object to the mutable array if the object is not null.
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 <U> NSArray<U>	sortedArraySortedWithKey(NSArray array, String key) Sorts a given array with a key in ascending fashion.
static <U> NSArray<U>	sortedArraySortedWithKey(NSArray array, String key, NSSelector selector) Sorts a given array with a key in ascending fashion.
static <U> NSArray<U>	sortedArraySortedWithKeys(NSArray array, NSArray keys, NSSelector selector) Sorts a given array with a set of keys according to the given selector.
static NSArray	sortedArrayUsingComparator(NSArray array, NSComparator comparator) Just like the method on NSArray, except it catches the NSComparator.ComparisonException and, if thrown, it wraps it in a runtime exception.
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..
static void	swapObjectsAtIndexesInArray(NSMutableArray array, int indexOfA, int indexOfB) Swaps two objects at the given indexes in an array inplace
static void	swapObjectsInArray(NSMutableArray array, Object a, Object b) Swaps two objects a and b in an array inplace
static void	swapObjectWithObjectAtIndexInArray(NSMutableArray array, Object a, int indexOfB) Swaps the object a with the object at the given index
static String[]	toStringArray(NSArray a)
static NSArray	valuesForKeyPaths(Object array, NSArray paths) Performs multiple key-value coding calls against an array or an object.

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 <K,V> NSDictionary<K,NSArray<V>> arrayGroupedByKeyPath(NSArray<V> objects,
                                                                     ERXKey<K> keyPath)

Typesafe variant of arrayGroupedByKeyPath.

Parameters:

objects - array of objects to be grouped

keyPath - path into objects 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 that value. Note that if the key path returns null then one of the keys will be NULL_GROUPING_KEY

arrayGroupedByKeyPath

public static NSDictionary arrayGroupedByKeyPath(NSArray objects,
                                                 String keyPath)

Groups objects by the value returned by evaluating keyPath on the objects. The dictionary that is returned contains keys that correspond to the values returned by the keyPath. The objects in the dictionary are NSArrays of the objects having the key value at keyPath.

Parameters:

objects - array of objects to be grouped

keyPath - path into objects 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 that value. Note that if the key path returns null then one of the keys will be NULL_GROUPING_KEY

arrayGroupedByKeyPath

public static <T,K,V> NSDictionary<K,NSArray<V>> arrayGroupedByKeyPath(NSArray<T> objects,
                                                                       ERXKey<K> keyPath,
                                                                       boolean includeNulls,
                                                                       ERXKey<V> valueKeyPath)

Typesafe variant of arrayGroupedByKeyPath.

Parameters:

objects - array of objects to be grouped

keyPath - path into objects used to group the objects

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

valueKeyPath - allows the grouped objects in the result to be derived from objects (by evaluating valueKeyPath), instead of being members of the objects collection. Objects that evaluate valueKeyPath to null have no value included in the result.

Returns:

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

arrayGroupedByKeyPath

public static NSDictionary arrayGroupedByKeyPath(NSArray objects,
                                                 String keyPath,
                                                 boolean includeNulls,
                                                 String valueKeyPath)

Groups objects by the value returned by evaluating keyPath on the objects. The dictionary that is returned contains keys that correspond to the values returned by the keyPath. If valueKeyPath is null, the objects in the dictionary are NSArrays of the objects having the key value at keyPath. If valueKeyPath is not null, the objects in the dictionary are NSArrays of the result of calling valueKeyPath on the objects having the key value at keyPath. If valueKeyPath is not null, the objects in the dictionary will not be from objects.

Parameters:

objects - array of objects to be grouped

keyPath - path into objects used to group the objects

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

valueKeyPath - allows the grouped objects in the result to be derived from objects (by evaluating valueKeyPath), instead of being members of the objects collection. Objects that evaluate valueKeyPath to null have no value included in the result.

Returns:

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

arrayGroupedByKeyPath

public static <T,K,V> NSDictionary<K,NSArray<V>> arrayGroupedByKeyPath(NSArray<T> objects,
                                                                       ERXKey<K> keyPath,
                                                                       K nullGroupingKey,
                                                                       ERXKey<V> valueKeyPath)

Typesafe variant of arrayGroupedByKeyPath.

Parameters:

objects - array of objects to be grouped

keyPath - path into objects used to group the objects

nullGroupingKey - if not-null, determines if keyPaths that resolve to null should be allowed into the group; if so, this key is used for them

valueKeyPath - allows the grouped objects in the result to be derived from objects (by evaluating valueKeyPath), instead of being members of the objects collection. Objects that evaluate valueKeyPath to null have no value included in the result.

Returns:

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

arrayGroupedByKeyPath

public static NSDictionary arrayGroupedByKeyPath(NSArray objects,
                                                 String keyPath,
                                                 Object nullGroupingKey,
                                                 String valueKeyPath)

Groups objects by the value returned by evaluating keyPath on the objects. The dictionary that is returned contains keys that correspond to the values returned by the keyPath. If valueKeyPath is null, the objects in the dictionary are NSArrays of the objects having the key value at keyPath. If valueKeyPath is not null, the objects in the dictionary are NSArrays of the result of calling valueKeyPath on the objects having the key value at keyPath. If valueKeyPath is not null, the objects in the dictionary will not be from objects.

Parameters:

objects - array of objects to be grouped

keyPath - path into objects used to group the objects

nullGroupingKey - if not-null, determines if keyPaths that resolve to null should be allowed into the group; if so, this key is used for them

valueKeyPath - allows the grouped objects in the result to be derived from objects (by evaluating valueKeyPath), instead of being members of the objects collection. Objects that evaluate valueKeyPath to null have no value included in the result

Returns:

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

arrayGroupedByToManyKeyPath

public static <K,V> NSDictionary<K,NSArray<V>> arrayGroupedByToManyKeyPath(NSArray<V> objects,
                                                                           ERXKey<K> keyPath,
                                                                           boolean includeNulls)

Typesafe variant of arrayGroupedByToManyKeyPath.

Parameters:

objects - the objects to be grouped

keyPath - the key to group by

includeNulls - determins if the keypaths that resolve to null should be allowed in the group

Returns:

the resulting dictionary

arrayGroupedByToManyKeyPath

public static NSDictionary arrayGroupedByToManyKeyPath(NSArray objects,
                                                       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. A typical example is an array of users with a roles relationship. The result to calling arrayGroupedByToManyKeyPath(users, "roles.name") would be "admin" = (user1, user2); "editor" = (user3);.... 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:

objects - 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

arrayGroupedByToManyKeyPath

public static <K,V> NSDictionary<K,NSArray<V>> arrayGroupedByToManyKeyPath(NSArray<V> objects,
                                                                           ERXKey<K> keyPath,
                                                                           K nullGroupingKey)

Typesafe variant of arrayGroupedByToManyKeyPath.

Parameters:

objects - array of objects to be grouped

keyPath - path used to group the objects.

nullGroupingKey - if not-null, determines if keyPaths that resolve to null should be allowed into the group; if so, this key is used for them

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 objects,