NSArray(Extensions) Category Reference

Declared in NSArray+Extensions.h

Overview

General purpose extensions to NSArray.

– arrayByTransformingElementsWithBlock:

Adds the elements of self to a new NSArray performing transformBlock on each element. Nil results from transformBlock results in the item not being added.

- (nonnull NSArray *)arrayByTransformingElementsWithBlock:(nonnull __nullable id ( ^ ) ( NSUInteger index , id __nonnull value ))transformBlock

Parameters

transformBlock

The block to run on each element before adding to the new NSArray.

Return Value

The new NSArray containing the transformed elements.

Discussion

Warning: transformBlock must not be nil!

Declared In

NSArray+Extensions.h

– arrayWithMaxElementCount:

Adds the elements of self to a new NSArray up to a maximum of maximumCount.

- (nonnull NSArray *)arrayWithMaxElementCount:(NSUInteger)maximumCount

Parameters

maximumCount

The maximum number of elements to add to the new NSArray

Return Value

The new NSArray containing a maximum of maximumCount elements.

Declared In

NSArray+Extensions.h

+ compareArray:withArray:providingAddedItems:andRemovedItems:

Compares arrayA to arrayB adding to addedItems the items that were present in arrayB but not in arrayA and adding to removedItems the items that were present in arrayA but not in arrayB.

+ (void)compareArray:(nonnull NSArray *)arrayA withArray:(nonnull NSArray *)arrayB providingAddedItems:(NSArray *__nullable *__nullable)addedItems andRemovedItems:(NSArray *__nullable *__nullable)removedItems

Parameters

arrayA

The first NSArray.

arrayB

The NSArray to compare the first NSArray to.

addedItems

The items that were present in arrayB but not in arrayA.

removedItems

The items that were present in arrayA but not in arrayB.

Declared In

NSArray+Extensions.h

– shuffledArray

Shuffles the elements of the NSArray randomly.

- (nonnull NSArray *)shuffledArray

Return Value

A new NSArray with the shuffled elements.

Declared In

NSArray+Extensions.h

– firstObject

Gets the first element of the NSArray, or nil if the NSArray is empty.

- (nullable id)firstObject

Return Value

The first element of the NSArray or nil.

Declared In

NSArray+Extensions.h

– middleObject

Gets the middle element of the NSArray, or nil if the NSArray is empty.

- (nullable id)middleObject

Return Value

The middle element of the NSArray or nil.

Declared In

NSArray+Extensions.h

– randomObject

Gets a random element of the NSArray, or nil if the NSArray is empty.

- (nullable id)randomObject

Return Value

A random element of the NSArray or nil.

Declared In

NSArray+Extensions.h

– indexInRange:

Whether the index index is in range for this NSArray.

- (BOOL)indexInRange:(NSUInteger)index

Parameters

index

The zero-based index of an element.

Return Value

true if index is in range for the NSArray, and false if not.

Declared In

NSArray+Extensions.h

– binarySearchWithBlock:withStartIndex:withFinalIndex:

Runs a binary search on the NSArray to find the range that matches according to matchBlock. It assumes that the NSArray is sorted and the matching elements are contiguous.

- (BOOL)binarySearchWithBlock:(nonnull RBBinarySearchResult ( ^ ) ( id __nonnull obj ))matchBlock withStartIndex:(nonnull NSUInteger *)startIndex withFinalIndex:(nonnull NSUInteger *)finalIndex

Parameters

matchBlock

The block used to determine the RBBinarySearchResult match for a given element.

startIndex

The initial and resulting start index of the matching range.

finalIndex

The initial and resulting end index of the matching range.

Return Value

Whether or not the binary search was successful.

Discussion

Warning: startIndex and finalIndex must be initialized. The default initialization should be 0 to count - 1.

Declared In

NSArray+Extensions.h

– containsObjectOfType:

Check whether the NSArray contains at least one element of type type.

- (BOOL)containsObjectOfType:(nonnull Class)type

Parameters

type

The Class type to check the existance of.

Return Value

Whether or not at least one element of type type exists in the NSArray.

Declared In

NSArray+Extensions.h

– arrayExcludingObjectsFrom:to:removedObjects:

Creates a new NSArray with elements excluding those between fromIndex and toIndex, adding to removedObjects those elements within the exclusion range.

- (nonnull NSArray *)arrayExcludingObjectsFrom:(NSUInteger)fromIndex to:(NSUInteger)toIndex removedObjects:(NSArray *__nullable *__nullable)removedObjects

Parameters

fromIndex

The starting index of the exclusion range.

toIndex

The last index of the exclusion range.

removedObjects

The excluded items.

Return Value

The new NSArray with all elements outside of the exclusion range.

Declared In

NSArray+Extensions.h

– mergedArrayWithPriorityPostfix:removeOverridesAfterApply:

Performs a merge on the property list by overriding all keys with their siblings providing the given postfix.

- (nonnull instancetype)mergedArrayWithPriorityPostfix:(nonnull NSString *)priorityPostfix removeOverridesAfterApply:(BOOL)removeOverridesAfterApply

Parameters

priorityPostfix

The postfix denoting the overriding key.

removeOverridesAfterApply

If this is true, the overriding keys (those with the postfix) will be removed after they have been applied.

Return Value

The merged property list.

Discussion

*An example: * { “key”: “value”, “key_iPad”: “value_iPad” } merged with the postfix “_iPad” and removeOverridesAfterApply set to true would yield { “key”: “value_iPad” }

Declared In

NSArray+Extensions.h

– arrayExcludingObjects:

Creates a new NSArray with all elements excluding those in excludingObjects.

- (nonnull NSArray *)arrayExcludingObjects:(nonnull NSArray *)excludingObjects

Parameters

excludingObjects

The objects to exclude.

Return Value

A new NSArray containing all elements excluding those in excludingObjects.

Declared In

NSArray+Extensions.h

– arrayByIntersectingWithArray:

Creates a new NSArray containing all of the elements that exist in both self and in array.

- (nonnull NSArray *)arrayByIntersectingWithArray:(nonnull NSArray *)array

Parameters

array

The NSArray to intersect with self.

Return Value

A new NSArray containing all of the elements that exist in both self and in array.

Declared In

NSArray+Extensions.h

– prunedArrayWithOnlyLeafKeys:

Removes all keys from the property list recursively except the keys specified in onlyLeafKeys.

- (nonnull NSArray *)prunedArrayWithOnlyLeafKeys:(nonnull NSArray *)onlyLeafKeys

Parameters

onlyLeafKeys

An NSArray of the keys to keep.

Return Value

The pruned property list.

Declared In

NSArray+Extensions.h

– stringByCombiningComponentsWithSeparator:

Combines the NSString representations of the elements of the NSArray to a single NSString using the separator given.

- (nonnull NSString *)stringByCombiningComponentsWithSeparator:(nonnull NSString *)separator

Parameters

separator

The separator to join the elements with.

Return Value

The joined NSString.

Declared In

NSArray+Extensions.h

– arrayWithItemsMatching:

Creates an NSArray containing all elements that match with the block given.

- (nonnull NSArray *)arrayWithItemsMatching:(nonnull BOOL ( ^ ) ( id __nonnull obj ))matchBlock

Parameters

matchBlock

Used to determine whether a given element is a match or not.

Return Value

The new NSArray containing only matching elements.

Declared In

NSArray+Extensions.h

– arrayWithItemsOfType:

Creates an NSArray containing all elements that are of the type given.

- (nonnull NSArray *)arrayWithItemsOfType:(nonnull Class)itemType

Parameters

itemType

The type of object to match.

Return Value

The new NSArray containing only matching elements.

Declared In

NSArray+Extensions.h