- Inherits from:
- NSObject
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
- NSObject (NSObject)
Declared in:
- Foundation/NSArray.h
An NSArray stores an immutable array of objects.
+ 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
- + array
- + arrayWithArray:
- + arrayWithContentsOfFile:
- + arrayWithObject:
- + arrayWithObjects:
- + arrayWithObjects:count:
- - initWithArray:
- - initWithContentsOfFile:
- - initWithContentsOfURL:
- - 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:
- - writeToURL:atomically:
- Working with array elements
- - exchangeObjectAtIndex:withObjectAtIndex:
+ (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)arrayWithContentsOfURL:(NSURL
*)anURL
Returns nil if the location can't be opened or if the contents of the location can't be parsed into an array.
See Also: - writeToURL: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 in 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 protocol)
- (unsigned)count
See Also: - objectAtIndex:
- (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)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:
- (void)exchangeObjectAtIndex:(unsigned)idx1
withObjectAtIndex:(unsigned)idx2
- (id)firstObjectCommonWithArray:(NSArray
*)otherArray
nil
.
This method uses isEqual: to check for object equality. See Also: - containsObject:, isEqual: (NSObject protocol)
- (void)getObjects:(id
*)aBuffer
See Also: + arrayWithObjects:count:
- (void)getObjects:(id
*)aBuffer
range:(NSRange)aRange
See Also: + arrayWithObjects:count:
- (unsigned)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 protocol)
- (unsigned)indexOfObject:(id)anObject
inRange:(NSRange)range
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 protocol)
- (unsigned)indexOfObjectIdenticalTo:(id)anObject
See Also: - containsObject:, - indexOfObject:
- (unsigned)indexOfObjectIdenticalTo:(id)anObject
inRange:(NSRange)range
See Also: - containsObject:, - indexOfObject:inRange:
- (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: + arrayWithContentsOfFile:, - writeToFile:atomically:
- (id)initWithContentsOfURL:(NSURL
*)anURL
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: + arrayWithContentsOfURL:, - writeToURL:atomically:
- (id)initWithObjects:(id)firstObj,
...
See Also: - initWithObjects:count:, + arrayWithObjects:, - initWithArray:
- (id)initWithObjects:(id
*)objects
count:(unsigned)count
See Also: - initWithObjects:, + arrayWithObjects:, - initWithArray:
- (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 protocol)
- (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)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
tiff
"
or "eps
"). Filenames
that don't have an extension aren't included in the result.
This method can be used to identify those files with a particular
extension (or set of extensions) within a directory.- (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 *))comparator
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:
- (BOOL)writeToURL:(NSURL
*)anURL
atomically:(BOOL)atomically
If flag is YES
,
the array is written to an auxiliary location, and then the auxiliary
location is renamed to anURL. If flag is NO
,
the array is written directly to anURL.
The YES
option guarantees that anURL,
if it exists at all, won't be corrupted even if the system should
crash during writing.
This method returns YES
if
the location is written successfully, and NO
otherwise.
See Also: - initWithContentsOfURL: