Up

NSArray class reference

Authors

Andrew Kachites McCallum (mccallum@gnu.ai.mit.edu)
Adam Fedor (fedor@boulder.colorado.edu)
Richard Frith-Macdonald (richard@brainstorm.co.uk)

Version: 1.138

Date: 2004/01/28 07:33:20

Copyright: (C) 1995, 1996, 1998 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSArray class
  2. Software documentation for the NSMutableArray class
  3. Software documentation for the NSArray(GNUstep) category

Software documentation for the NSArray class

NSArray : NSObject

Declared in:
Foundation/NSArray.h
Conforms to:
NSCoding
NSCopying
NSMutableCopying
Standards:

A simple, low overhead, ordered container for objects. All the objects in the container are retained by it. The container may not contain nil (though it may contain [NSNull +null] ).

Method summary

array 

+ (id) array;

Returns an empty autoreleased array.


arrayWithArray: 

+ (id) arrayWithArray: (NSArray*)array;

Returns a new autoreleased NSArray instance containing all the objects from array , in the same order as the original.


arrayWithContentsOfFile: 

+ (id) arrayWithContentsOfFile: (NSString*)file;

Returns an autoreleased array based upon the file. The new array is created using +allocWithZone: and initialised using the -initWithContentsOfFile: method. See the documentation for those methods for more detail.


arrayWithContentsOfURL: 

+ (id) arrayWithContentsOfURL: (NSURL*)aURL;

Returns an autoreleased array from the contenta of aURL. The new array is created using +allocWithZone: and initialised using the -initWithContentsOfURL: method. See the documentation for those methods for more detail.


arrayWithObject: 

+ (id) arrayWithObject: (id)anObject;

Returns an autoreleased array containing anObject.


arrayWithObjects: ,...

+ (id) arrayWithObjects: (id)firstObject,...;

Returns an autoreleased array containing the list of objects, preserving order.


arrayWithObjects: count: 

+ (id) arrayWithObjects: (id*)objects count: (unsigned)count;

Returns an autoreleased array containing the specified objects, preserving order.


arrayByAddingObject: 

- (NSArray*) arrayByAddingObject: (id)anObject;

Returns an autoreleased array formed from the contents of the receiver and adding anObject as the last item.


arrayByAddingObjectsFromArray: 

- (NSArray*) arrayByAddingObjectsFromArray: (NSArray*)anotherArray;

Returns a new array which is the concatenation of self and otherArray (in this precise order).


componentsJoinedByString: 

- (NSString*) componentsJoinedByString: (NSString*)separator;

Returns a string formed by concatenating the objects in the receiver, with the specified separator string inserted between each part.


containsObject: 

- (BOOL) containsObject: (id)anObject;

Returns YES if anObject belongs to self. No otherwise.
The -isEqual: method of anObject is used to test for equality.


count 

- (unsigned) count;
Subclasses should override this method.

Returns the number of elements contained in the receiver.


description 

- (NSString*) description;

Returns the result of invoking -descriptionWithLocale:indent: with a nil locale and zero indent.


descriptionWithLocale: 

- (NSString*) descriptionWithLocale: (NSDictionary*)locale;

Returns the result of invoking -descriptionWithLocale:indent: with a zero indent.


descriptionWithLocale: indent: 

- (NSString*) descriptionWithLocale: (NSDictionary*)locale indent: (unsigned int)level;

Returns the receiver as a text property list in the traditional format.
See [NSString -propertyList] for details.
If locale is nil, no formatting is done, otherwise entries are formatted according to the locale, and indented according to level.
Unless locale is nil, a level of zero indents items by four spaces, while a level of one indents them by a tab.
The items in the property list string appear in the same order as they appear in the receiver.


firstObjectCommonWithArray: 

- (id) firstObjectCommonWithArray: (NSArray*)otherArray;

Returns the first object found in the receiver (starting at index 0) which is present in the otherArray as determined by using the -containsObject: method.


getObjects: 

- (void) getObjects: (id*)aBuffer;

Copies the objects from the receiver to aBuffer, which must be an area of memory large enough to hold them.


getObjects: range: 

- (void) getObjects: (id*)aBuffer range: (NSRange)aRange;

Copies the objects from the range aRange of the receiver to aBuffer, which must be an area of memory large enough to hold them.


indexOfObject: 

- (unsigned) indexOfObject: (id)anObject;

Returns the index of the first object found in the receiver which is equal to anObject (using anObject's -isEqual: method). Returns NSNotFound on failure.


indexOfObject: inRange: 

- (unsigned) indexOfObject: (id)anObject inRange: (NSRange)aRange;

Returns the index of the first object found in aRange of receiver which is equal to anObject (using anObject's -isEqual: method). Returns NSNotFound on failure.


indexOfObjectIdenticalTo: 

- (unsigned) indexOfObjectIdenticalTo: (id)anObject;

Returns the index of the specified object in the receiver, or NSNotFound if the object is not present.


indexOfObjectIdenticalTo: inRange: 

- (unsigned) indexOfObjectIdenticalTo: (id)anObject inRange: (NSRange)aRange;

Returns the index of the specified object in the range of the receiver, or NSNotFound if the object is not present.


initWithArray: 

- (id) initWithArray: (NSArray*)array;

Initialize the receiver with the contents of array. The order of array is preserved.
Invokes -initWithObjects:count:


initWithArray: copyItems: 

- (id) initWithArray: (NSArray*)array copyItems: (BOOL)shouldCopy;

Initialize the receiver with the contents of array. The order of array is preserved.
If shouldCopy is YES then the objects are copied rather than simply retained.
Invokes -initWithObjects:count:


initWithContentsOfFile: 

- (id) initWithContentsOfFile: (NSString*)file;

Initialises the array with the contents of the specified file, which must contain an array in property-list format.

In GNUstep, the property-list format may be either the OpenStep format (ASCII data), or the MacOS-X format (URF8 XML data)... this method will recognise which it is.

If there is a failure to load the file for any reason, the receiver will be released, the method will return nil, and a warning may be logged.

Works by invoking [NSString -initWithContentsOfFile:] and [NSString -propertyList] then checking that the result is an array.


initWithContentsOfURL: 

- (id) initWithContentsOfURL: (NSURL*)aURL;

Initialises the array with the contents of the specified URL, which must contain an array in property-list format.

In GNUstep, the property-list format may be either the OpenStep format (ASCII data), or the MacOS-X format (URF8 XML data)... this method will recognise which it is.

If there is a failure to load the URL for any reason, the receiver will be released, the method will return nil, and a warning may be logged.

Works by invoking [NSString -initWithContentsOfURL:] and [NSString -propertyList] then checking that the result is an array.


initWithObjects: ,...

- (id) initWithObjects: (id)firstObject,...;

Initialize the array the list of objects.
May change the value of self before returning it.


initWithObjects: count: 

- (id) initWithObjects: (id*)objects count: (unsigned)count;
This is a designated initialiser for the class.

Initialize the array with count objects.
Retains each object placed in the array.
Like all initializers, may change the value of self before returning it.


isEqualToArray: 

- (BOOL) isEqualToArray: (NSArray*)otherArray;

Returns YES if the receiver is equal to otherArray, NO otherwise.


lastObject 

- (id) lastObject;

Returns the last object in the receiver, or nil if the receiver is empty.


makeObjectsPerform: 

- (void) makeObjectsPerform: (SEL)aSelector;

Obsolete version of -makeObjectsPerformSelector:


makeObjectsPerform: withObject: 

- (void) makeObjectsPerform: (SEL)aSelector withObject: (id)argument;

Obsolete version of -makeObjectsPerformSelector:withObject:


makeObjectsPerformSelector: 

- (void) makeObjectsPerformSelector: (SEL)aSelector;

Makes each object in the array perform aSelector.
This is done sequentially from the last to the first object.


makeObjectsPerformSelector: withObject: 

- (void) makeObjectsPerformSelector: (SEL)aSelector withObject: (id)arg;

Makes each object in the array perform aSelector with arg.
This is done sequentially from the last to the first object.


objectAtIndex: 

- (id) objectAtIndex: (unsigned)index;
Subclasses should override this method.

Returns the object at the specified index. Raises an exception of the index is beyond the array.


objectEnumerator 

- (NSEnumerator*) objectEnumerator;

Returns an enumerator describing the array sequentially from the first to the last element.
If you use a mutable subclass of NSArray, you should not modify the array during enumeration.


pathsMatchingExtensions: 

- (NSArray*) pathsMatchingExtensions: (NSArray*)extensions;

Assumes that the receiver is an array of paths, and returns an array formed by selecting the subset of those patch matching the specified array of extensions.


reverseObjectEnumerator 

- (NSEnumerator*) reverseObjectEnumerator;

Returns an enumerator describing the array sequentially from the last to the first element.
If you use a mutable subclass of NSArray, you should not modify the array during enumeration.


sortedArrayHint 

- (NSData*) sortedArrayHint;

Subclasses may provide a hint for sorting... The default GNUstep implementation just returns nil.


sortedArrayUsingFunction: context: 

- (NSArray*) sortedArrayUsingFunction: (NSComparisonResult(*)(id,id,void*))comparator context: (void*)context;

Returns an autoreleased array in which the objects are ordered according to a sort with comparator. This invokes -sortedArrayUsingFunction:context:hint: with a nil hint.


sortedArrayUsingFunction: context: hint: 

- (NSArray*) sortedArrayUsingFunction: (NSComparisonResult(*)(id,id,void*))comparator context: (void*)context hint: (NSData*)hint;

Returns an autoreleased array in which the objects are ordered according to a sort with comparator, where the comparator function is passed two objects to compare, and the copntext as the third argument.


sortedArrayUsingSelector: 

- (NSArray*) sortedArrayUsingSelector: (SEL)comparator;

Returns an autoreleased array in which the objects are ordered according to a sort with comparator.


subarrayWithRange: 

- (NSArray*) subarrayWithRange: (NSRange)aRange;

Returns a subarray of the receiver containing the objects found in the specified range aRange.


valueForKey: 

- (id) valueForKey: (NSString*)key;

This overrides NSObjects implementation of this method. This method returns an array of objects returned by invoking -valueForKey: for each item in the receiver, substituting NSNull for nil. A special case: the key "count" is not forwarded to each object of the receiver but returns the number of objects of the receiver.


writeToFile: atomically: 

- (BOOL) writeToFile: (NSString*)path atomically: (BOOL)useAuxiliaryFile;

Writes the contents of the array to the file specified by path. The file contents will be in property-list format... under GNUstep this is either OpenStep style (ASCII characters using \U hexadecimal escape sequences for unicode), or MacOS-X style (XML in the UTF8 character set).

If the useAuxiliaryFile flag is YES, the file write operation is atomic... the data is written to a temporary file, which is then renamed to the actual file name.

If the conversion of data into the correct property-list format fails or the write operation fails, the method returns NO, otherwise it returns YES.

NB. The fact that the file is in property-list format does not necessarily mean that it can be used to reconstruct the array using the -initWithContentsOfFile: method. If the original array contains non-property-list objects, the descriptions of those objects will have been written, and reading in the file as a property-list will result in a new array containing the string descriptions.


writeToURL: atomically: 

- (BOOL) writeToURL: (NSURL*)url atomically: (BOOL)useAuxiliaryFile;

Writes the contents of the array to the specified url. This functions just like -writeToFile:atomically: except that the output may be written to any URL, not just a local file.


Software documentation for the NSMutableArray class

NSMutableArray : NSArray

Declared in:
Foundation/NSArray.h
Standards:

Description forthcoming.

Method summary

arrayWithCapacity: 

+ (id) arrayWithCapacity: (unsigned)numItems;

Creates an autoreleased mutable array anble to store at least numItems. See the -initWithCapacity: method.


addObject: 

- (void) addObject: (id)anObject;
Subclasses should override this method.

Adds anObject at the end of the array, thus increasing the size of the array. The object is retained upon addition.


addObjectsFromArray: 

- (void) addObjectsFromArray: (NSArray*)otherArray;

Adds each object from otherArray to the receiver, in first to last order.


exchangeObjectAtIndex: withObjectAtIndex: 

- (void) exchangeObjectAtIndex: (unsigned int)i1 withObjectAtIndex: (unsigned int)i2;

Swaps the positions of two objects in the array. Raises an exception if either array index is out of bounds.


initWithCapacity: 

- (id) initWithCapacity: (unsigned)numItems;
This is a designated initialiser for the class.

Initialise the array with the specified capacity ... this should ensure that the array can have numItems added efficiently.


insertObject: atIndex: 

- (void) insertObject: (id)anObject atIndex: (unsigned)index;
Subclasses should override this method.

Inserts an object into the receiver at the specified location.
Raises an exception if given an array index which is too large.
The size of the array increases by one.
The object is retained by the array.


removeAllObjects 

- (void) removeAllObjects;

Removes all objects from the receiver, leaving an empty array.


removeLastObject 

- (void) removeLastObject;

Removes the last object in the array. Raises an exception if the array is already empty.


removeObject: 

- (void) removeObject: (id)anObject;

Removes all occurrances of anObject (found by anObjects -isEqual: method) from the receiver.


removeObject: inRange: 

- (void) removeObject: (id)anObject inRange: (NSRange)aRange;

Removes all occurrances of anObject (found by the -isEqual: method of anObject) aRange in the receiver.


removeObjectAtIndex: 

- (void) removeObjectAtIndex: (unsigned)index;
Subclasses should override this method.

Removes an object from the receiver at the specified location.
The size of the array decreases by one.
Raises an exception if given an array index which is too large.


removeObjectIdenticalTo: 

- (void) removeObjectIdenticalTo: (id)anObject;

Removes all occurrances of anObject (found by pointer equality) from the receiver.


removeObjectIdenticalTo: inRange: 

- (void) removeObjectIdenticalTo: (id)anObject inRange: (NSRange)aRange;

Removes all occurrances of anObject (found by pointer equality) from aRange in the receiver.


removeObjectsFromIndices: numIndices: 

- (void) removeObjectsFromIndices: (unsigned*)indices numIndices: (unsigned)count;

Supplied with a C array of indices containing count values, this method removes all corresponding objects from the receiver. The objects are removed in such a way that the removal is safe irrespective of the order in which they are specified in the indices array.


removeObjectsInArray: 

- (void) removeObjectsInArray: (NSArray*)otherArray;

Removes from the receiver, all the objects present in otherArray, as determined by using the -isEqual: method.


removeObjectsInRange: 

- (void) removeObjectsInRange: (NSRange)aRange;

Removes all the objects in aRange from the receiver.


replaceObjectAtIndex: withObject: 

- (void) replaceObjectAtIndex: (unsigned)index withObject: (id)anObject;
Subclasses should override this method.

Places an object into the receiver at the specified location.
Raises an exception if given an array index which is too large.
The object is retained by the array.


replaceObjectsInRange: withObjectsFromArray: 

- (void) replaceObjectsInRange: (NSRange)aRange withObjectsFromArray: (NSArray*)anArray;

Replaces objects in the receiver with those from anArray.
Raises an exception if given a range extending beyond the array.


replaceObjectsInRange: withObjectsFromArray: range: 

- (void) replaceObjectsInRange: (NSRange)aRange withObjectsFromArray: (NSArray*)anArray range: (NSRange)anotherRange;

Replaces objects in the receiver with some of those from anArray.
Raises an exception if given a range extending beyond the array.


setArray: 

- (void) setArray: (NSArray*)otherArray;

Sets the contents of the receiver to be identical to the contents of othrArray.


setValue: forKey: 

- (void) setValue: (id)value forKey: (NSString*)key;

Call setValue:forKey: on each of the receiver's items with the value and key.


sortUsingFunction: context: 

- (void) sortUsingFunction: (NSComparisonResult(*)(id,id,void*))compare context: (void*)context;

Sorts the array according to the supplied compare function with the context information.


sortUsingSelector: 

- (void) sortUsingSelector: (SEL)comparator;

Sorts the array according to the supplied comparator.


Software documentation for the NSArray(GNUstep) category

NSArray(GNUstep)

Declared in:
Foundation/NSArray.h
Standards:

Description forthcoming.

Method summary

insertionPosition: usingFunction: context: 

- (unsigned) insertionPosition: (id)item usingFunction: (NSComparisonResult(*)(id,id,void*))sorter context: (void*)context;

Locate the correct insertion position for item where the receiver is a sorted array witch was sorted using the sorter function.
The comparator function takes two items as arguments, the first is the item to be added, the second is the item already in the array. The function should return NSOrderedAscending if the item to be added is 'less than' the item in the array, NSOrderedDescending if it is greater, and NSOrderedSame if it is equal.


insertionPosition: usingSelector: 

- (unsigned) insertionPosition: (id)item usingSelector: (SEL)comp;

Locate the correct insertion position for item where the receiver is a sorted array which was sorted using the comp selector.



Up