Class CPArray

CPObject
    extended byCPArray
Direct Known Subclasses:
CPMutableArray

@implementation CPArray : CPObject

A mutable array class backed by a JavaScript Array. There is also a CPMutableArray class, but it is just a child class of this class with an empty implementation. All mutable functionality is implemented directly in CPArray.


Method Summary
+(id)alloc
          Returns a new uninitialized CPArray.
+(id)array
          Returns a new initialized CPArray.
+(id)arrayWithArray:(CPArray)anArray
          Creates a new array containing the objects in anArray.
+(CPArray)arrayWithCapacity:(unsigned)aCapacity
          Creates an array able to store at least aCapacity items.
+(id)arrayWithObject:(id)anObject
          Creates a new array with anObject in it.
+(id)arrayWithObjects:(id)anObject,...
          Creates a new CPArray containing all the objects passed as arguments to the method.
+(id)arrayWithObjects:(id)objects count:(unsigned)aCount
          Creates a CPArray from a JavaScript array of objects.
-(id)init
          Initializes the CPArray.
-(id)initWithArray:(CPArray)anArray
          Creates a new CPArray from anArray.
-(id)initWithArray:(CPArray)anArray copyItems:(BOOL)copyItems
          Initializes a the array with the contents of anArray and optionally performs a deep copy of the objects based on copyItems.
-(id)initWithCapacity:(unsigned)aCapacity
          Initializes an array able to store at least aCapacity items.
-(id)initWithCoder:(CPCoder)aCoder
-(id)initWithObjects:(Array)anObject,...
          initializes.
-(id)initWithObjects:(id)objects count:(unsigned)aCount
          Initializes the array with a JavaScript array of objects.
-(void)addObject:(id)anObject
          Adds anObject to the end of the array.
-(void)addObjectsFromArray:(CPArray)anArray
          Adds the objects in anArray to the receiver array.
-(CPArray)arrayByAddingObject:(id)anObject
          Returns a copy of this array plus anObject inside the copy.
-(CPArray)arrayByAddingObjectsFromArray:(CPArray)anArray
          Returns a new array which is the concatenation of self and otherArray (in this precise order).
-(CPString)componentsJoinedByString:(CPString)aString
          Returns a string formed by concatenating the objects in the receiver, with the specified separator string inserted between each part.
-(BOOL)containsObject:(id)anObject
          Returns YES if the array contains anObject.
-(id)copy
          Makes a copy of the receiver.
-(int)count
          Returns the number of elements in the array.
-(CPString)description
          Returns a human readable description of this array and it's elements.
-(void)encodeWithCoder:(CPCoder)aCoder
-(void)exchangeObjectAtIndex:(unsigned)anIndex withObjectAtIndex:(unsigned)otherIndex
          Swaps the elements at the two specified indices.
-(id)firstObjectCommonWithArray:(CPArray)anArray
          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.
-(unsigned)hash
          Returns a hash of the CPArray.
-(int)indexOfObject:(id)anObject
          Returns the index of anObject in this array.
-(int)indexOfObjectIdenticalTo:(id)anObject
          Returns the index of anObject in the array.
-(int)indexOfObjectIdenticalTo:(id)anObject inRange:(CPRange)aRange
          Returns the index of anObject in the array within aRange.
-(int)indexOfObject:(id)anObject inRange:(CPRange)aRange
          Returns the index of anObject in the array within aRange.
-(void)insertObject:(id)anObject atIndex:(int)anIndex
          Inserts an object into the receiver at the specified location.
-(void)insertObjects:(CPArray)objects atIndexes:(CPIndexSet)anIndexSet
          Inserts the objects in the provided array into the receiver at the indexes specified.
-(BOOL)isEqualToArray:(id)anArray
          Returns true if anArray contains exactly the same objects as the reciever.
-(id)lastObject
          Returns the last object in the array.
-(void)makeObjectsPerformSelector:(SEL)aSelector
          Sends each element in the array a message.
-(void)makeObjectsPerformSelector:(SEL)aSelector withObject:(id)anObject
          Sends each element in the array a message with an argument.
-(id)objectAtIndex:(int)anIndex
          Returns the object at index anIndex.
-(CPEnumerator)objectEnumerator
          Returns an enumerator describing the array sequentially from the first to the last element.
-(CPArray)objectsAtIndexes:(CPIndexSet)indexes
          Returns the objects at indexes in a new CPArray.
-(CPArray)pathsMatchingExtensions:(CPArray)filterTypes
          Returns a new array subset formed by selecting the elements that have filename extensions from filterTypes.
-(void)removeAllObjects
          Removes all objects from this array.
-(void)removeLastObject
          Removes the last object from the array.
-(void)removeObject:(id)anObject
          Removes all entries of anObject from the array.
-(void)removeObjectAtIndex:(int)anIndex
          Removes the object at anIndex.
-(void)removeObjectIdenticalTo:(id)anObject
          Remove the first instance of anObject from the array.
-(void)removeObjectIdenticalTo:(id)anObject inRange:(CPRange)aRange
          Remove the first instance of anObject from the array, within the range specified by aRange.
-(void)removeObject:(id)anObject inRange:(CPRange)aRange
          Removes all entries of anObject from the array, in the range specified by aRange.
-(void)removeObjectsAtIndexes:(CPIndexSet)anIndexSet
          Removes the objects at the indices specified by CPIndexSet.
-(void)removeObjectsInArray:(CPArray)anArray
          Remove the objects in anArray from the receiver array.
-(void)removeObjectsInRange:(CPRange)aRange
          Removes all the objects in the specified range from the receiver.
-(void)replaceObjectAtIndex:(int)anIndex withObject:(id)anObject
          Replaces the element at anIndex with anObject.
-(void)replaceObjectsAtIndexes:(CPIndexSet)anIndexSet withObjects:(CPArray)objects
          Replace the elements at the indices specified by anIndexSet with the objects in objects.
-(void)replaceObjectsInRange:(CPRange)aRange withObjectsFromArray:(CPArray)anArray
          Replaces some of the receiver's objects with the objects from anArray.
-(void)replaceObjectsInRange:(CPRange)aRange withObjectsFromArray:(CPArray)anArray range:(CPRange)otherRange
          Replaces some of the receiver's objects with objects from anArray.
-(CPEnumerator)reverseObjectEnumerator
          Returns an enumerator describing the array sequentially from the last to the first element.
-(void)setArray:(CPArray)anArray
          Sets the contents of the receiver to be identical to the contents of anArray.
-(void)setValue:(id)aValue forKey:(CPString)aKey
          Sets the key-value for each element in the array.
-(CPArray)sortUsingDescriptors:(CPArray)descriptors
-(void)sortUsingFunction:(Function)aFunction context:(id)aContext
          Sorts the receiver array using a JavaScript function as a comparator, and a specified context.
-(void)sortUsingSelector:(SEL)aSelector
          Sorts the receiver array using an Objective-J method as a comparator.
-(CPArray)sortedArrayUsingDescriptors:(CPArray)descriptors
          Not yet described.
-(CPArray)sortedArrayUsingFunction:(Function)aFunction context:(id)aContext
          Returns an array in which the objects are ordered according to a sort with aFunction.
-(CPArray)sortedArrayUsingSelector:(SEL)aSelector
          Returns a new array in which the objects are ordered according to a sort with aSelector.
-(CPArray)subarrayWithRange:(CPRange)aRange
          Returns a subarray of the receiver containing the objects found in the specified range aRange.
-(CPArray)valueForKey:(CPString)aKey
          Returns the value for aKey from each element in the array.

Methods inherited from class CPObject
initialize, alloc, class, instanceMethodForSelector, instancesRespondToSelector, isSubclassOfClass, load, new, setVersion, superclass, version, init, autorelease, awakeAfterUsingCoder, class, classForCoder, classForKeyedArchiver, className, copy, dealloc, description, doesNotRecognizeSelector, forwardInvocation, hash, isEqual, isKindOfClass, isMemberOfClass, isProxy, methodForSelector, methodSignatureForSelector, mutableCopy, performSelector, performSelector, performSelector, release, replacementObjectForArchiver, replacementObjectForCoder, replacementObjectForKeyedArchiver, respondsToSelector, retain, self, superclass


Method Detail

alloc

+(id)alloc
Returns a new uninitialized CPArray.

array

+(id)array
Returns a new initialized CPArray.

arrayWithArray

+(id)arrayWithArray:(CPArray)anArray
Creates a new array containing the objects in anArray.
Parameters:
anArray - Objects in this array will be added to the new array
Returns:
a new CPArray of the provided objects

arrayWithCapacity

+(CPArray)arrayWithCapacity:(unsigned)aCapacity
Creates an array able to store at least aCapacity items. Because CPArray is backed by JavaScript arrays, this method ends up simply returning a regular array.
Parameters:
aCapacity

arrayWithObject

+(id)arrayWithObject:(id)anObject
Creates a new array with anObject in it.
Parameters:
anObject - the object to be added to the array
Returns:
a new CPArray containing a single object

arrayWithObjects

+(id)arrayWithObjects:(id)anObject,...
Creates a new CPArray containing all the objects passed as arguments to the method.
Parameters:
anObject,...
Returns:
a new CPArray containing the argument objects

arrayWithObjects

+(id)arrayWithObjects:(id)objects count:(unsigned)aCount
Creates a CPArray from a JavaScript array of objects.
Parameters:
objects - the JavaScript Array
aCount - the number of objects in the JS Array
Returns:
a new CPArray containing the specified objects

init

-(id)init
Initializes the CPArray.
Returns:
the initialized array

initWithArray

-(id)initWithArray:(CPArray)anArray
Creates a new CPArray from anArray.
Parameters:
anArray - objects in this array will be added to the new array
Returns:
a new CPArray containing the objects of anArray

initWithArray

-(id)initWithArray:(CPArray)anArray copyItems:(BOOL)copyItems
Initializes a the array with the contents of anArray and optionally performs a deep copy of the objects based on copyItems.
Parameters:
anArray - the array to copy the data from
copyItems - if YES, each object will be copied by having a copy message sent to it, and the returned object will be added to the receiver. Otherwise, no copying will be performed.
Returns:
the initialized array of objects

initWithCapacity

-(id)initWithCapacity:(unsigned)aCapacity
Initializes an array able to store at least aCapacity items. Because CPArray is backed by JavaScript arrays, this method ends up simply returning a regular array.
Parameters:
aCapacity

initWithCoder

-(id)initWithCoder:(CPCoder)aCoder
Parameters:
aCoder

initWithObjects

-(id)initWithObjects:(Array)anObject,...
initializes
Parameters:
anObject,...

initWithObjects

-(id)initWithObjects:(id)objects count:(unsigned)aCount
Initializes the array with a JavaScript array of objects.
Parameters:
objects - the array of objects to add to the receiver
aCount - the number of objects in objects
Returns:
the initialized CPArray

addObject

-(void)addObject:(id)anObject
Adds anObject to the end of the array.
Parameters:
anObject - the object to add to the array

addObjectsFromArray

-(void)addObjectsFromArray:(CPArray)anArray
Adds the objects in anArray to the receiver array.
Parameters:
anArray - the array of objects to add to the end of the receiver

arrayByAddingObject

-(CPArray)arrayByAddingObject:(id)anObject
Returns a copy of this array plus anObject inside the copy.
Parameters:
anObject - the object to be added to the array copy
Throws:
CPInvalidArgumentException - if anObject is nil
Returns:
a new array that should be n+1 in size compared to the receiver.

arrayByAddingObjectsFromArray

-(CPArray)arrayByAddingObjectsFromArray:(CPArray)anArray
Returns a new array which is the concatenation of self and otherArray (in this precise order).
Parameters:
anArray - the array that will be concatenated to the receiver's copy

componentsJoinedByString

-(CPString)componentsJoinedByString:(CPString)aString
Returns a string formed by concatenating the objects in the receiver, with the specified separator string inserted between each part. If the element is a Cappuccino object, then the description of that object will be used, otherwise the default JavaScript representation will be used.
Parameters:
aString - the separator that will separate each object string
Returns:
the string representation of the array

containsObject

-(BOOL)containsObject:(id)anObject
Returns YES if the array contains anObject. Otherwise, it returns NO.
Parameters:
anObject - the method checks if this object is already in the array

copy

-(id)copy
Makes a copy of the receiver.
Returns:
a new CPArray copy

count

-(int)count
Returns the number of elements in the array

description

-(CPString)description
Returns a human readable description of this array and it's elements.

encodeWithCoder

-(void)encodeWithCoder:(CPCoder)aCoder
Parameters:
aCoder

exchangeObjectAtIndex

-(void)exchangeObjectAtIndex:(unsigned)anIndex withObjectAtIndex:(unsigned)otherIndex
Swaps the elements at the two specified indices.
Parameters:
anIndex - the first index to swap from
otherIndex - the second index to swap from

firstObjectCommonWithArray

-(id)firstObjectCommonWithArray:(CPArray)anArray
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.
Parameters:
anArray
Returns:
the first object found, or nil if no common object was found.

hash

-(unsigned)hash
Returns a hash of the CPArray.
Returns:
an unsigned integer hash

indexOfObject

-(int)indexOfObject:(id)anObject
Returns the index of anObject in this array. If the object is nil or not in the array, returns CPNotFound. It first attempts to find a match using isEqual:, then ==.
Parameters:
anObject - the object to search for

indexOfObjectIdenticalTo

-(int)indexOfObjectIdenticalTo:(id)anObject
Returns the index of anObject in the array. The test for equality is done using only ==.
Parameters:
anObject - the object to search for
Returns:
the index of the object in the array. CPNotFound if the object is not in the array.

indexOfObjectIdenticalTo

-(int)indexOfObjectIdenticalTo:(id)anObject inRange:(CPRange)aRange
Returns the index of anObject in the array within aRange. The test for equality is done using only ==.
Parameters:
anObject - the object to search for
aRange - the range to search within
Returns:
the index of the object, or CPNotFound if it was not found.

indexOfObject

-(int)indexOfObject:(id)anObject inRange:(CPRange)aRange
Returns the index of anObject in the array within aRange. It first attempts to find a match using isEqual:, then ==.
Parameters:
anObject - the object to search for
aRange - the range to search within
Returns:
the index of the object, or CPNotFound if it was not found.

insertObject

-(void)insertObject:(id)anObject atIndex:(int)anIndex
Inserts an object into the receiver at the specified location.
Parameters:
anObject - the object to insert into the array
anIndex - the location to insert anObject at

insertObjects

-(void)insertObjects:(CPArray)objects atIndexes:(CPIndexSet)anIndexSet
Inserts the objects in the provided array into the receiver at the indexes specified.
Parameters:
objects - the objects to add to this array
anIndexSet - the indices for the objects

isEqualToArray

-(BOOL)isEqualToArray:(id)anArray
Returns true if anArray contains exactly the same objects as the reciever.
Parameters:
anArray

lastObject

-(id)lastObject
Returns the last object in the array. If the array is empty, returns nil/

makeObjectsPerformSelector

-(void)makeObjectsPerformSelector:(SEL)aSelector
Sends each element in the array a message.
Parameters:
aSelector - the selector of the message to send
Throws:
CPInvalidArgumentException - if aSelector is nil

makeObjectsPerformSelector

-(void)makeObjectsPerformSelector:(SEL)aSelector withObject:(id)anObject
Sends each element in the array a message with an argument.
Parameters:
aSelector - the selector of the message to send
anObject - the first argument of the message
Throws:
CPInvalidArgumentException - if aSelector is nil

objectAtIndex

-(id)objectAtIndex:(int)anIndex
Returns the object at index anIndex.
Parameters:
anIndex
Throws:
CPRangeException - if anIndex is out of bounds

objectEnumerator

-(CPEnumerator)objectEnumerator
Returns an enumerator describing the array sequentially from the first to the last element. You should not modify the array during enumeration.

objectsAtIndexes

-(CPArray)objectsAtIndexes:(CPIndexSet)indexes
Returns the objects at indexes in a new CPArray.
Parameters:
indexes - the set of indices
Throws:
CPRangeException - if any of the indices is greater than or equal to the length of the array

pathsMatchingExtensions

-(CPArray)pathsMatchingExtensions:(CPArray)filterTypes
Returns a new array subset formed by selecting the elements that have filename extensions from filterTypes. Only elements that are of type CPString are candidates for inclusion in the returned array.
Parameters:
filterTypes - an array of CPString objects that contain file extensions (without the '.')
Returns:
a new array with matching paths

removeAllObjects

-(void)removeAllObjects
Removes all objects from this array.

removeLastObject

-(void)removeLastObject
Removes the last object from the array.

removeObject

-(void)removeObject:(id)anObject
Removes all entries of anObject from the array.
Parameters:
anObject - the object whose entries are to be removed

removeObjectAtIndex

-(void)removeObjectAtIndex:(int)anIndex
Removes the object at anIndex.
Parameters:
anIndex - the location of the element to be removed

removeObjectIdenticalTo

-(void)removeObjectIdenticalTo:(id)anObject
Remove the first instance of anObject from the array. The search for the object is done using ==.
Parameters:
anObject - the object to remove

removeObjectIdenticalTo

-(void)removeObjectIdenticalTo:(id)anObject inRange:(CPRange)aRange
Remove the first instance of anObject from the array, within the range specified by aRange. The search for the object is done using ==.
Parameters:
anObject - the object to remove
aRange - the range in the array to search for the object

removeObject

-(void)removeObject:(id)anObject inRange:(CPRange)aRange
Removes all entries of anObject from the array, in the range specified by aRange.
Parameters:
anObject - the object to remove
aRange - the range to search in the receiver for the object

removeObjectsAtIndexes

-(void)removeObjectsAtIndexes:(CPIndexSet)anIndexSet
Removes the objects at the indices specified by CPIndexSet.
Parameters:
anIndexSet - the indices of the elements to be removed from the array

removeObjectsInArray

-(void)removeObjectsInArray:(CPArray)anArray
Remove the objects in anArray from the receiver array.
Parameters:
anArray - the array of objects to remove from the receiver

removeObjectsInRange

-(void)removeObjectsInRange:(CPRange)aRange
Removes all the objects in the specified range from the receiver.
Parameters:
aRange - the range of objects to remove

replaceObjectAtIndex

-(void)replaceObjectAtIndex:(int)anIndex withObject:(id)anObject
Replaces the element at anIndex with anObject. The current element at position anIndex will be removed from the array.
Parameters:
anIndex - the position in the array to place anObject
anObject

replaceObjectsAtIndexes

-(void)replaceObjectsAtIndexes:(CPIndexSet)anIndexSet withObjects:(CPArray)objects
Replace the elements at the indices specified by anIndexSet with the objects in objects.
Parameters:
anIndexSet - the set of indices to array positions that will be replaced
objects - the array of objects to place in the specified indices

replaceObjectsInRange

-(void)replaceObjectsInRange:(CPRange)aRange withObjectsFromArray:(CPArray)anArray
Replaces some of the receiver's objects with the objects from anArray. Specifically, the elements of the receiver in the range specified by aRange.
Parameters:
aRange - the range of elements to be replaced in the receiver
anArray - the array to retrieve objects for placement into the receiver

replaceObjectsInRange

-(void)replaceObjectsInRange:(CPRange)aRange withObjectsFromArray:(CPArray)anArray range:(CPRange)otherRange
Replaces some of the receiver's objects with objects from anArray. Specifically, the elements of the receiver in the range specified by aRange, with the elements of anArray in the range specified by otherRange.
Parameters:
aRange - the range of elements to be replaced in the receiver
anArray - the array to retrieve objects for placement into the receiver
otherRange - the range of objects in anArray to pull from for placement into the receiver

reverseObjectEnumerator

-(CPEnumerator)reverseObjectEnumerator
Returns an enumerator describing the array sequentially from the last to the first element. You should not modify the array during enumeration.

setArray

-(void)setArray:(CPArray)anArray
Sets the contents of the receiver to be identical to the contents of anArray.
Parameters:
anArray - the array of objects used to replace the receiver's objects

setValue

-(void)setValue:(id)aValue forKey:(CPString)aKey
Sets the key-value for each element in the array.
Parameters:
aValue - the value for the coding
aKey - the key for the coding

sortUsingDescriptors

-(CPArray)sortUsingDescriptors:(CPArray)descriptors
Parameters:
descriptors

sortUsingFunction

-(void)sortUsingFunction:(Function)aFunction context:(id)aContext
Sorts the receiver array using a JavaScript function as a comparator, and a specified context.
Parameters:
aFunction - a JavaScript function that will be called to compare objects
aContext - an object that will be passed to aFunction with comparison

sortUsingSelector

-(void)sortUsingSelector:(SEL)aSelector
Sorts the receiver array using an Objective-J method as a comparator.
Parameters:
aSelector - the selector for the method to call for comparison

sortedArrayUsingDescriptors

-(CPArray)sortedArrayUsingDescriptors:(CPArray)descriptors
Not yet described.
Parameters:
descriptors

sortedArrayUsingFunction

-(CPArray)sortedArrayUsingFunction:(Function)aFunction context:(id)aContext
Returns an array in which the objects are ordered according to a sort with aFunction. This invokes -sortUsingFunction:context.
Parameters:
aFunction - a JavaScript 'Function' type that compares objects
aContext - context information
Returns:
a new sorted array

sortedArrayUsingSelector

-(CPArray)sortedArrayUsingSelector:(SEL)aSelector
Returns a new array in which the objects are ordered according to a sort with aSelector.
Parameters:
aSelector - the selector that will perform object comparisons

subarrayWithRange

-(CPArray)subarrayWithRange:(CPRange)aRange
Returns a subarray of the receiver containing the objects found in the specified range aRange.
Parameters:
aRange - the range of objects to be copied into the subarray
Throws:
CPRangeException - if the specified range exceeds the bounds of the array

valueForKey

-(CPArray)valueForKey:(CPString)aKey
Returns the value for aKey from each element in the array.
Parameters:
aKey - the key to return the value for
Returns:
an array of containing a value for each element in the array

Created on Sat Sep 13 14:15:43 PDT 2008