NSArray Mac OS X 10.0

This class manages an immutable ordered collection of objects. Objects are stored in an array by reference. That is, the pointer to the object is stored rather than the object itself. When the object is added to an array, the array retains it by sending a retain message to the object. When the array is released it sends a release message to each of its members.

There are many methods for querying the contents of the array. The method objectAtIndex: is commonly used to access an object at some position in the array. Conversely, we can determine the index of some object using the method indexOfObject:, which returns the lowest index of the member that is equivalent the specified object. To determine the number of objects contained within the array the count method is invoked.

To enumerate the contents of an array, create an NSEnumerator object for the array using one of two methods: objectEnumerator or reverseObjectEnumerator. A standard object enumerator will return the objects in the order that they exist within the array, while the reverse enumerator will return members starting from the last object and working its way forward. See the NSEnumerator class description for more information on enumerating collections.

Often we want to invoke some method in each member of a collection. NSArray provides a method that saves us from the burden of having to enumerate the contents of the array and send the message manually. This method is makeObjectsPerformSelector:, which will cause the method matching the selector to be invoked in each member of the collection. If you need to invoke a method that takes an argument, then use the method makeObjectsPerformSelector:withObject:.

NSArray is an immutable class. The class NSMutableArray supports ordered collections whose contents can be changed after initialization.

NSArray is toll-free bridged with the Core Foundation type CFArray. As such, NSArray objects can be used interchangeably with the CFArray pointer type, CFArrayRef.


@interface NSArray : NSObject <NSCoding, NSCopying, NSMutableCopying>
 // Convenience Constructors
   + (id)array;
   + (id)arrayWithArray:(NSArray *)array;
   + (id)arrayWithContentsOfFile:(NSString *)path;
   + (id)arrayWithContentsOfURL:(NSURL *)url;
   + (id)arrayWithObject:(id)anObject;
   + (id)arrayWithObjects:(id *)objs count:(unsigned)cnt;
   + (id)arrayWithObjects:(id)firstObj, ...;
 // Initializers
   - (id)initWithArray:(NSArray *)array;
   - (id)initWithArray:(NSArray *)array copyItems:(BOOL)flag;
   - (id)initWithContentsOfFile:(NSString *)path;
   - (id)initWithContentsOfURL:(NSURL *)url;
   - (id)initWithObjects:(id *)objects count:(unsigned)count;
   - (id)initWithObjects:(id)firstObj, ...;
 // Instance Methods
   - (NSArray *)arrayByAddingObject:(id)anObject;
   - (NSArray *)arrayByAddingObjectsFromArray:(NSArray *)otherArray;
   - (NSString *)componentsJoinedByString:(NSString *)separator;
   - (BOOL)containsObject:(id)anObject;
   - (unsigned)count;
   - (NSString *)description;
   - (NSString *)descriptionWithLocale:(NSDictionary *)locale;
   - (NSString *)descriptionWithLocale:(NSDictionary *)locale indent:(unsigned)level;
   - (id)firstObjectCommonWithArray:(NSArray *)otherArray;
   - (void)getObjects:(id *)objects;
   - (void)getObjects:(id *)objects range:(NSRange)range;
   - (unsigned)indexOfObject:(id)anObject;
   - (unsigned)indexOfObject:(id)anObject  inRange:(NSRange)range;
   - (unsigned)indexOfObjectIdenticalTo:(id)anObject;
   - (unsigned)indexOfObjectIdenticalTo:(id)anObject inRange:(NSRange)range;
   - (BOOL)isEqualToArray:(NSArray *)otherArray;
   - (id)lastObject;
   - (void)makeObjectsPerformSelector:(SEL)aSelector;
   - (void)makeObjectsPerformSelector:(SEL)aSelector withObject:(id)argument;
   - (id)objectAtIndex:(unsigned)index;
   - (NSEnumerator *)objectEnumerator;
   - (NSArray *)pathsMatchingExtensions:(NSArray *)filterTypes;
   - (NSEnumerator *)reverseObjectEnumerator;
   - (NSData *)sortedArrayHint;
   - (NSArray *)sortedArrayUsingFunction:(int (*)(id, id, void *))comparator context:(void *)context;
   - (NSArray *)sortedArrayUsingFunction:(int (*)(id, id, void *))comparator context:(void *)
        context hint:(NSData *)hint;
   - (NSArray *)sortedArrayUsingSelector:(SEL)comparator;
   - (NSArray *)subarrayWithRange:(NSRange)range;
   - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;
   - (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically;
 // Methods Implementing NSCoding
   - (void)encodeWithCoder:(NSCoder *)aCoder;
   - (id)initWithCoder:(NSCoder *)aDecoder;
 // Methods Implementing NSCopying
   - (id)copyWithZone:(NSZone *)zone;
 // Methods Implementing NSMutableCopying
   - (id)mutableCopyWithZone:(NSZone *)zone;



    Part II: API Quick Reference
    Chapter 13. Foundation Classes