mccallum@gnu.ai.mit.edu
)fedor@boulder.colorado.edu
)richard@brainstorm.co.uk
)Version: 1.144
Date: 2005/02/22 11:22:43
Copyright: (C) 1995, 1996, 1998 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSArray.h
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
Standards:
- MacOS-X
- OpenStep
- GNUstep
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]
).
Returns an empty autoreleased array.
Returns a new autoreleased NSArray instance containing all the objects from array , in the same order as the original.
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.
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.
Returns an autoreleased array containing anObject.
Returns an autoreleased array containing the list of objects, preserving order.
Returns an autoreleased array containing the specified objects, preserving order.
Returns an autoreleased array formed from the contents of the receiver and adding anObject as the last item.
Returns a new array which is the concatenation of self and otherArray (in this precise order).
Returns a string formed by concatenating the objects in the receiver, with the specified separator string inserted between each part.
Returns YES
if anObject
belongs to self. No otherwise.
The
-isEqual:
method of anObject is used to test for
equality.
Returns the number of elements contained in the receiver.
Returns the result of invoking
-descriptionWithLocale:indent:
with a nil
locale and zero indent.
Returns the result of invoking -descriptionWithLocale:indent: with a zero indent.
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.
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.
Copies the objects from the receiver to aBuffer, which must be an area of memory large enough to hold them.
Copies the objects from the range aRange of the receiver to aBuffer, which must be an area of memory large enough to hold them.
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.
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.
Returns the index of the specified object in the receiver, or NSNotFound if the object is not present.
Returns the index of the specified object in the range of the receiver, or NSNotFound if the object is not present.
In MacOS-X class clusters do not have designated initialisers, and there is a general rule that -init is treated as the designated initialiser of the class cluster, but that other intitialisers may not work s expected an would need to be individually overridden in any subclass.
GNUstep tries to make it easier to subclass a class cluster, by making class clusters follow the same convention as normal classes, so the designated initialiser is the richest initialiser. This means that all other initialisers call the documented designated initialiser (which calls -init only for MacOS-X compatibility), and anyone writing a subclass only needs to override that one initialiser in order to have all the other ones work.
For MacOS-X compatibility, you may also need to override various other initialisers. Exactly which ones, you will need to determine by trial on a MacOS-X system... and may vary between releases of MacOS-X. So to be safe, on MacOS-X you probably need to re-implement all the class cluster initialisers you might use in conjunction with your subclass.
Initialize the receiver with the contents of
array. The order of array is
preserved.
Invokes
-initWithObjects:count:
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:
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 (UTF-8 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.
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.
Initialize the array the list of objects.
May change the value of self before returning it.
This should initialize the array with count
(may be zero) objects.
Retains each
object placed in the array.
Calls
-init
(which does nothing but maintain MacOS-X
compatibility), and needs to be
re-implemented in subclasses in order to
have all other initialisers work.
Returns YES
if the receiver is equal
to otherArray, NO
otherwise.
Returns the last object in the receiver, or
nil
if the receiver is empty.
Obsolete version of -makeObjectsPerformSelector:
Obsolete version of -makeObjectsPerformSelector:withObject:
Makes each object in the array perform
aSelector.
This is done
sequentially from the first to the last
object.
Makes each object in the array perform
aSelector with arg.
This
is done sequentially from the first to the last object.
Returns the object at the specified index. Raises an exception of the index is beyond the array.
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.
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.
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.
Subclasses may provide a hint for sorting... The
default GNUstep implementation just returns
nil
.
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.
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 context as the third
argument. The hint argument is
currently ignored, and may be nil
.
Returns an autoreleased array in which the objects are ordered according to a sort with comparator.
Returns a subarray of the receiver containing the objects found in the specified range aRange.
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.
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.
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.
- Declared in:
- Foundation/NSArray.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
NSMutableArray
is the mutable version of
NSArray
. It provides methods for altering the contents of the
array.
Creates an autoreleased mutable array anble to store at least numItems. See the -initWithCapacity: method.
Adds anObject at the end of the array, thus increasing the size of the array. The object is retained upon addition.
Adds each object from otherArray to the receiver, in first to last order.
Swaps the positions of two objects in the array. Raises an exception if either array index is out of bounds.
Initialise the array with the specified capacity
... this should ensure that the array can have
numItems added efficiently.
Calls
-init
(which does nothing but maintain MacOS-X
compatibility), and needs to be
re-implemented in subclasses in order to
have all other initialisers work.
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.
Removes all objects from the receiver, leaving an empty array.
Removes the last object in the array. Raises an exception if the array is already empty.
Removes all occurrences of anObject (found by anObjects -isEqual: method) from the receiver.
Removes all occurrences of anObject (found by the -isEqual: method of anObject) aRange in the receiver.
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.
Removes all occurrences of anObject (found by pointer equality) from the receiver.
Removes all occurrances of anObject (found by pointer equality) from aRange in the receiver.
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.
Removes from the receiver, all the objects present in otherArray, as determined by using the -isEqual: method.
Removes all the objects in aRange from the receiver.
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.
Replaces objects in the receiver with those from
anArray.
Raises an exception if
given a range extending beyond the array.
Replaces objects in the receiver with some of
those from anArray.
Raises an
exception if given a range extending beyond the
array.
Sets the contents of the receiver to be identical to the contents of othrArray.
Call setValue:forKey: on each of the receiver's items with the value and key.
Sorts the array according to the supplied compare function with the context information.
Sorts the array according to the supplied comparator.
- Declared in:
- Foundation/NSArray.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
NSArray enhancements provided by GNUstep.
Method summary
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.
Locate the correct insertion position for item where the receiver is a sorted array which was sorted using the comp selector.