Inherits from: NSObject
Conforms to: NSCoding
NSCopying
NSMutableCopying
NSObject (NSObject)
Declared in: Foundation/NSArray.h
+ array | Returns an empty array. |
+ arrayWithArray: | Returns an array containing the elements from another array. |
+ arrayWithContentsOfFile: | Returns an array initialized from the contents of a file. |
+ arrayWithObject: | Returns an array containing a single object. |
+ arrayWithObjects: | Returns an array containing multiple objects. |
+ arrayWithObjects:count: | Returns an array containing a specified number of objects. |
- count | Returns the number of objects currently in the array. |
- objectAtIndex: | Returns the object located at the specified index. |
NSArray and its subclass NSMutableArray manage collections of objects called arrays. NSArray creates static arrays and NSMutableArray creates dynamic arrays.
NSArray and NSMutableArray are part of a class cluster, so arrays are not actual instances of the NSArray or NSMutableArray classes but of one of their private subclasses. Although an array's class is private, its interface is public, as declared by these abstract superclasses, NSArray and NSMutableArray.
Generally, you instantiate an array by sending one of the array... messages
to either the NSArray or NSMutableArray class object. These methods
return an array containing the elements you pass in as arguments.
(Note that arrays can't contain nil
.)
In general, objects that you add to an array aren't copied; rather,
each object receives a retain message before its id is
added to the array. When an object is removed from an array, it's
sent a release message.
The NSArray and NSMutableArray classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert an array of one type to the other.
NSArray's two primitive methods- count and objectAtIndex:-provide the basis for all other methods in its interface. The count method returns the number of elements in the array. objectAtIndex: gives you access to the array elements by index, with index values starting at 0.
The methods objectEnumerator and reverseObjectEnumerator also grant sequential access to the elements of the array, differing only in the direction of travel through the elements. These methods are provided so that arrays can be traversed in a manner similar to that used for objects of other collection classes, such as NSDictionary. See the objectEnumerator method description for a code excerpt that shows how to use these methods to access the elements of an array.
NSArray provides methods for querying the elements of the array. indexOfObject: searches the array for the object that matches its argument. To determine whether the search is successful, each element of the array is sent an isEqual: message, as declared in the NSObject protocol. Another method, indexOfObjectIdenticalTo:, is provided for the less common case of determining whether a specific object is present in the array. indexOfObjectIdenticalTo: tests each element in the array to see whether its id matches that of the argument.
NSArray's makeObjectsPerformSelector: and makeObjectsPerformSelector:withObject:methods let you send messages to all objects in the array. To act on the array as a whole, a variety of other methods are defined. You can create a sorted version of the array ( sortedArrayUsingSelector: and sortedArrayUsingFunction:context:), extract a subset of the array ( subarrayWithRange:), or concatenate the elements of an array of NSStrings into a single string ( componentsJoinedByString:). In addition, you can compare two arrays using the isEqualToArray: and firstObjectCommonWithArray: methods. Finally, you can create new arrays that contain the objects in an existing array and one or more additional objects with arrayByAddingObject: and arrayByAddingObjectsFromArray:.
- NSCoding
- - encodeWithCoder:
- - initWithCoder:
- NSCopying
- - copyWithZone:
- NSMutableCopying
- - mutableCopyWithZone:
- Creating an array
- + allocWithZone:
- + array
- + arrayWithArray:
- + arrayWithContentsOfFile:
- + arrayWithObject:
- + arrayWithObjects:
- + arrayWithObjects:count:
- - initWithArray:
- - initWithContentsOfFile:
- - initWithObjects:
- - initWithObjects:count:
- Querying the array
- - containsObject:
- - count
- - getObjects:
- - getObjects:range:
- - indexOfObject:
- - indexOfObject:inRange:
- - indexOfObjectIdenticalTo:
- - indexOfObjectIdenticalTo:inRange:
- - lastObject
- - objectAtIndex:
- - objectEnumerator
- - reverseObjectEnumerator
- Sending messages to elements
- - makeObjectsPerformSelector:
- - makeObjectsPerformSelector:withObject:
- Comparing arrays
- - firstObjectCommonWithArray:
- - isEqualToArray:
- Deriving new arrays
- - arrayByAddingObject:
- - arrayByAddingObjectsFromArray:
- - sortedArrayHint
- - sortedArrayUsingFunction:context:
- - sortedArrayUsingFunction:context:hint:
- - sortedArrayUsingSelector:
- - subarrayWithRange:
- Working with string elements
- - componentsJoinedByString:
- - pathsMatchingExtensions:
- Creating a description of the array
- - description
- - descriptionWithLocale:
- - descriptionWithLocale:indent:
- - writeToFile:atomically:
+ (id)allocWithZone:(NSZone
*)zone
Typically, you create temporary arrays using the array... class methods, not the allocWithZone: and init... methods. Note that it's your responsibility to free objects created with the allocWithZone: method.
+ (id)array
See Also: + arrayWithObject:, + arrayWithObjects:
+ (id)arrayWithArray:(NSArray
*)anArray
See Also: + arrayWithObjects:, - initWithObjects:
+ (id)arrayWithContentsOfFile:(NSString
*)aPath
Returns nil if the file can't be opened or if the contents of the file can't be parsed into an array.
See Also: - writeToFile:atomically:
+ (id)arrayWithObject:(id)anObject
See Also: + array, + arrayWithObjects:
+ (id)arrayWithObjects:(id)firstObj,
...
This code example creates an array containing three different types of elements (assuming aPath exists):
NSArray *myArray; NSData *someData = [NSData dataWithContentsOfFile:aPath]; NSValue *aValue = [NSNumber numberWithInt:5]; NSString *aString = @"a string"; myArray = [NSArray arrayWithObjects:someData, aValue, aString, nil];
See Also: + array, + arrayWithObject:
+ (id)arrayWithObjects:(id
*)objects count:(unsigned)count
See Also: - getObjects:, - getObjects:range:
- (NSArray *)arrayByAddingObject:(id)anObject
nil
,
an NSInvalidArgumentException is raised.See Also: - addObject: (NSMutableArray)
- (NSArray *)arrayByAddingObjectsFromArray:(NSArray
*)otherArray
See Also: - addObjectsFromArray: (NSMutableArray)
- (NSString *)componentsJoinedByString:(NSString
*)separator
/System/Developer
to
the console: NSArray *pathArray = [NSArray arrayWithObjects:@"System", @"Developer", nil]; NSLog("The path is /%@.\n", [pathArray componentsJoinedByString:@"/"]);
Each element of the receiver's array must handle description. If the receiver has no elements, an NSString representing an empty string is returned.
See Also: - componentsSeparatedByString: (NSString)
- (BOOL)containsObject:(id)anObject
See Also: - indexOfObject:, - indexOfObjectIdenticalTo:, - isEqual: (NSObject)
- (unsigned int)count
See Also: - objectAtIndex:
@protocol NSObject
- (NSString *)description
See Also: - descriptionWithLocale:, - descriptionWithLocale:indent:
- (NSString *)descriptionWithLocale:(NSDictionary
*)locale
For a description of how locale is applied to each element in the receiving array, see descriptionWithLocale:indent:.
See Also: - description, - descriptionWithLocale:indent:
- (NSString *)descriptionWithLocale:(NSDictionary
*)locale indent:(unsigned int)level
The returned NSString contains the string representations of each of the receiver's elements, in order, from first to last. To obtain the string representation of a given element, descriptionWithLocale:indent: proceeds as follows:
See Also: - description, - descriptionWithLocale:
- (id)firstObjectCommonWithArray:(NSArray
*)otherArray
nil
.
This method uses isEqual: to check for object
equality. See Also: - containsObject:, - isEqual: (NSObject)
- (void)getObjects:(id
*)aBuffer
See Also: + arrayWithObjects:count:
- (void)getObjects:(id
*)aBuffer range:(NSRange)aRange
See Also: + arrayWithObjects:count:
@protocol NSObject
- (unsigned int)hash
See Also: - isEqual: (NSObject)
- (unsigned int)indexOfObject:(id)anObject
YES
.
If none of the objects in the receiver are equal to anObject, indexOfObject: returns NSNotFound.See Also: - containsObject:, - indexOfObjectIdenticalTo:, - isEqual: (NSObject)
- (unsigned int)indexOfObject:(id)anObject inRange:(NSRange)aRange
YES
.
If none of the objects in the specified range are equal to anObject, indexOfObject:inRange: returns
NSNotFound.See Also: - containsObject:, - indexOfObjectIdenticalTo:inRange:, - isEqual: (NSObject)
- (unsigned int)indexOfObjectIdenticalTo:(id)anObject
- containsObject:, - indexOfObject:, - isEqual: (NSObject)
- (unsigned int)indexOfObjectIdenticalTo:(id)anObject inRange:(NSRange)aRange
- containsObject:, - indexOfObject:inRange:, - isEqual: (NSObject)
- (id)initWithArray:(NSArray
*)anArray
See Also: + arrayWithObject:, - initWithObjects:
- (id)initWithContentsOfFile:(NSString
*)aPath
Returns self if the receiver is successfully initialized, or nil if the file can't be opened or the contents of the file can't be parsed into an array.
See Also: - writeToFile:atomically:
- (id)initWithObjects:(id)firstObj,
...
See Also: - initWithObjects:count:, + arrayWithObjects:, - initWithArray:
- (id)initWithObjects:(id
*)objects count:(unsigned
int)count
See Also: - initWithObjects:, + arrayWithObjects:, - initWithArray:
@protocol NSObject
- (BOOL)isEqual:(id)anObject
YES
if
the receiver and anObject are equal;
otherwise returns NO
. A YES
return
value indicates that the receiver and anObject are
both instances of classes that inherit from NSArray and they both
contain the same objects (as determined by the isEqualToArray: method).See Also: - isEqualToArray:
- (BOOL)isEqualToArray:(NSArray
*)otherArray
YES
.
If not, it returns NO
.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.
See Also: - isEqual: (NSObject)
- (id)lastObject
nil
. See Also: - removeLastObject (NSMutableArray)
- (void)makeObjectsPerformSelector:(SEL)aSelector
See Also: - makeObjectsPerformSelector:withObject:
- (void)makeObjectsPerformSelector:(SEL)aSelector withObject:(id)anObject
See Also: - makeObjectsPerformSelector:
- (id)objectAtIndex:(unsigned
int)index
See Also: - count
- (NSEnumerator *)objectEnumerator
NSEnumerator *enumerator = [myArray objectEnumerator]; id anObject; while ((anObject = [enumerator nextObject])) { /* code to act on each element as it is returned */ }
When this method is used with mutable subclasses of NSArray, your code shouldn't modify the array during enumeration.
See Also: - reverseObjectEnumerator, - nextObject (NSEnumerator)
- (NSArray *)pathsMatchingExtensions:(NSArray
*)filterTypes
- (NSEnumerator *)reverseObjectEnumerator
See Also: - objectEnumerator, - nextObject (NSEnumerator)
- (NSData *)sortedArrayHint
- (NSArray *)sortedArrayUsingFunction:
(int(*)(id, id, void *))comparator context:(void
*)context
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:
int intSort(id num1, id num2, void *context) { int v1 = [num1 intValue]; int v2 = [num2 intValue]; if (v1 < v2) return NSOrderedAscending; else if (v1 > v2) return NSOrderedDescending; else return NSOrderedSame; }
A sorted version of anArray is created in this way:
NSArray *sortedArray; sortedArray = [anArray sortedArrayUsingFunction:intSort context:NULL];
See Also: - sortedArrayUsingSelector:
- (NSArray *)sortedArrayUsingFunction:
(int (*)(id, id, void *))compare
context:(void *)context hint:(NSData
*)hint
- (NSArray *)sortedArrayUsingSelector:(SEL)comparator
The comparator message is sent to each object in the array, and has as its single argument another object in the array. The comparator method is used to compare two elements at a time and should return NSOrderedAscending if the receiver is smaller than the argument, NSOrderedDescending if the receiver is larger than the argument, and NSOrderedSame if they are equal.
For example, an array of NSStrings can be sorted by using the compare: method declared in the NSString class. Assuming anArray exists, a sorted version of the array can be created in this way:
NSArray *sortedArray = [anArray sortedArrayUsingSelector:@selector(compare:)];
See Also: - sortedArrayUsingFunction:context:
- (NSArray *)subarrayWithRange:(NSRange)range
For example, the following code example creates an array containing the elements found in the first half of wholeArray (assuming wholeArray exists).
NSArray *halfArray; NSRange theRange; theRange.location = 0; theRange.length = [wholeArray count] / 2; halfArray = [wholeArray subarrayWithRange:theRange];
- (BOOL)writeToFile:(NSString
*)path atomically:(BOOL)flag
If flag is YES
,
the array is written to an auxiliary file, and then the auxiliary
file is renamed to path. If flag is 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.
If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath: before invoking this method.
This method returns YES
if
the file is written successfully, and NO
otherwise.
See Also: - initWithContentsOfFile: