Up
Authors
- Andrew Kachites McCallum (
mccallum@gnu.ai.mit.edu
)
-
- Adam Fedor (
fedor@boulder.colorado.edu
)
-
- Richard Frith-Macdonald (
richard@brainstorm.co.uk
)
-
Version: 38855
Date: 2015-08-05 02:34:49 -0600 (Wed, 05 Aug 2015)
Copyright: (C) 1995-2015 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSArray.h
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
- NSFastEnumeration
Availability: OpenStep
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
+ (id)
array;
Availability: OpenStep
Returns an empty autoreleased array.
+ (id)
arrayWithArray: (
NSArray*)array;
Availability: OpenStep
Returns a new autoreleased NSArray instance
containing all the objects from array
, in the same order as the original.
+ (id)
arrayWithContentsOfFile: (
NSString*)file;
Availability: OpenStep
+ (id)
arrayWithContentsOfURL: (
NSURL*)aURL;
Availability: MacOS-X 10.0.0
+ (id)
arrayWithObject: (id)anObject;
Availability: OpenStep
Returns an autoreleased array containing
anObject.
+ (id)
arrayWithObjects: (id)firstObject
,...;
Availability: OpenStep
Returns an autoreleased array containing the list
of objects, preserving order.
+ (id)
arrayWithObjects: (const id[])objects
count: (
NSUInteger)count;
Availability: OpenStep
Returns an autoreleased array containing the
specified objects, preserving order.
- (
NSArray*)
arrayByAddingObject: (id)anObject;
Availability: OpenStep
Returns an autoreleased array formed from the
contents of the receiver and adding
anObject as the last item.
- (
NSArray*)
arrayByAddingObjectsFromArray: (
NSArray*)anotherArray;
Availability: OpenStep
Returns a new array which is the concatenation of
self and otherArray (in this precise order).
- (
NSString*)
componentsJoinedByString: (
NSString*)separator;
Availability: OpenStep
Returns a string formed by concatenating the
objects in the receiver, with the specified
separator string inserted between each
part.
- (BOOL)
containsObject: (id)anObject;
Availability: OpenStep
Returns YES
if anObject
belongs to self. No otherwise.
The
[NSObject -isEqual:]
method of anObject is used to test for
equality.
- (
NSUInteger)
count;
Availability: OpenStep
Subclasses
must override this method.
Returns the number of elements contained in the
receiver.
- (
NSString*)
description;
Availability: OpenStep
- (
NSString*)
descriptionWithLocale: (id)locale;
Availability: OpenStep
- (
NSString*)
descriptionWithLocale: (id)locale
indent: (
NSUInteger)level;
Availability: OpenStep
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.
- (void)
enumerateObjectsAtIndexes: (
NSIndexSet*)indexSet
options: (
NSEnumerationOptions)opts
usingBlock: (GSEnumeratorBlock)block;
Availability: MacOS-X 10.6.0
Enumerate over the specified indexes in the
collection using the given block. The
first argument is the object and the second is the
index in the array. The final argument is a pointer
to a BOOL indicating whether the enumeration should
stop. Setting this to YES
will interrupt
the enumeration. The opts argument is a
bitfield. Setting the NSNSEnumerationConcurrent
flag specifies that it is thread-safe. The
NSEnumerationReverse bit specifies
that it should be enumerated in reverse order.
- (void)
enumerateObjectsUsingBlock: (GSEnumeratorBlock)aBlock;
Availability: MacOS-X 10.6.0
Enumerate over the collection using the given
block. The first argument is the object and the
second is the index in the array. The final argument
is a pointer to a BOOL indicating whether the
enumeration should stop. Setting this to
YES
will interrupt the enumeration.
- (void)
enumerateObjectsWithOptions: (
NSEnumerationOptions)opts
usingBlock: (GSEnumeratorBlock)aBlock;
Availability: MacOS-X 10.6.0
Enumerate over the collection using the given
block. The first argument is the object and the
second is the index in the array. The final argument
is a pointer to a BOOL indicating whether the
enumeration should stop. Setting this to
YES
will interrupt the enumeration. The
opts argument is a bitfield. Setting the
NSNSEnumerationConcurrent flag
specifies that it is thread-safe. The
NSEnumerationReverse bit specifies
that it should be enumerated in reverse order.
- (id)
firstObject;
Availability: MacOS-X 10.6.0
Returns the first object in the receiver, or
nil
if the receiver is empty.
- (id)
firstObjectCommonWithArray: (
NSArray*)otherArray;
Availability: OpenStep
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.
- (void)
getObjects: (__unsafe_unretained id[])aBuffer;
Availability: OpenStep
Copies the objects from the receiver to
aBuffer, which must be an area of memory
large enough to hold them.
- (void)
getObjects: (__unsafe_unretained id[])aBuffer
range: (
NSRange)aRange;
Availability: OpenStep
Copies the objects from the range aRange
of the receiver to aBuffer, which must be an
area of memory large enough to hold them.
- (
NSUInteger)
indexOfObject: (id)anObject;
Availability: OpenStep
Returns the index of the first object found in the
receiver which is equal to anObject
(using anObject's
[NSObject -isEqual:]
method). Returns NSNotFound on failure.
- (
NSUInteger)
indexOfObject: (id)anObject
inRange: (
NSRange)aRange;
Availability: OpenStep
Returns the index of the first object found in
aRange of receiver which is equal to
anObject (using anObject's
[NSObject -isEqual:]
method). Returns NSNotFound on failure.
- (
NSUInteger)
indexOfObject: (id)key
inSortedRange: (
NSRange)range
options: (
NSBinarySearchingOptions)options
usingComparator: (NSComparator)comparator;
Availability: MacOS-X 10.6.0
Performs a binary search of the array within the
specified range for the index of an
object equal to obj according to cmp. If
NSBinarySearchingInsertionIndex
is specified, searches for the index at which such an
object should be inserted.
- (
NSUInteger)
indexOfObjectAtIndexes: (
NSIndexSet*)indexSet
options: (
NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
Availability: MacOS-X 10.6.0
Returns the index of the first object in the
specified range in a collection that matches the
condition specified by the block. The
opts argument is a bitfield. Setting the
NSNSEnumerationConcurrent flag
specifies that it is thread-safe. The
NSEnumerationReverse bit specifies
that it should be enumerated in reverse order.
- (
NSUInteger)
indexOfObjectIdenticalTo: (id)anObject;
Availability: OpenStep
Returns the index of the specified object in the
receiver, or NSNotFound if the object is not
present.
- (
NSUInteger)
indexOfObjectIdenticalTo: (id)anObject
inRange: (
NSRange)aRange;
Availability: OpenStep
Returns the index of the specified object in the
range of the receiver, or NSNotFound if the object is
not present.
- (
NSUInteger)
indexOfObjectPassingTest: (GSPredicateBlock)predicate;
Availability: MacOS-X 10.6.0
Returns the index of the first object in the array
that matches the condition specified by the block.
- (
NSUInteger)
indexOfObjectWithOptions: (
NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
Availability: MacOS-X 10.6.0
Returns the index of the first object in the array
that matches the condition specified by the block. The
opts argument is a bitfield. Setting the
NSNSEnumerationConcurrent flag
specifies that it is thread-safe. The
NSEnumerationReverse bit specifies
that it should be enumerated in reverse order.
- (
NSIndexSet*)
indexesOfObjectsAtIndexes: (
NSIndexSet*)indexSet
options: (
NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
Availability: MacOS-X 10.6.0
Returns the indexes of the objects in a collection
that match the condition specified by the block and
are in the range specified by the index set. The
opts argument is a bitfield. Setting the
NSNSEnumerationConcurrent flag
specifies that it is thread-safe. The
NSEnumerationReverse bit specifies
that it should be enumerated in reverse order.
- (
NSIndexSet*)
indexesOfObjectsPassingTest: (GSPredicateBlock)predicate;
Availability: MacOS-X 10.6.0
Returns the indexes of the objects in a collection
that match the condition specified by the block.
- (
NSIndexSet*)
indexesOfObjectsWithOptions: (
NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
Availability: MacOS-X 10.6.0
Returns the indexes of the objects in a collection
that match the condition specified by the block. The
opts argument is a bitfield. Setting the
NSNSEnumerationConcurrent flag
specifies that it is thread-safe. The
NSEnumerationReverse bit specifies
that it should be enumerated in reverse order.
- (id)
init;
Availability: OpenStep
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.
- (id)
initWithArray: (
NSArray*)array;
Availability: OpenStep
Initialize the receiver with the contents of
array. The order of
array is
preserved.
Invokes
-initWithObjects:count:
- (id)
initWithArray: (
NSArray*)array
copyItems: (BOOL)shouldCopy;
Availability: MacOS-X 10.0.0
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:
- (id)
initWithContentsOfFile: (
NSString*)file;
Availability: OpenStep
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.
- (id)
initWithContentsOfURL: (
NSURL*)aURL;
Availability: MacOS-X 10.0.0
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 (UTF8 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.
- (id)
initWithObjects: (id)firstObject
,...;
Availability: OpenStep
Initialize the array the list of objects.
May change the value of self before returning it.
- (id)
initWithObjects: (const id[])objects
count: (
NSUInteger)count;
Availability: OpenStep
This is a designated initialiser for the class.
Subclasses
must override this method.
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.
- (BOOL)
isEqualToArray: (
NSArray*)otherArray;
Availability: OpenStep
Returns YES
if the receiver is equal
to otherArray, NO
otherwise.
- (id)
lastObject;
Availability: OpenStep
Returns the last object in the receiver, or
nil
if the receiver is empty.
- (void)
makeObjectsPerform: (SEL)aSelector;
Availability: OPENSTEP 4.0.0 removed at MacOS-X 10.0.0
- (void)
makeObjectsPerform: (SEL)aSelector
withObject: (id)argument;
Availability: OPENSTEP 4.0.0 removed at MacOS-X 10.0.0
- (void)
makeObjectsPerformSelector: (SEL)aSelector;
Availability: MacOS-X 10.0.0
Makes each object in the array perform
aSelector.
This is done
sequentially from the first to the last
object.
- (void)
makeObjectsPerformSelector: (SEL)aSelector
withObject: (id)arg;
Availability: MacOS-X 10.0.0
Makes each object in the array perform
aSelector with arg.
This
is done sequentially from the first to the last object.
- (id)
objectAtIndex: (
NSUInteger)index;
Availability: OpenStep
Subclasses
must override this method.
Returns the object at the specified
index. Raises an exception of the
index is beyond the array.
- (id)
objectAtIndexedSubscript: (size_t)anIndex;
Availability: OpenStep
Accessor for subscripting. This is called by the
compiler when you write code like anArray[12]. It
should not be called directly.
- (
NSEnumerator*)
objectEnumerator;
Availability: OpenStep
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.
- (
NSArray*)
objectsAtIndexes: (
NSIndexSet*)indexes;
Availability: MacOS-X 10.4.0
Description forthcoming.
- (
NSArray*)
pathsMatchingExtensions: (
NSArray*)extensions;
Availability: OpenStep
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.
- (
NSEnumerator*)
reverseObjectEnumerator;
Availability: OpenStep
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.
- (void)
setValue: (id)value
forKey: (
NSString*)key;
Availability: MacOS-X 10.0.0
Call setValue:forKey: on each of the receiver's items
with the value and key.
- (
NSData*)
sortedArrayHint;
Availability: OpenStep
Subclasses may provide a hint for sorting... The
default GNUstep implementation just returns
nil
.
- (
NSArray*)
sortedArrayUsingComparator: (NSComparator)comparator;
Availability: MacOS-X 10.6.0
Returns a sorted array using the
comparator to determine the order of
objects.
- (
NSArray*)
sortedArrayUsingFunction: (NSComparisonResult(*)(id,id,void*))comparator
context: (void*)context;
Availability: OpenStep
- (
NSArray*)
sortedArrayUsingFunction: (NSComparisonResult(*)(id,id,void*))comparator
context: (void*)context
hint: (
NSData*)hint;
Availability: OpenStep
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
.
- (
NSArray*)
sortedArrayUsingSelector: (SEL)comparator;
Availability: OpenStep
Returns an autoreleased array in which the objects
are ordered according to a sort with
comparator.
- (
NSArray*)
sortedArrayWithOptions: (
NSSortOptions)options
usingComparator: (NSComparator)comparator;
Availability: MacOS-X 10.6.0
Returns a sorted array using the block to determine
the order of objects. The opts argument is a bitfield.
Setting the NSSortConcurrent flag specifies that it
is thread-safe. The NSSortStable bit specifies that it
should keep equal objects in the same order.
- (
NSArray*)
subarrayWithRange: (
NSRange)aRange;
Availability: OpenStep
Returns a subarray of the receiver containing the
objects found in the specified range
aRange.
- (id)
valueForKey: (
NSString*)key;
Availability: MacOS-X 10.0.0
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.
- (BOOL)
writeToFile: (
NSString*)path
atomically: (BOOL)useAuxiliaryFile;
Availability: OpenStep
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.
- (BOOL)
writeToURL: (
NSURL*)url
atomically: (BOOL)useAuxiliaryFile;
Availability: MacOS-X 10.0.0
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
Availability: OpenStep
NSMutableArray
is the mutable version of
NSArray
. It provides methods for altering the contents of the
array.
Method summary
+ (id)
arrayWithCapacity: (
NSUInteger)numItems;
Availability: OpenStep
Creates an autoreleased mutable array able to store
at least
numItems. See the
-initWithCapacity:
method.
- (void)
addObject: (id)anObject;
Availability: OpenStep
Subclasses
must override this method.
Adds anObject at the end of the array, thus
increasing the size of the array. The object is
retained upon addition.
- (void)
addObjectsFromArray: (
NSArray*)otherArray;
Availability: OpenStep
Adds each object from otherArray to the
receiver, in first to last order.
- (void)
exchangeObjectAtIndex: (
NSUInteger)i1
withObjectAtIndex: (
NSUInteger)i2;
Availability: MacOS-X 10.0.0
Swaps the positions of two objects in the array.
Raises an exception if either array index is out of
bounds.
- (id)
initWithCapacity: (
NSUInteger)numItems;
Availability: OpenStep
This is a designated initialiser for the class.
Subclasses
must override this method.
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.
- (void)
insertObject: (id)anObject
atIndex: (
NSUInteger)index;
Availability: OpenStep
Subclasses
must 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.
- (void)
insertObjects: (
NSArray*)objects
atIndexes: (
NSIndexSet*)indexes;
Availability: MacOS-X 10.4.0
Inserts the values from the objects
array into the receiver at the locations given by the
indexes set.
The values are
inserted in the same order that they appear in the
array.
- (void)
removeAllObjects;
Availability: OpenStep
Removes all objects from the receiver, leaving an
empty array.
- (void)
removeLastObject;
Availability: OpenStep
Removes the last object in the array. Raises an
exception if the array is already empty.
- (void)
removeObject: (id)anObject;
Availability: OpenStep
Removes all occurrences of anObject
(found by anObject's
[NSObject -isEqual:]
method) from the receiver.
- (void)
removeObject: (id)anObject
inRange: (
NSRange)aRange;
Availability: OpenStep
Removes all occurrences of anObject
(found by the
[NSObject -isEqual:]
method of anObject) aRange in
the receiver.
- (void)
removeObjectAtIndex: (
NSUInteger)index;
Availability: OpenStep
Subclasses
must 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.
- (void)
removeObjectIdenticalTo: (id)anObject;
Availability: OpenStep
Removes all occurrences of anObject
(found by pointer equality) from the receiver.
- (void)
removeObjectIdenticalTo: (id)anObject
inRange: (
NSRange)aRange;
Availability: OpenStep
Removes all occurrences of anObject
(found by pointer equality) from aRange
in the receiver.
- (void)
removeObjectsAtIndexes: (
NSIndexSet*)indexes;
Availability: OpenStep
Removes objects from the receiver at the indices
supplied by an NSIndexSet
- (void)
removeObjectsFromIndices: (
NSUInteger*)indices
numIndices: (
NSUInteger)count;
Availability: OpenStep
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.
- (void)
removeObjectsInArray: (
NSArray*)otherArray;
Availability: OpenStep
Removes from the receiver, all the objects present
in otherArray, as determined by using the
[NSObject -isEqual:]
method.
- (void)
removeObjectsInRange: (
NSRange)aRange;
Availability: OpenStep
Removes all the objects in aRange from
the receiver.
- (void)
replaceObjectAtIndex: (
NSUInteger)index
withObject: (id)anObject;
Availability: OpenStep
Subclasses
must 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.
- (void)
replaceObjectsAtIndexes: (
NSIndexSet*)indexes
withObjects: (
NSArray*)objects;
Availability: MacOS-X 10.4.0
Replaces the values in the receiver at the
locations given by the indexes set
with values from the objects array.
- (void)
replaceObjectsInRange: (
NSRange)aRange
withObjectsFromArray: (
NSArray*)anArray;
Availability: OpenStep
Replaces objects in the receiver with those from
anArray.
Raises an exception if
given a range extending beyond the array.
- (void)
replaceObjectsInRange: (
NSRange)aRange
withObjectsFromArray: (
NSArray*)anArray
range: (
NSRange)anotherRange;
Availability: OpenStep
Replaces objects in the receiver with some of
those from anArray.
Raises an
exception if given a range extending beyond the
array.
- (void)
setArray: (
NSArray*)otherArray;
Availability: OpenStep
Sets the contents of the receiver to be identical to
the contents of otherArray.
- (void)
setObject: (id)anObject
atIndexedSubscript: (size_t)anIndex;
Availability: OpenStep
Set method called by the compiler with array
subscripting.
- (void)
sortUsingComparator: (NSComparator)comparator;
Availability: MacOS-X 10.6.0
Sorts the array using the specified
comparator block.
- (void)
sortUsingFunction: (NSComparisonResult(*)(id,id,void*))compare
context: (void*)context;
Availability: OpenStep
Sorts the array according to the supplied
compare function with the
context information.
- (void)
sortUsingSelector: (SEL)comparator;
Availability: OpenStep
Sorts the array according to the supplied
comparator.
- (void)
sortWithOptions: (
NSSortOptions)options
usingComparator: (NSComparator)comparator;
Availability: MacOS-X 10.6.0
Sorts the array using the specified
comparator block and options.
Up