Class: NSArray

Inherits:
NSObject show all

Overview

NSArray and its subclass NSMutableArray manage ordered collections of objects called arrays. NSArray creates static arrays, and NSMutableArray creates dynamic arrays. You can use arrays when you need an ordered collection of objects.

Direct Known Subclasses

NSMutableArray

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (Object) array

Creates and returns an empty array. This method is used by mutable subclasses of NSArray.

Returns:

  • (Object) —

    An empty array.

+ (Object) arrayWithArray(anArray)

Creates and returns an array containing the objects in another given array.

Parameters:

  • anArray (Array) —

    An array.

Returns:

  • (Object) —

    An array containing the objects in anArray.

+ (Object) arrayWithContentsOfFile(aPath)

Creates and returns an array containing the contents of the file specified by a given path. The array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this array are immutable, even if the array is mutable.

Parameters:

  • aPath (String) —

    The path to a file containing a string representation of an array produced by the writeToFile:atomically: method.

Returns:

  • (Object) —

    An array containing the contents of the file specified by aPath. Returns nil if the file can’t be opened or if the contents of the file can’t be parsed into an array.

+ (Object) arrayWithContentsOfURL(aURL)

Creates and returns an array containing the contents specified by a given URL. The array representation at the location identified by aURL must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). The objects contained by this array are immutable, even if the array is mutable.

Parameters:

  • aURL (NSURL) —

    The location of a file containing a string representation of an array produced by the writeToURL:atomically: method.

Returns:

  • (Object) —

    An array containing the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into an array.

+ (Object) arrayWithObject(anObject)

Creates and returns an array containing a given object.

Parameters:

  • anObject (Object) —

    An object.

Returns:

  • (Object) —

    An array containing the single element anObject.

+ (Object) arrayWithObjects(firstObj, ...)

Creates and returns an array containing the objects in the argument list. This code example creates an array containing three different types of element:

Parameters:

  • firstObj, (Object) —

    ... A comma-separated list of objects ending with nil.

Returns:

  • (Object) —

    An array containing the objects in the argument list.

+ (Object) arrayWithObjects(objects, count:count)

Creates and returns an array that includes a given number of objects from a given C array. Elements are added to the new array in the same order they appear in objects, up to but not including index count. For example:

Parameters:

  • objects (Object) —

    A C array of objects.

  • count (Integer) —

    The number of values from the objects C array to include in the new array. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.

Returns:

  • (Object) —

    A new array including the first count objects from objects.

Instance Method Details

- (Object) addObserver(observer, forKeyPath:keyPath, options:options, context:context)

Raises an exception.

Parameters:

  • observer (NSObject) —

    The object to register for KVO notifications. The observer must implement the key-value observing method observeValueForKeyPath:ofObject:change:context:.

  • keyPath (String) —

    The key path, relative to the array, of the property to observe. This value must not be nil.

  • options (NSKeyValueObservingOptions) —

    A combination of NSKeyValueObservingOptions values that specifies what is included in observation notifications.

  • context (Object) —

    Arbitrary data that is passed to observer in observeValueForKeyPath:ofObject:change:context:.

Returns:

- (Object) addObserver(anObserver, toObjectsAtIndexes:indexes, forKeyPath:keyPath, options:options, context:context)

Registers an observer to receive key value observer notifications for the specified key-path relative to the objects at the indexes. The options determine what is included in the notifications, and the context is passed in the notifications. This is not merely a convenience method; invoking this method is potentially much faster than repeatedly invoking addObserver:forKeyPath:options:context:.

Parameters:

  • anObserver (NSObject) —

    The observer.

  • indexes (NSIndexSet) —

    The index set.

  • keyPath (String) —

    The key path, relative to the array, to be observed.

  • options (NSKeyValueObservingOptions) —

    The options to be included in the notification.

  • context (Object) —

    The context passed to the notifications.

Returns:

- (Array) arrayByAddingObject(anObject)

Returns a new array that is a copy of the receiving array with a given object added to the end. If anObject is nil, an NSInvalidArgumentException is raised.

Parameters:

  • anObject (Object) —

    An object.

Returns:

  • (Array) —

    A new array that is a copy of the receiving array with anObject added to the end.

- (Array) arrayByAddingObjectsFromArray(otherArray)

Returns a new array that is a copy of the receiving array with the objects contained in another array added to the end.

Parameters:

  • otherArray (Array) —

    An array.

Returns:

  • (Array) —

    A new array that is a copy of the receiving array with the objects contained in otherArray added to the end.

- (String) componentsJoinedByString(separator)

Constructs and returns an NSString object that is the result of interposing a given separator between the elements of the array. For example, this code excerpt writes "here be dragons" to the console:

Parameters:

  • separator (String) —

    The string to interpose between the elements of the array.

Returns:

  • (String) —

    An NSString object that is the result of interposing separator between the elements of the array. If the array has no elements, returns an NSString object representing an empty string.

- (Boolean) containsObject(anObject)

Returns a Boolean value that indicates whether a given object is present in the array. This method determines whether anObject is present in the array by sending an isEqual: message to each of the array’s objects (and passing anObject as the parameter to each isEqual: message).

Parameters:

  • anObject (Object) —

    An object.

Returns:

  • (Boolean) —

    YES if anObject is present in the array, otherwise NO.

- (Integer) count

Returns the number of objects currently in the array.

Returns:

  • (Integer) —

    The number of objects currently in the array.

- (String) description

Returns a string that represents the contents of the array, formatted as a property list.

Returns:

  • (String) —

    A string that represents the contents of the array, formatted as a property list.

- (String) descriptionWithLocale(locale)

Returns a string that represents the contents of the array, formatted as a property list. For a description of how locale is applied to each element in the receiving array, see descriptionWithLocale:indent:.

Parameters:

  • locale (Object) —

    An NSLocale object or an NSDictionary object that specifies options used for formatting each of the array’s elements (where recognized). Specify nil if you don’t want the elements formatted.

Returns:

  • (String) —

    A string that represents the contents of the array, formatted as a property list.

- (String) descriptionWithLocale(locale, indent:level)

Returns a string that represents the contents of the array, formatted as a property list. The returned NSString object contains the string representations of each of the array’s elements, in order, from first to last. To obtain the string representation of a given element, descriptionWithLocale:indent: proceeds as follows:If the element is an NSString object, it is used as is. If the element responds to descriptionWithLocale:indent:, that method is invoked to obtain the element’s string representation. If the element responds to descriptionWithLocale:, that method is invoked to obtain the element’s string representation. If none of the above conditions is met, the element’s string representation is obtained by invoking its description method.

Parameters:

  • locale (Object) —

    An NSLocale object or an NSDictionary object that specifies options used for formatting each of the array’s elements (where recognized). Specify nil if you don’t want the elements formatted.

  • level (Integer) —

    A level of indent, to make the output more readable: set level to 0 to use four spaces to indent, or 1 to indent the output with a tab character.

Returns:

  • (String) —

    A string that represents the contents of the array, formatted as a property list.

- (Object) enumerateObjectsAtIndexes(indexSet, options:opts, usingBlock:block)

Executes a given block using the objects in the array at the specified indexes. By default, the enumeration starts with the first object and continues serially through the array to the last element specified by indexSet. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.Important: If the Block parameter or the indexSet is nil this method will raise an exception.

Parameters:

  • indexSet —

    The indexes of the objects over which to enumerate.

  • opts —

    A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

  • block —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

- (Object) enumerateObjectsUsingBlock(block)

Executes a given block using each object in the array, starting with the first object and continuing through the array to the last object. If the Block parameter is nil this method will raise an exception.

Parameters:

  • block —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

- (Object) enumerateObjectsWithOptions(opts, usingBlock:block)

Executes a given block using each object in the array. By default, the enumeration starts with the first object and continues serially through the array to the last object. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.Important: If the Block parameter is nil this method will raise an exception.

Parameters:

  • opts —

    A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

  • block —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

- (Array) filteredArrayUsingPredicate(predicate)

Evaluates a given predicate against each object in the receiving array and returns a new array containing the objects for which the predicate returns true. For more details, see Predicate Programming Guide.

Parameters:

  • predicate (NSPredicate) —

    The predicate against which to evaluate the receiving array’s elements.

Returns:

  • (Array) —

    A new array containing the objects in the receiving array for which predicate returns true.

- (Object) firstObjectCommonWithArray(otherArray)

Returns the first object contained in the receiving array that’s equal to an object in another given array. This method uses isEqual: to check for object equality.

Parameters:

  • otherArray (Array) —

    An array.

Returns:

  • (Object) —

    Returns the first object contained in the receiving array that’s equal to an object in otherArray. If no such object is found, returns nil.

- (Object) getObjects(aBuffer, range:aRange)

Copies the objects contained in the array that fall within the specified range to aBuffer. The method copies into aBuffer the objects in the array in the range specified by aRange; the size of the buffer must therefore be at least the length of the range multiplied by the size of an object reference, as shown in the following example (this is solely for illustration—you should typically not create a buffer simply to iterate over the contents of an array):

Parameters:

  • aBuffer (Object) —

    A C array of objects of size at least the length of the range specified by aRange.

  • aRange (NSRange) —

    A range within the bounds of the array.If the location plus the length of the range is greater than the count of the array, this method raises an NSRangeException.

Returns:

- (NSIndexSet) indexesOfObjectsAtIndexes(indexSet, options:opts, passingTest:predicate)

Returns the indexes, from a given set of indexes, of objects in the array that pass a test in a given Block for a given set of enumeration options. By default, the enumeration starts with the first object and continues serially through the array to the last element specified by indexSet. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.Important: If the Block parameter or the indexSet is nil this method will raise an exception.

Parameters:

  • indexSet —

    The indexes of the objects over which to enumerate.

  • opts —

    A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

  • predicate —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (NSIndexSet) —

    The indexes whose corresponding values in the array pass the test specified by predicate. If no objects in the array pass the test, returns an empty index set.

- (NSIndexSet) indexesOfObjectsPassingTest(predicate)

Returns the indexes of objects in the array that pass a test in a given Block.

Parameters:

  • predicate —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (NSIndexSet) —

    The indexes whose corresponding values in the array pass the test specified by predicate. If no objects in the array pass the test, returns an empty index set.

- (NSIndexSet) indexesOfObjectsWithOptions(opts, passingTest:predicate)

Returns the indexes of objects in the array that pass a test in a given Block for a given set of enumeration options. By default, the enumeration starts with the first object and continues serially through the array to the last object. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.Important: If the Block parameter is nil this method will raise an exception.

Parameters:

  • opts —

    A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

  • predicate —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (NSIndexSet) —

    The indexes whose corresponding values in the array pass the test specified by predicate. If no objects in the array pass the test, returns an empty index set.

- (Integer) indexOfObject(anObject)

Returns the lowest index whose corresponding array value is equal to a given object. Starting at index 0, each element of the array is sent an isEqual: message until a match is found or the end of the array is reached. This method passes the anObject parameter to each isEqual: message. Objects are considered equal if isEqual: (declared in the NSObject protocol) returns YES.

Parameters:

  • anObject (Object) —

    An object.

Returns:

  • (Integer) —

    The lowest index whose corresponding array value is equal to anObject. If none of the objects in the array is equal to anObject, returns NSNotFound.

- (Integer) indexOfObject(anObject, inRange:range)

Returns the lowest index within a specified range whose corresponding array value is equal to a given object . Starting at index 0, each element of the array is sent an isEqual: message until a match is found or the end of the array is reached. This method passes the anObject parameter to each isEqual: message. Objects are considered equal if isEqual: returns YES.This method raises an NSRangeException exception if the range parameter represents a range that doesn’t exist in the array.

Parameters:

  • anObject (Object) —

    An object.

  • range (NSRange) —

    The range of indexes in the array within which to search for anObject.

Returns:

  • (Integer) —

    The lowest index within range whose corresponding array value is equal to anObject. If none of the objects within range is equal to anObject, returns NSNotFound.

- (Integer) indexOfObject(obj, inSortedRange:r, options:opts, usingComparator:cmp)

Returns the index, within a specified range, of an object compared with elements in the array using a given NSComparator block.

Parameters:

  • obj (Object) —

    An object for which to search in the array.If this value is nil, throws an NSInvalidArgumentException.

  • r (NSRange) —

    The range within the array to search for obj.If r exceeds the bounds of the array (if the location plus length of the range is greater than the count of the array), throws an NSRangeException.

  • opts (NSBinarySearchingOptions) —

    Options for the search. For possible values, see “NSBinarySearchingOptions.”If you specify both NSBinarySearchingFirstEqual and NSBinarySearchingLastEqual, throws an NSInvalidArgumentException.

  • cmp (NSComparator) —

    A comparator block used to compare the object obj with elements in the array.If this value is NULL, throws an NSInvalidArgumentException.

Returns:

  • (Integer) —

    If the NSBinarySearchingInsertionIndex option is not specified:If the NSBinarySearchingInsertionIndex option is specified, returns the index at which you should insert obj in order to maintain a sorted array:

- (Integer) indexOfObjectAtIndexes(indexSet, options:opts, passingTest:predicate)

Returns the index, from a given set of indexes, of the first object in the array that passes a test in a given Block for a given set of enumeration options. By default, the enumeration starts with the first object and continues serially through the array to the last element specified by indexSet. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.Important: If the Block parameter or indexSet is nil this method will raise an exception.

Parameters:

  • indexSet —

    The indexes of the objects over which to enumerate.

  • opts —

    A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

  • predicate —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (Integer) —

    The lowest index whose corresponding value in the array passes the test specified by predicate. If no objects in the array pass the test, returns NSNotFound.

- (Integer) indexOfObjectIdenticalTo(anObject)

Returns the lowest index whose corresponding array value is identical to a given object. Objects are considered identical if their object addresses are the same.

Parameters:

  • anObject (Object) —

    An object.

Returns:

  • (Integer) —

    The lowest index whose corresponding array value is identical to anObject. If none of the objects in the array is identical to anObject, returns NSNotFound.

- (Integer) indexOfObjectIdenticalTo(anObject, inRange:range)

Returns the lowest index within a specified range whose corresponding array value is equal to a given object . Objects are considered identical if their object addresses are the same.

Parameters:

  • anObject (Object) —

    An object.

  • range (NSRange) —

    The range of indexes in the array within which to search for anObject.

Returns:

  • (Integer) —

    The lowest index within range whose corresponding array value is identical to anObject. If none of the objects within range is identical to anObject, returns NSNotFound.

- (Integer) indexOfObjectPassingTest(predicate)

Returns the index of the first object in the array that passes a test in a given Block. If the Block parameter is nil this method will raise an exception.

Parameters:

  • predicate —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (Integer) —

    The lowest index whose corresponding value in the array passes the test specified by predicate. If no objects in the array pass the test, returns NSNotFound.

- (Integer) indexOfObjectWithOptions(opts, passingTest:predicate)

Returns the index of an object in the array that passes a test in a given Block for a given set of enumeration options. By default, the enumeration starts with the first object and continues serially through the array to the last object. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.Important: If the Block parameter is nil this method will raise an exception.

Parameters:

  • opts —

    A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

  • predicate —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the array.idxThe index of the element in the array.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the array.

  • idx —

    The index of the element in the array.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (Integer) —

    The index whose corresponding value in the array passes the test specified by predicate and opts. If the opts bitmask specifies reverse order, then the last item that matches is returned. Otherwise, the index of the first matching object is returned. If no objects in the array pass the test, returns NSNotFound.

- (Object) initWithArray(anArray)

Initializes a newly allocated array by placing in it the objects contained in a given array. After an immutable array has been initialized in this way, it cannot be modified.

Parameters:

  • anArray (Array) —

    An array.

Returns:

  • (Object) —

    An array initialized to contain the objects in anArray. The returned object might be different than the original receiver.

- (Object) initWithArray(array, copyItems:flag)

Initializes a newly allocated array using anArray as the source of data objects for the array. After an immutable array has been initialized in this way, it cannot be modified.The copyWithZone: method performs a shallow copy. If you have a collection of arbitrary depth, passing YES for the flag parameter will perform an immutable copy of the first level below the surface. If you pass NO the mutability of the first level is unaffected. In either case, the mutability of all deeper levels is unaffected.

Parameters:

  • array (Array) —

    An array containing the objects with which to initialize the new array.

  • flag (Boolean) —

    If YES, each object in array receives a copyWithZone: message to create a copy of the object—objects must conform to the NSCopying protocol. In a managed memory environment, this is instead of the retain message the object would otherwise receive. The object copy is then added to the returned array.If NO, then in a managed memory environment each object in array simply receives a retain message when it is added to the returned array.

Returns:

  • (Object) —

    An array initialized to contain the objects—or if flag is YES, copies of the objects—in array. The returned object might be different than the original receiver.

- (Object) initWithContentsOfFile(aPath)

Initializes a newly allocated array with the contents of the file specified by a given path. The array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). The objects contained by this array are immutable, even if the array is mutable.

Parameters:

  • aPath (String) —

    The path to a file containing a string representation of an array produced by the writeToFile:atomically: method.

Returns:

  • (Object) —

    An array initialized to contain the contents of the file specified by aPath or nil if the file can’t be opened or the contents of the file can’t be parsed into an array. The returned object might be different than the original receiver.

- (Object) initWithContentsOfURL(aURL)

Initializes a newly allocated array with the contents of the location specified by a given URL. The array representation at the location identified by aURL must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). The objects contained by this array are immutable, even if the array is mutable.

Parameters:

  • aURL (NSURL) —

    The location of a file containing a string representation of an array produced by the writeToURL:atomically: method.

Returns:

  • (Object) —

    An array initialized to contain the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into an array. The returned object might be different than the original receiver.

- (Object) initWithObjects(firstObj, ...)

Initializes a newly allocated array by placing in it the objects in the argument list. After an immutable array has been initialized in this way, it can’t be modified.

Parameters:

  • firstObj, (Object) —

    … A comma-separated list of objects ending with nil.

Returns:

  • (Object) —

    An array initialized to include the objects in the argument list. The returned object might be different than the original receiver.

- (Object) initWithObjects(objects, count:count)

Initializes a newly allocated array to include a given number of objects from a given C array. Elements are added to the new array in the same order they appear in objects, up to but not including index count.After an immutable array has been initialized in this way, it can’t be modified.

Parameters:

  • objects (Object) —

    A C array of objects.

  • count (Integer) —

    The number of values from the objects C array to include in the new array. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.

Returns:

  • (Object) —

    A newly allocated array including the first count objects from objects. The returned object might be different than the original receiver.

- (Boolean) isEqualToArray(otherArray)

Compares the receiving array to another array. Two arrays have equal contents if they each hold the same number of objects and objects at a given index in each array satisfy the isEqual: test.

Parameters:

  • otherArray (Array) —

    An array.

Returns:

  • (Boolean) —

    YES if the contents of otherArray are equal to the contents of the receiving array, otherwise NO.

- (Object) lastObject

Returns the object in the array with the highest index value.

Returns:

  • (Object) —

    The object in the array with the highest index value. If the array is empty, returns nil.

- (Object) makeObjectsPerformSelector(aSelector)

Sends to each object in the array the message identified by a given selector, starting with the first object and continuing through the array to the last object. This method raises an NSInvalidArgumentException if aSelector is NULL.

Parameters:

  • aSelector (Symbol) —

    A selector that identifies the message to send to the objects in the array. The method must not take any arguments, and must not have the side effect of modifying the receiving array.

Returns:

- (Object) makeObjectsPerformSelector(aSelector, withObject:anObject)

Sends the aSelector message to each object in the array, starting with the first object and continuing through the array to the last object. This method raises an NSInvalidArgumentException if aSelector is NULL.

Parameters:

  • aSelector (Symbol) —

    A selector that identifies the message to send to the objects in the array. The method must take a single argument of type id, and must not have the side effect of modifying the receiving array.

  • anObject (Object) —

    The object to send as the argument to each invocation of the aSelector method.

Returns:

- (Object) objectAtIndex(index)

Returns the object located at index. If index is beyond the end of the array (that is, if index is greater than or equal to the value returned by count), an NSRangeException is raised.

Parameters:

  • index (Integer) —

    An index within the bounds of the array.

Returns:

  • (Object) —

    The object located at index.

- (Object) objectAtIndexedSubscript(idx)

Returns the object at the specified index. If index is beyond the end of the array (that is, if index is greater than or equal to the value returned by count), an NSRangeException is raised.This method is identical to objectAtIndex:.

Parameters:

  • idx (Integer) —

    An index within the bounds of the array.

Returns:

  • (Object) —

    The object located at index.

- (NSEnumerator) objectEnumerator

Returns an enumerator object that lets you access each object in the array. Returns an enumerator object that lets you access each object in the array, in order, starting with the element at index 0, as in:

Returns:

  • (NSEnumerator) —

    An enumerator object that lets you access each object in the array, in order, from the element at the lowest index upwards.

- (Array) objectsAtIndexes(indexes)

Returns an array containing the objects in the array at the indexes specified by a given index set. The returned objects are in the ascending order of their indexes in indexes, so that object in returned array with higher index in indexes will follow the object with smaller index in indexes.Raises an NSRangeException if any location in indexes exceeds the bounds of the array, of if indexes is nil.

Returns:

  • (Array) —

    An array containing the objects in the array at the indexes specified by indexes.

- (Array) pathsMatchingExtensions(filterTypes)

Returns an array containing all the pathname elements in the receiving array that have filename extensions from a given array.

Parameters:

  • filterTypes (Array) —

    An array of NSString objects containing filename extensions. The extensions should not include the dot (“.”) character.

Returns:

  • (Array) —

    An array containing all the pathname elements in the receiving array that have filename extensions from the filterTypes array.

- (Object) removeObserver(observer, forKeyPath:keyPath)

Raises an exception.

Parameters:

  • observer (NSObject) —

    The object to remove as an observer.

  • keyPath (String) —

    A key-path, relative to the array, for which observer is registered to receive KVO change notifications. This value must not be nil.

Returns:

- (Object) removeObserver(observer, forKeyPath:keyPath, context:context)

Raises an exception.

Parameters:

  • observer (NSObject) —

    The object to remove as an observer.

  • keyPath (String) —

    A key-path, relative to the set, for which observer is registered to receive KVO change notifications. This value must not be nil.

  • context (Object) —

    The context passed to the notifications.

Returns:

- (Object) removeObserver(anObserver, fromObjectsAtIndexes:indexes, forKeyPath:keyPath)

Removes anObserver from all key value observer notifications associated with the specified keyPath relative to the array’s objects at indexes. This is not merely a convenience method; invoking this method is potentially much faster than repeatedly invoking removeObserver:forKeyPath:.

Parameters:

  • anObserver (NSObject) —

    The observer.

  • indexes (NSIndexSet) —

    The index set.

  • keyPath (String) —

    The key path, relative to the array, to be observed.

Returns:

- (Object) removeObserver(observer, fromObjectsAtIndexes:indexes, forKeyPath:keyPath, context:context)

Raises an exception.

Parameters:

  • observer —

    The object to remove as an observer.

  • keyPath —

    A key-path, relative to the array, for which observer is registered to receive KVO change notifications. This value must not be nil.

  • context —

    The context passed to the notifications.

Returns:

- (NSEnumerator) reverseObjectEnumerator

Returns an enumerator object that lets you access each object in the array, in reverse order.

Returns:

  • (NSEnumerator) —

    An enumerator object that lets you access each object in the array, in order, from the element at the highest index down to the element at index 0.

- (Object) setValue(value, forKey:key)

Invokes setValue:forKey: on each of the array's items using the specified value and key.

Parameters:

  • value (Object) —

    The object value.

  • key (String) —

    The key to store the value.

Returns:

- (NSData) sortedArrayHint

Analyzes the array and returns a “hint” that speeds the sorting of the array when the hint is supplied to sortedArrayUsingFunction:context:hint:.

Returns:

- (Array) sortedArrayUsingComparator(cmptr)

Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given NSComparator Block.

Parameters:

  • cmptr (NSComparator) —

    A comparator block.

Returns:

  • (Array) —

    An array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified cmptr.

- (Array) sortedArrayUsingDescriptors(sortDescriptors)

Returns a copy of the receiving array sorted as specified by a given array of sort descriptors. The first descriptor specifies the primary key path to be used in sorting the receiving array’s contents. Any subsequent descriptors are used to further refine sorting of objects with duplicate values. See NSSortDescriptor for additional information.

Parameters:

Returns:

  • (Array) —

    A copy of the receiving array sorted as specified by sortDescriptors.

- (Array) sortedArrayUsingFunction(comparator, context:context)

Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function comparator. The new array contains references to the receiving array’s elements, not copies of them.The comparison function is used to compare two elements at a time and should return NSOrderedAscending if the first element is smaller than the second, NSOrderedDescending if the first element is larger than the second, and NSOrderedSame if the elements are equal. Each time the comparison function is called, it’s passed context as its third argument. This allows the comparison to be based on some outside parameter, such as whether character sorting is case-sensitive or case-insensitive.Given anArray (an array of NSNumber objects) and a comparison function of this type: A sorted version of anArray is created in this way:

Returns:

- (Array) sortedArrayUsingFunction(comparator, context:context, hint:hint)

Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function comparator. The new array contains references to the receiving array’s elements, not copies of them.This method is similar to sortedArrayUsingFunction:context:, except that it uses the supplied hint to speed the sorting process. When you know the array is nearly sorted, this method is faster than sortedArrayUsingFunction:context:. If you sorted a large array (N entries) once, and you don’t change it much (P additions and deletions, where P is much smaller than N), then you can reuse the work you did in the original sort by conceptually doing a merge sort between the N “old” items and the P “new” items.To obtain an appropriate hint, use sortedArrayHint. You should obtain this hint when the original array has been sorted, and keep hold of it until you need it, after the array has been modified. The hint is computed by sortedArrayHint in O(N) (where N is the number of items). This assumes that items in the array implement a -hash method. Given a suitable hint, and assuming that the hash function is a “good” hash function, -sortedArrayUsingFunction:context:hint: sorts the array in O(P*LOG(P)+N) where P is the number of adds or deletes. This is an improvement over the un-hinted sort, O(N*LOG(N)), when P is small.The hint is simply an array of size N containing the N hashes. To re-sort you need internally to create a map table mapping a hash to the index. Using this map table on the new array, you can get a first guess for the indices, and then sort that. For example, a sorted array B, D, E, F with corresponding hash values 96, 78, 32, 17, may be subject to small changes that result in contents A, C, B, F. The mapping table maps the hashes 96, 78, 32, 17 to the indices #1, #2, #3, #4. If the hashes for A, C, B, F are 25, 99, 96, 17, then by using the mapping table you can get a first order sort #0, ?, #1, #4, so therefore create an initial semi-sorted array B, E, F, and then perform a cheap merge sort with C that yields B, C, E, F.

Returns:

- (Array) sortedArrayUsingSelector(comparator)

Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given selector. The new array contains references to the receiving array’s elements, not copies of them.The comparator message is sent to each object in the array and has as its single argument another object in the array. For example, an array of NSString objects can be sorted by using the caseInsensitiveCompare: method declared in the NSString class. Assuming anArray exists, a sorted version of the array can be created in this way:

Parameters:

  • comparator (Symbol) —

    A selector that identifies the method to use to compare two elements at a time. The method should return NSOrderedAscending if the receiving array is smaller than the argument, NSOrderedDescending if the receiving array is larger than the argument, and NSOrderedSame if they are equal.

Returns:

  • (Array) —

    An array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by the selector comparator.

- (Array) sortedArrayWithOptions(opts, usingComparator:cmptr)

Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given NSComparator Block.

Parameters:

  • opts (NSSortOptions) —

    A bitmask that specifies the options for the sort (whether it should be performed concurrently and whether it should be performed stably).

  • cmptr (NSComparator) —

    A comparator block.

Returns:

  • (Array) —

    An array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified cmptr.

- (Array) subarrayWithRange(range)

Returns a new array containing the receiving array’s elements that fall within the limits specified by a given range. If range isn’t within the receiving array’s range of elements, an NSRangeException is raised.For example, the following code example creates an array containing the elements found in the first half of wholeArray (assuming wholeArray exists).

Parameters:

  • range (NSRange) —

    A range within the receiving array’s range of elements.

Returns:

  • (Array) —

    A new array containing the receiving array’s elements that fall within the limits specified by range.

- (Object) valueForKey(key)

Returns an array containing the results of invoking valueForKey: using key on each of the array's objects.

The returned array contains NSNull elements for each object that returns nil.

Parameters:

  • key (String) —

    The key to retrieve.

Returns:

  • (Object) —

    The value of the retrieved key.

- (Boolean) writeToFile(path, atomically:flag)

Writes the contents of the array to a file at a given path. If the array’s contents are all property list objects (NSString, NSData, NSArray, or NSDictionary objects), the file written by this method can be used to initialize a new array with the class method arrayWithContentsOfFile: or the instance method initWithContentsOfFile:. This method recursively validates that all the contained objects are property list objects before writing out the file, and returns NO if all the objects are not property list objects, since the resultant file would not be a valid property list.

Parameters:

  • path (String) —

    The path at which to write the contents of the array.If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

  • flag (Boolean) —

    If YES, the array is written to an auxiliary file, and then the auxiliary file is renamed to path. If NO, the array is written directly to path. The YES option guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.

Returns:

  • (Boolean) —

    YES if the file is written successfully, otherwise NO.

- (Boolean) writeToURL(aURL, atomically:flag)

Writes the contents of the array to the location specified by a given URL. If the array’s contents are all property list objects (NSString, NSData, NSArray, or NSDictionary objects), the location written by this method can be used to initialize a new array with the class method arrayWithContentsOfURL: or the instance method initWithContentsOfURL:.

Parameters:

  • aURL (NSURL) —

    The location at which to write the array.

  • flag (Boolean) —

    If YES, the array is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If NO, the array is written directly to aURL. The YES option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing.

Returns:

  • (Boolean) —

    YES if the location is written successfully, otherwise NO.