Inherits from: NSObject
Conforms to: NSObject NSObject Protocol, [NSCopying] NSCopying Protocol, [NSMutableCopying] NSMutableCopying Protocol, [NSSecureCoding] NSSecureCoding Protocol
DSSparseArray and its subclass DSMutableSparseArray manage ordered collections of objects called sparse arrays, which are similar to regular arrays but can have nil entries. The efficiency comes from the fact that a nil entry takes no space, it simply does not exist. DSSparseArray creates static sparse arrays and DSMutableSparseArray creates dynamic sparse arrays. You can use sparse arrays when you need an ordered collection of objects that may have non-contiguous indexes.
+ sparseArray
+ sparseArrayWithArray:
+ sparseArrayWithSparseArray:
+ sparseArrayWithContentsOfFile:
+ sparseArrayWithContentsOfURL:
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjects:atIndexes:
+ sparseArrayWithObjects:atIndexes:count:
+ sparseArrayWithObjectsAndIndexes:
+ sparseArrayWithObjectsAndNSUIntegerIndexes:
- init
- initWithArray:
- initWithDictionary:
- initWithSparseArray:
- initWithSparseArray:copyItems:
- initWithContentsOfURL:
- initWithContentsOfFile:
- initWithObjects:atIndexes:
- initWithObjects:atIndexes:count:
- initWithObjectsAndIndexes:
- initWithObjectsAndNSUIntegerIndexes:
- containsObject:
- count
- firstObject
- lastObject
- objectAtIndex:
- valueAtIndex:
- objectsAtIndexes:
- objectsAtIndexes:notFoundMarker:
- allIndexes
- allObjects
- objectEnumerator
- enumerateIndexesAndObjectsUsingBlock:
- enumerateIndexesAndObjectsWithOptions:usingBlock:
- indexOfObject:
- allIndexesForObject:
- indexOfObjectIdenticalTo:
- indexesOfEntriesPassingTest:
- indexesOfEntriesWithOptions:passingTest:
- filteredSparseArrayUsingPredicate:
- description:
- writeToFile:atomically:
- writeToURL:atomically:
Creates and returns an empty sparse array.
+ (instancetype) sparseArray
An empty sparse array.
This method is more usefull for by mutable subclasses of DSSparseArray.
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Creates and returns a sparse array containing the objects in the given array.
+ (instancetype) sparseArrayWithArray: (NSArray *) anArray
The array to get the elements from.
A sparse array containing the objects from anArray in indexes 0 to count - 1.
This method is used to create a sparse array containing the contents of anArray.
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Creates and returns a sparse array containing the objects in the given sparse array.
+ (instancetype) sparseArrayWithSparseArray: (DSSparseArray *) otherSparseArray
The sparse array to get the elements from.
A sparse array containing the objects from otherSparseArray at the indexes from otherSparseArray.
This method is used to create a sparse array containing the contents of otherSparseArray.
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Creates and returns a sparse array containing the objects in the given sparse array.
+ (instancetype) sparseArrayWithSparseArray: (DSSparseArray *) otherSparseArray
The sparse array to get the elements from.
A sparse array containing the objects from otherSparseArray at the indexes from otherSparseArray.
This method is used to create a sparse array containing the contents of otherSparseArray.
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Creates and returns a sparse array containing the contents of the file specified by a given path.
+ (id) sparseArrayWithContentsOfFile: (NSString *) aPath
The path to a file containing a string representation of a sparse array produced by the writeToFile:atomically: method.
A sparse array containing the contents of the file specified by aPath. Returns nil if the file can’t be opened or if the contents of the file can’t be parsed into a sparse array.
The sparse array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this sparse array are immutable, even if the sparse array is mutable.
DSSparseArray.h
Creates and returns an array containing the contents specified by a given URL.
+ (id) sparseArrayWithContentsOfURL: (NSURL *) aURL
The location of a file containing a string representation of a sparse array produced by the writeToURL:atomically: method.
A sparse array containing the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into a sparse array.
The sparse array representation at the location identified by aURL must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this sparse array are immutable, even if the sparse array is mutable.
DSSparseArray.h
Creates and returns a sparse array containing the objects at the indexes.
+ (instancetype) sparseArrayWithObjects: (NSArray *) objects atIndexes: (NSIndexSet *) indexSet
The objects the sparse array will contain.
The indexes within the sparse array the objects will be placed at.
A sparse array containing the objects at the indexes.
This method is used to create a sparse array containing the objects from an array at specified locations. The count of the array of objects must equal the count of the index set.
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Creates and returns a sparse array that includes a given number of objects at the indexes from the given C arrays.
+ (instancetype) sparseArrayWithObjects: (const id[]) objects atIndexes: (const NSUInteger[]) indexes count: (NSUInteger) count
The objects the sparse array will contain.
The indexes within the sparse array the objects will be placed at.
The number of values from the objects C arrays to include in the new sparse array. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.
A new sparse array including the first count objects from objects at the locations from indexes.
Elements are added to the new sparse array in the same order they appear in objects, up to but not including index count. For example:
NSString *strings[3];
strings[0] = @"First";
strings[1] = @"Second";
strings[2] = @"Third";
NSUInteger indexes[3];
indexes[0] = 10;
indexes[1] = 20;
indexes[2] = 30;
DSSparseArray *decadesArray = [DSSparseArray arrayWithObjects: strings atIndexes: indexes count: 2];
// decades array contains { 10: @"First", 20: @"Second" }
+ sparseArrayWithObjects:atIndexes:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Creates and returns a sparse array containing the objects at the indexes in the argument list.
+ (instancetype) sparseArrayWithObjectsAndIndexes: (id) firstObj, (int) firstIndex, ... nil
A comma-separated list of object and index pairts ending with nil.
A sparse array containing the objects at the indexes from the argument list.
This method is used to create a sparse array containing the objects at the indexes liseted. This is similar to sparseArrayWithObjectsAndIndexes: except for how the index-object pairs are specified. This code example creates a sparse array containing three different types of element:
DSSparseArray *myArray;
NSDate *aDate = [NSDate distantFuture];
NSValue *aValue = [NSNumber numberWithInt: 5];
NSString *aString = @"a string";
mySparseArray = [DSSparseArray sparseArrayWithObjectsAndIndexes: aDate, 10, aValue, 20, aString, 30, nil];
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndNSUIntegerIndexes:
DSSparseArray.h
Creates and returns a sparse array containing the objects at the indexes in the argument list.
+ (instancetype) sparseArrayWithObjectsAndNSUIntegerIndexes: (id) firstObject, (NSUInteger) firstIndex, ... nil
A comma-separated list of object and NSUInteger index pairs ending with nil.
This method is the same as sparseArrayWithObjectsAndIndexes: except the indexes are type NSUInteger. This is added because of default argument promotion for variadic functions in C. What this means is numeric arguments that are smaller than an int are increased in size to an int when there is no prototype declaring and defining the size. As a result sparseArrayWithObjectsAndIndexes: will pass its indexes as int values unless they will not fit within an int but within the method there is no way to tell if the index value is an int or a long. This method requires that all the index values be of the NSUInteger size (which could be 32 bits or 64 bits depending on the machine architecture, OS version, etc.). This code example creates a sparse array portably with very large index values:
DSSparseArray *myArray;
NSDate *aDate = [NSDate distantFuture];
NSValue *aValue = [NSNumber numberWithInt: 5];
NSString *aString = @"a string";
mySparseArray = [DSSparseArray sparseArrayWithObjectsAndNSUIntegerIndexes: aDate, (NSUInteger) NSNotFound-30, aValue, (NSUInteger) NSNotFound-20, aString, (NSUInteger) NSNotFound-10, nil];
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Sets object functionality for objects whose indexes go out of range
+ (void) setThrowExceptionOnIndexOutOfRange: (unsigned int) throwMode
IndexOutOfRangeNoThrowNoWarn for no exception throwing, IndexOutOfRangeNoThrowButLogWarning for no exception throwing but printing a warning by NSLog, IndexOutOfRangeThrowIfNonEmpty for throwing an exception if an operation causes a array entry to be pushed out of the array either at the top or bottom, IndexOutOfRangeThrowIfAny for throwing an exception if an operation causes even an empty array entry to be pushed out of the array at the bottom or if the requested start location is shifted off the top.
None.
Sparse array indexes are limited to a minium of zero and a maximum value of NSNotFound - 1. Therefore if shift or insertion operations move objects to where their index would be less than zero or greater than NSNotFound - 1 something must be done. If the throwMode has been set to IndexOutOfRangeNoThrowNoWarn (the default), then the entries are deleted. If the throwMode has been set to IndexOutOfRangeNoThrowButLogWarning the entries are also deleted but a warning is placed printed by NSLog(). If the throwMode has been set to IndexOutOfRangeThrowIfNonEmpty then an NSRangeException is thrown if a non-empty array entry would have its index set less than zero or greater than NSNotFound - 1. Lastly, if the throwMode has been to IndexOutOfRangeThrowIfAny then an NSRangeException would be thrown if any array entry, even an empty one, would have its index set to less than zero (e.g. shift entry at index 5 by negative 10) or if the selected start location of a shift would be shifted to have an index greater than NSNotFound - 1.
DSSparseArray.h
Returns a Boolean value that indicates whether a given object is present in the sparse array.
- (BOOL) containsObject: (id) anObject
An object.
YES if anObject is present in the sparse array, otherwise NO.
This method determines whether anObject is present in the sparse array by sending an isEqual: message to each of the array’s objects (and passing anObject as the parameter to each isEqual: message).
DSSparseArray.h
Returns the number of objects currently in the sparse array
- (NSUInteger) count
The number of objects currently in the sparse array.
Unlike a regular array the objects in sparse array do not necessarily be at contiguous indexes starting at zero. The method returns the number of non-empty array entries.
DSSparseArray.h
Returns a string that represents the contents of the array. - (NSString *) description
A string that represents the contents of the array.
DSSparseArray.h
Returns an NSIndexSet containing the indexes of all the non-empty entries in the sparse array.
- (NSIndexSet *) allIndexes
An NSIndexSet containing the indexes of all the non-empty entries in the sparse array.
This can be used for finding the first, last, or other entries in the sparse array.
DSSparseArray.h
Returns the lowest index whose corresponding sparse array value is equal to a given object.
- (NSUInteger) indexOfObject: (id) anObject
The object to get the index of.
The lowest index whose corresponding sparse array value is equal to anObject. If none of the objects in the sparse array is equal to anObject, returns NSNotFound.
If anObject is not nil, starting at index 0, each element of the sparse array is sent an isEqual: message until a match is found or the end of the sparse array is reached. This method passes the anObject parameter to each isEqual: message. Objects are considered equal if isEqual: (declared in the NSObject protocol returns YES.
If anObject is nil the index of the first empty sparse array location is returned or NSNotFound if completely full.
- allIndexesForObject:
- indexOfObjectIdenticalTo:
DSSparseArray.h
Returns the lowest index whose corresponding object is identical to a given object.
- (NSUInteger) indexOfObjectIdenticalTo: (id) anObject
The object to get the index of.
The lowest index whose corresponding sparse array object is identical to anObject. If none of the objects in the sparse array is identical to anObject, returns NSNotFound.
If anObject is not nil, objects are considered identical if their object addresses are the same.
If anObject is nil the index of the first empty sparse array location is returned or NSNotFound if the sparse array is completely full.
- allIndexesForObject:
- indexOfObject:
DSSparseArray.h
Returns the first object in the sparse array.
- (id) firstObject
The first object in the sparse array. If the array is empty, returns nil.
Provides a convenient method to retrieve the object in the sparse array with the lowest index. To find out the lowest index itself use the firstIndex method on the NSIndexSet returned by allIndexes.
DSSparseArray.h
Returns the last object in the sparse array.
- (id) lastObject
The last object in the sparse array. If the array is empty, returns nil.
Provides a convenient method to retrieve the object in the sparse array with the highest index. To find out the highest index itself use the lastIndex method on the NSIndexSet returned by allIndexes.
DSSparseArray.h
Returns an enumerator object that lets you access each object in the sparse array.
- (DSSparseArrayEnumerator *) objectEnumerator
An enumerator object that lets you access each object in the array, in order, from the element at the lowest index upwards to the element at the highest index skipping empty entries. Returns nil when there are not more entries.
Returns an enumerator object that lets you access each object in the array, in order, starting with the element at the lowest index, as in:
NSEnumerator *enumerator = [mySparseArray objectEnumerator];
id anObject;
while( (anObject = [enumerator nextObject]) ) {
/* code to act on each element as it is returned */
}
The DSSparseArrayEnumerator is a subclass of NSEnumerator that adds the - (NSUInteger) indexOfNextObject that will return the index in the sparse array of the object that will be returned with the next call to -(id) nextObject.
DSSparseArrayEnumerator *enumerator = [mySparseArray objectEnumerator];
NSUInteger idx;
id anObject;
while( (idx = [enumerator indexOfNextObject]) != NSNotFound ) {
anObject = [enumerator nextObject];
NSLog( @"%lu: %@", (unsigned long) idx, anObject );
}
When you use this method with mutable subclasses of DSSparseArray, you must not modify the array during enumeration.
Available in OS X v10.0 and later.
- reverseObjectEnumerator
- enumerateIndexesAndObjectsUsingBlock:
- enumerateIndexesAndObjectsWithOptions:usingBlock:
DSSparseArray.h
Returns an enumerator object that lets you access each object in the sparse array, in reverse order.
- (DSSparseArrayEnumerator *) reverseObjectEnumerator
An enumerator object that lets you access each object in the array, in order, from the element at the highest index down to the element at the lowest index skipping empty entries. Returns nil when there are no more entries
The DSSparseArrayEnumerator is a subclass of NSEnumerator that adds the - (NSUInteger) indexOfNextObject method that will return the index in the sparse array of the object that will be returned with the next call to -(id) nextObject.
When you use this method with mutable subclasses of DSSparseArray, you must not modify the array during enumeration.
Available in OS X v10.0 and later.
- objectEnumerator
- enumerateIndexesAndObjectsUsingBlock:
- enumerateIndexesAndObjectsWithOptions:usingBlock:
DSSparseArray.h
Returns the indexes of objects in the sparse array that are equal to a given object.
- (NSIndexSet *) allIndexesForObject: (id) anObject
The object to get the indexes for.
The indexes whose corresponding values in the sparse array are equal to anObject. If no objects in the sparse array are equal, returns an empty index set. If anObject is nil the indexes of the empty entries in the sparse array are returned.
Starting at the lowest index, each element of the sparse array is sent an isEqual: message and if equal its index is added to the index set that will be returned. This method passes the anObject parameter to each isEqual: message. Objects are considered equal if isEqual: (declared in the [NSObject protocol][NSObject Protcol]) returns YES.
Available in OS X v10.0 and later.
DSSparseArray.h
Returns the object located at the specified index.
- (id) valueAtIndex: (NSUInteger) index
The index to get the value for.
The object located at index which, since this is a sparse array, could be nil.
This is a synonym for objectAtIndex:. Any value of index is permissible from 0 to NSNotFound - 1 but will return nil for any entry that has not been set.
DSSparseArray.h
Returns a new array containing the sparse array's values.
- (NSArray *) allObjects
A new array containing the sparse array's values, or an empty array if the sparse array has no entries.
The order of the values in the array is the same as their order in the receiver.
- allIndexes
- getObjects:andIndexes:
- objectEnumerator
DSSparseArray.h
Returns by reference C arrays of the indexes and values in the sparse array.
- (void) getObjects: (__unsafe_unretained id []) objects andIndexes: (NSUInteger []) indexes
Upon return, contains a C array of the values or objects in the sparse array.
Upon return, contains a C array of the indexes in the sparse array.
None.
The elements in the returned arrays are ordered from smallest index to largest index such that the first element in objects is the value for the first index in indexes and so on.
id __unsafe_unretained *objectArray;
NSUInteger *indexArray;
NSUInteger count;
count = [spouseArray count];
objectArray = (__unsafe_unretained id *) malloc( count * sizeof(id) );
indexArray = (NSUInteger *) malloc( count * sizeof(NSUInteger) );
[sparseArray getObjects: objectArray andIndexes: indexArray];
/* Use objects and indexes from arrays... */
free( objectArray );
free( indexArray );
DSSparseArray.h
Executes a given block using each object in the sparse array, starting with the first object and continuing through the array to the last object.
- (void) enumerateIndexesAndObjectsUsingBlock: (void (^)( id obj, NSUInteger idx, BOOL *stop )) block
A block object to operate on entries in the sparse array.
The block takes three arguments:
obj
The element in the sparse array.
idx
The index of the element in the array.
*stop
A reference to a Boolean value. The block can set the value to YES to stop further processing of the sparse array. The stop argument is an out-only argument. You should only ever set this boolean to YES within the block.
None.
If the block sets *stop to YES, the enumeration stops. This method executes synchronously.
- allIndexes
- allObjects
- enumerateIndexesAndObjectsWithOptions:usingBlock:
DSSparseArray.h
Executes a given block using each object in the sparse array.
- (void) enumerateIndexesAndObjectsWithOptions: (NSEnumerationOptions) opts usingBlock: (void (^)( id obj, NSUInteger idx, BOOL *stop )) block
A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and/or whether it should be performed in reverse order).
A block object to operate on entries in the sparse array.
The block takes three arguments:
obj
The element in the sparse array.
idx
The index of the element in the array.
*stop
A reference to a Boolean value. The block can set the value to YES to stop further processing of the sparse array. The stop argument is an out-only argument. You should only ever set this boolean to YES within the block.
None.
By default, the enumeration starts with the first object and continues serially through the sparse array to the last object. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.
This method executes synchronously.
- allIndexes
- allObjects
- enumerateIndexesAndObjectsUsingBlock:
DSSparseArray.h
Evaluates a given predicate against each object in the receiving sparse array and returns a new sparse array containing the objects for which the predicate returns true.
- (DSSparseArray *) filteredSparseArrayUsingPredicate: (NSPredicate *) predicate
The predicate against which to evaluate the receiving array’s elements.
A new sparse array containing the objects in the receiving array for which predicate returns true.
For more details, see Predicate Programming Guide.
Available in OS X v10.4 and later.
DSSparseArray.h
Returns the indexes of objects in the sparse array that pass a test in a given Block.
- (NSIndexSet *) indexesOfEntriesPassingTest: (BOOL (^)( NSUInteger idx, id obj, BOOL *stop) ) predicate
The block to apply to elements in the sparse array.
The block takes three arguments:
obj
The element in the sparse array.
idx
The index of the element in the array.
*stop
A reference to a Boolean value. The block can set the value to YES to stop further processing of the sparse array. The stop argument is an out-only argument. You should only ever set this boolean to YES within the block.
The Block returns a Boolean value that indicates whether obj passed the test.
The indexes whose corresponding entries in the sparse array pass the test specified by predicate. If no objects in the sparse array pass the test, returns an empty index set.
The method uses Entries instead of Objects in its name since the test can utilize the index or the object at each tested entry.
Available in OS X v10.6 and later.
- allIndexes
- allObjects
- enumerateIndexesAndObjectsUsingBlock:
- indexesOfEntriesWithOptions:passingTest:
DSSparseArray.h
Returns the indexes of objects in the array that pass a test in a given Block for a given enumeration options bitmask.
- (NSIndexSet *) indexesOfEntriesWithOptions: (NSEnumerationOptions) opts passingTest: (BOOL (^)( NSUInteger idx, id obj, BOOL *stop )) predicate
A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and/or whether it should be performed in reverse order).
The block to apply to elements in the sparse array.
The block takes three arguments:
obj
The element in the sparse array.
idx
The index of the element in the array.
*stop
A reference to a Boolean value. The block can set the value to YES to stop further processing of the sparse array. The stop argument is an out-only argument. You should only ever set this boolean to YES within the block.
The Block returns a Boolean value that indicates whether obj passed the test.
The indexes whose corresponding entries in the sparse array pass the test specified by predicate. If no objects in the sparse array pass the test, returns an empty index set.
By default, the enumeration starts with the first object and continues serially through the sparse array to the last object. You can specify [NSEnumerationConcurrent][] and/or NSEnumerationReverse as enumeration options to modify this behavior.
The method uses Entries instead of Objects in its name since the test can utilize the index or the object at each tested entry.
Available in OS X v10.6 and later.
- allIndexes
- allObjects
- indexesOfEntriesPassingTest:
DSSparseArray.h
Initializes a newly allocated sparse array.
- (instancetype) init
A sparse array.
After an immutable sparse array has been initialized in this way, it cannot be modified.
This method is a designated initializer.
DSSparseArray.h
Initializes a newly allocated sparse array by placing in it the objects contained in a given array.
- (instancetype) initWithArray: (NSArray *) array
An array
A sparse array initialized to contain the objects in array. The returned object might be different than the original receiver.
After an immutable sparse array has been initialized in this way, it cannot be modified.
- initWithObjects:atIndexes:
- initWithObjectsAndIndexes:
DSSparseArray.h
Initializes a newly allocated sparse array by placing in it the objects contained in a given dictionary.
- (instancetype) initWithArray: (NSDictionary *) dictionary
A dictionary
A sparse array initialized to contain the objects in dictionary. The returned object might be different than the original receiver.
The keys for the entries in the dictionary must respond to the integerValue method with the index the object is to be placed at in the sparse array being initialized. After an immutable sparse array has been initialized in this way, it cannot be modified.
DSSparseArray.h
Initializes a newly allocated sparse array by placing in it the objects contained in a given sparse array.
- (instancetype) initWithSparseArray: (DSSparseArray *) otherSparseArray
A sparse array containing the objects with which to initialize the new array.
A sparse array initialized to contain the objects in otherSparseArray. The returned object might be different than the original receiver.
After an immutable sparse array has been initialized in this way, it cannot be modified.
- initWithObjectsAndIndexes:
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Initializes a newly allocated sparse array with the contents of the file specified by a given path.
- (id) initWithContentsOfFile: (NSString *) aPath
The path to a file containing a representation of a sparse array produced by the writeToFile:atomically: method.
A sparse array initialized to contain the contents of the file specified by aPath or nil if the file can’t be opened or the contents of the file can’t be parsed into a sparse array. The returned object might be different than the original receiver.
The sparse array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this sparse array are immutable, even if the sparse array is mutable.
+ sparseArrayWithContentsOfFile:
- writeToFile:atomically:
DSSparseArray.h
Initializes a newly allocated sparse array by placing in it the objects contained in a given sparse array.
- (id) initWithContentsOfURL: (NSURL *) aURL
The location of a file containing a string representation of an array produced by the writeToURL:atomically: method.
A sparse array initialized to contain the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into a sparse array. The returned object might be different than the original receiver.
The sparse array representation at the location identified by aURL must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this sparse array are immutable, even if the sparse array is mutable.
+ sparseArrayWithContentsOfURL:
- writeToURL:atomically:
DSSparseArray.h
Initializes a newly allocated sparse array by placing in it the objects contained in a given array at the indexes in the index set.
- (instancetype) initWithObjects: (NSArray *) objects atIndexes: (NSIndexSet *) indexSet
The objects the sparse array will contain.
The indexes within the sparse array the objects will be placed at.
A sparse array containing the objects at the indexes.
This method initializes a sparse array with the objects from an array at specified locations. The count of the array of objects must equal the count of the index set.
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Initializes a newly allocated sparse array to include a given number of objects at the specified indexes from the given C arrays.
- (instancetype) initWithObjects: (const id []) objects atIndexes: (const NSUInteger[]) indexes count: (NSUInteger) count
A C array of objects.
The indexes within the sparse array the objects will be placed at.
The number of values from the objects C arrays to include in the new sparse array. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.
A newly allocated sparse array including the first count objects from objects at the locations in indexes. The returned object might be different than the original receiver.
Elements are added to the sparse array in the same order they appear in objects, up to but not including index count. For example:
NSString *strings[3];
strings[0] = @"First";
strings[1] = @"Second";
strings[2] = @"Third";
NSUInteger indexes[3];
indexes[0] = 10;
indexes[1] = 20;
indexes[2] = 30;
DSSparseArray *decadesArray = [[DSSparseArray alloc] initWithObjects: strings atIndexes: indexes count: 2];
// decades array contains { 10: @"First", 20: @"Second" }
+ sparseArrayWithObjectsAndIndexes:
+ sparseArrayWithObjects:atIndexes:count:
DSSparseArray.h
Initializes and returns a newly allocated sparse array containing the objects at the indexes in the argument list.
- (instancetype) initWithObjectsAndIndexes: (id) firstObject, (int) firstIndex, ... nil
A comma-separated list of object and index pairs ending with nil.
A sparse array containing the objects at the indexes from the argument list.
This method is used to initialize a sparse array containing the objects at the indexes liseted. This is similar to initWithObjects:atIndexes: except for how the index-object pairs are specified. This code example creates a sparse array containing three different types of element:
DSSparseArray *myArray;
NSDate *aDate = [NSDate distantFuture];
NSValue *aValue = [NSNumber numberWithInt: 5];
NSString *aString = @"a string";
mySparseArray = [[DSSparseArray alloc] initWithObjectsAndIndexes: aDate, 10, aValue, 20, aString, 30, nil];
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Initializes and returns a newly allocated sparse array containing the objects at the indexes in the argument list.
- (instancetype) initWithObjectsAndNSUIntegerIndexes: (id) firstObject, (NSUInteger) firstIndex, ..., nil
A comma-separated list of object and NSUInteger index pairs ending with nil.
This method is the same as initWithObjectsAndIndexes: except the indexes are type NSUInteger. This is added because of default argument promotion for variadic functions in C. What this means is numeric arguments that are smaller than an int are increased in size to an int when there is no prototype declaring and defining the size. As a result sparseArrayWithObjectsAndIndexes: will pass its indexes as int values unless they will not fit within an int but within the method there is no way to tell if the index value is an int or a long. This method requires that all the index values be of the NSUInteger size (which could be 32 bits or 64 bits depending on the machine architecture, OS version, etc.). This code example creates a sparse array portably with very large index values:
DSSparseArray *myArray;
NSDate *aDate = [NSDate distantFuture];
NSValue *aValue = [NSNumber numberWithInt: 5];
NSString *aString = @"a string";
mySparseArray = [[DSSparseArray alloc] initObjectsAndNSUIntegerIndexes: aDate, (NSUInteger) NSNotFound-30, aValue, (NSUInteger) NSNotFound-20, aString, (NSUInteger) NSNotFound-10, nil];
- initWithObjectsAndIndexes:
+ sparseArrayWithObject:atIndex:
+ sparseArrayWithObjectsAndIndexes:
DSSparseArray.h
Initializes a newly allocated sparse array by placing in it the objects contained in a given sparse array.
- (instancetype) initWithSparseArray: (DSSparseArray *) otherSparseArray copyItems: (BOOL) flag
A sparse array containing the objects with which to initialize the new array.
If YES, each object in otherSparseArray receives a copyWithZone: message to create a copy of the object—objects must conform to the NSCopying protocol. In a managed memory environment, this is instead of the retain message the object would otherwise receive. The object copy is then added to the returned sparse array at its same index value. If NO, then in a managed memory environment each object in otherSparseArray simply receives a retain message when it is added to the returned sparse array.
A sparse array initialized to contain the objects—or if flag is YES, copies of the objects—in otherSparseArray. The returned object might be different than the original receiver.
After an immutable sparse array has been initialized in this way, it cannot be modified.
The copyWithZone: method performs a shallow copy. If you have a collection of arbitrary depth, passing YES for the flag parameter will perform an immutable copy of the first level below the surface. If you pass NO the mutability of the first level is unaffected. In either case, the mutability of all deeper levels is unaffected.
- init
- initWithObjects:atIndexes:
- initWithSparseArray:
DSSparseArray.h
Compares the receiving sparse array to another sparse array.
- (BOOL) isEqualToSparseArray: (DSSparseArray *) otherSparseArray
A sparse array.
YES if the contents of otherSparseArray are equal to the contents of the receiving sparse array, otherwise 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.
Available in OS X v10.0 and later.
DSSparseArray.h
Returns a sparse array containing the objects in the sparse array at the indexes specified by a given index set.
- (DSSparseArray *) objectsAtIndexes: (NSIndexSet *) indexes
An index set.
A sparse array containing the objects in the sparse array at the indexes specified by indexes.
The returned objects are at the indexes specified by indexes. This method is equivalent to objectsAtIndexes:notFoundMarker: with nil passed as the notFoundMarker object.
Available in OS X v10.0 and later.
- allIndexes
- allObjects
- objectsAtIndexes:notFoundMarker:
DSSparseArray.h
Returns a sparse array containing the objects in the sparse array at the indexes specified by a given index set.
- (DSSparseArray *) objectsAtIndexes: (NSIndexSet *) indexes notFoundMarker: (id) anObject
An index set.
An object to use for empty entries in the receiving sparse array. This can be nil.
A sparse array containing the objects in the sparse array at the indexes specified by indexes.
The returned objects are at the indexes in indexes. Any empty location is filled in by anObject.
Available in OS X v10.0 and later.
- allIndexes
- allObjects
- objectsAtIndexes:
DSSparseArray.h
Writes the contents of the sparse array to a file at a given path.
- (BOOL) writeToFile: (NSString *) path atomically: (BOOL) flag
The path at which to write the contents of the sparse array.
If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.
If YES, the sparse array is written to an auxiliary file, and then the auxiliary file is renamed to path. If 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.
YES if the file is written successfully, otherwise NO.
If the sparse array’s contents are all property list objects (NSString, NSData, NSArray, or NSDictionary objects), the file written by this method can be used to initialize a new sparse array with the class method sparseArrayWithContentsOfFile: or the instance method initWithContentsOfFile:. This method recursively validates that all the contained objects are property list objects before writing out the file, and returns NO if all the objects are not property list objects, since the resultant file would not be a valid property list.
For more information about property lists, see Property List Programming Guide.
Available in OS X v10.0 and later.
+ sparseArrayWithContentsOfFile:
- initWithContentsOfFile:
DSSparseArray.h
Writes the contents of the sparse array to the location specified by a given URL.
- (BOOL) writeToURL: (NSURL *) aURL atomically: (BOOL) flag
The location at which to write the sparse array.
If YES, the sparse array is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If NO, the array is written directly to aURL. The YES option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing.
YES if the location is written successfully, otherwise NO.
If the sparse array’s contents are all property list objects (NSString, NSData, NSArray, or NSDictionary objects), the location written by this method can be used to initialize a new sparse array with the class method sparseArrayWithContentsOfURL: or the instance method initWithContentsOfURL:.
For more information about property lists, see Property List Programming Guide.
Available in OS X v10.0 and later.
+ sparseArrayWithContentsOfURL:
- initWithContentsOfURL:
DSSparseArray.h