1 /* Interface for NSArray for GNUStep 2 Copyright (C) 1995-2015 Free Software Foundation, Inc. 3 4 Written by: Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu> 5 Created: 1995 6 7 This file is part of the GNUstep Base Library. 8 9 This library is free software; you can redistribute it and/or 10 modify it under the terms of the GNU Lesser General Public 11 License as published by the Free Software Foundation; either 12 version 2 of the License, or (at your option) any later version. 13 14 This library is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 Library General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public 20 License along with this library; if not, write to the Free 21 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 22 Boston, MA 02111 USA. 23 */ 24 25 #ifndef __NSArray_h_GNUSTEP_BASE_INCLUDE 26 #define __NSArray_h_GNUSTEP_BASE_INCLUDE 27 #import "../GNUstepBase/GSVersionMacros.h" 28 29 #import "NSObject.h" 30 #import "NSRange.h" 31 #import "NSEnumerator.h" 32 #if __BLOCKS__ 33 #import "../GNUstepBase/GSBlocks.h" 34 #endif 35 36 #if defined(__cplusplus) 37 extern "C" { 38 #endif 39 40 @class NSString; 41 @class NSURL; 42 @class NSIndexSet; 43 44 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 45 enum 46 { 47 NSBinarySearchingFirstEqual = (1UL << 8), /** Specifies that the binary 48 * search should find the first object equal in the array. 49 */ 50 NSBinarySearchingLastEqual = (1UL << 9), /** Specifies that the binary 51 * search should find the last object equal in the array. 52 */ 53 NSBinarySearchingInsertionIndex = (1UL << 10), /** Specifies that the binary 54 * search should find the index at which an equal object should be inserted 55 * in order to keep the array sorted 56 */ 57 }; 58 59 typedef NSUInteger NSBinarySearchingOptions; 60 #endif 61 62 @interface GS_GENERIC_CLASS(NSArray, __covariant ElementT) : NSObject 63 <NSCoding, NSCopying, NSMutableCopying, NSFastEnumeration> 64 65 + (instancetype) array; 66 + (instancetype) arrayWithArray: (GS_GENERIC_CLASS(NSArray, ElementT) *)array; 67 + (instancetype) arrayWithContentsOfFile: (NSString*)file; 68 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 69 + (instancetype) arrayWithContentsOfURL: (NSURL*)aURL; 70 #endif 71 + (instancetype) arrayWithObject: (id)anObject; 72 + (instancetype) arrayWithObjects: (id)firstObject, ...; 73 + (instancetype) arrayWithObjects: (const id[])objects count: (NSUInteger)count; 74 75 - (GS_GENERIC_CLASS(NSArray, ElementT) *) arrayByAddingObject: 76 (GS_GENERIC_TYPE(ElementT))anObject; 77 - (GS_GENERIC_CLASS(NSArray, ElementT) *) arrayByAddingObjectsFromArray: 78 (GS_GENERIC_CLASS(NSArray, ElementT)*)anotherArray; 79 - (BOOL) containsObject: (GS_GENERIC_TYPE(ElementT))anObject; 80 81 /** <override-subclass /> 82 * Returns the number of elements contained in the receiver. 83 */ 84 - (NSUInteger) count; 85 - (void) getObjects: (__unsafe_unretained GS_GENERIC_TYPE(ElementT)[])aBuffer; 86 - (void) getObjects: (__unsafe_unretained GS_GENERIC_TYPE(ElementT)[])aBuffer 87 range: (NSRange)aRange; 88 - (NSUInteger) indexOfObject: (GS_GENERIC_TYPE(ElementT))anObject; 89 - (NSUInteger) indexOfObject: (GS_GENERIC_TYPE(ElementT))anObject 90 inRange: (NSRange)aRange; 91 - (NSUInteger) indexOfObjectIdenticalTo: (GS_GENERIC_TYPE(ElementT))anObject; 92 - (NSUInteger) indexOfObjectIdenticalTo: (GS_GENERIC_TYPE(ElementT))anObject 93 inRange: (NSRange)aRange; 94 - (instancetype) init; 95 - (instancetype) initWithArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)array; 96 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 97 - (instancetype) initWithArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)array 98 copyItems: (BOOL)shouldCopy; 99 #endif 100 - (instancetype) initWithContentsOfFile: (NSString*)file; 101 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 102 - (instancetype) initWithContentsOfURL: (NSURL*)aURL; 103 #endif 104 - (instancetype) initWithObjects: (GS_GENERIC_TYPE(ElementT)) firstObject, ...; 105 106 /** <init /> <override-subclass /> 107 * This should initialize the array with count (may be zero) objects.<br /> 108 * Retains each object placed in the array.<br /> 109 * Calls -init (which does nothing but maintain MacOS-X compatibility), 110 * and needs to be re-implemented in subclasses in order to have all 111 * other initialisers work. 112 */ 113 - (instancetype) initWithObjects: (const GS_GENERIC_TYPE(ElementT)[])objects 114 count: (NSUInteger)count; 115 - (GS_GENERIC_TYPE(ElementT)) lastObject; 116 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 117 - (GS_GENERIC_TYPE(ElementT)) firstObject; 118 #endif 119 120 /** <override-subclass /> 121 * Returns the object at the specified index. 122 * Raises an exception of the index is beyond the array. 123 */ 124 - (GS_GENERIC_TYPE(ElementT)) objectAtIndex: (NSUInteger)index; 125 126 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST) 127 - (GS_GENERIC_CLASS(NSArray, ElementT) *) objectsAtIndexes: 128 (NSIndexSet *)indexes; 129 #endif 130 131 - (GS_GENERIC_TYPE(ElementT)) firstObjectCommonWithArray: 132 (GS_GENERIC_CLASS(NSArray, ElementT) *)otherArray; 133 - (BOOL) isEqualToArray: (NSArray*)otherArray; 134 135 #if OS_API_VERSION(GS_API_OPENSTEP, GS_API_MACOSX) 136 - (void) makeObjectsPerform: (SEL)aSelector; 137 - (void) makeObjectsPerform: (SEL)aSelector withObject: (id)argument; 138 #endif 139 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 140 - (void) makeObjectsPerformSelector: (SEL)aSelector; 141 - (void) makeObjectsPerformSelector: (SEL)aSelector withObject: (id)arg; 142 #endif 143 144 - (NSData*) sortedArrayHint; 145 - (GS_GENERIC_CLASS(NSArray, ElementT)*) sortedArrayUsingFunction: 146 (NSComparisonResult (*)(id, id, void*))comparator 147 context: (void*)context; 148 - (GS_GENERIC_CLASS(NSArray, ElementT)*) sortedArrayUsingFunction: 149 (NSComparisonResult (*)(id, id, void*))comparator 150 context: (void*)context 151 hint: (NSData*)hint; 152 - (GS_GENERIC_CLASS(NSArray, ElementT)*) sortedArrayUsingSelector: 153 (SEL)comparator; 154 - (GS_GENERIC_CLASS(NSArray, ElementT)*) subarrayWithRange: (NSRange)aRange; 155 156 - (NSString*) componentsJoinedByString: (NSString*)separator; 157 - (GS_GENERIC_CLASS(NSArray, NSString*)*) pathsMatchingExtensions: 158 (GS_GENERIC_CLASS(NSArray, NSString*)*)extensions; 159 160 - (GS_GENERIC_CLASS(NSEnumerator, ElementT)*) objectEnumerator; 161 - (GS_GENERIC_CLASS(NSEnumerator, ElementT)*) reverseObjectEnumerator; 162 163 - (NSString*) description; 164 - (NSString*) descriptionWithLocale: (id)locale; 165 - (NSString*) descriptionWithLocale: (id)locale 166 indent: (NSUInteger)level; 167 168 - (BOOL) writeToFile: (NSString*)path atomically: (BOOL)useAuxiliaryFile; 169 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 170 - (BOOL) writeToURL: (NSURL*)url atomically: (BOOL)useAuxiliaryFile; 171 - (GS_GENERIC_TYPE(ElementT)) valueForKey: (NSString*)key; 172 - (void) setValue: (GS_GENERIC_TYPE(ElementT))value forKey: (NSString*)key; 173 #endif 174 175 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 176 177 #if __BLOCKS__ 178 DEFINE_BLOCK_TYPE(GSEnumeratorBlock, void, GS_GENERIC_TYPE(ElementT), 179 NSUInteger, BOOL*); 180 DEFINE_BLOCK_TYPE(GSPredicateBlock, BOOL, GS_GENERIC_TYPE(ElementT), 181 NSUInteger, BOOL*); 182 /** 183 * Enumerate over the collection using the given block. The first argument is 184 * the object and the second is the index in the array. The final argument is 185 * a pointer to a BOOL indicating whether the enumeration should stop. Setting 186 * this to YES will interrupt the enumeration. 187 */ 188 - (void) enumerateObjectsUsingBlock: (GSEnumeratorBlock)aBlock; 189 190 /** 191 * Enumerate over the collection using the given block. The first argument is 192 * the object and the second is the index in the array. The final argument is 193 * a pointer to a BOOL indicating whether the enumeration should stop. Setting 194 * this to YES will interrupt the enumeration. 195 * 196 * The opts argument is a bitfield. Setting the NSNSEnumerationConcurrent flag 197 * specifies that it is thread-safe. The NSEnumerationReverse bit specifies 198 * that it should be enumerated in reverse order. 199 */ 200 - (void) enumerateObjectsWithOptions: (NSEnumerationOptions)opts 201 usingBlock: (GSEnumeratorBlock)aBlock; 202 /** 203 * Enumerate over the specified indexes in the collection using the given 204 * block. The first argument is the object and the second is the index in the 205 * array. The final argument is a pointer to a BOOL indicating whether the 206 * enumeration should stop. Setting this to YES will interrupt the 207 * enumeration. 208 * 209 * The opts argument is a bitfield. Setting the NSNSEnumerationConcurrent flag 210 * specifies that it is thread-safe. The NSEnumerationReverse bit specifies 211 * that it should be enumerated in reverse order. 212 */ 213 - (void) enumerateObjectsAtIndexes: (NSIndexSet*)indexSet 214 options: (NSEnumerationOptions)opts 215 usingBlock: (GSEnumeratorBlock)block; 216 /** 217 * Returns the indexes of the objects in a collection that match the condition 218 * specified by the block. 219 * 220 * The opts argument is a bitfield. Setting the NSNSEnumerationConcurrent flag 221 * specifies that it is thread-safe. The NSEnumerationReverse bit specifies 222 * that it should be enumerated in reverse order. 223 */ 224 - (NSIndexSet *) indexesOfObjectsWithOptions: (NSEnumerationOptions)opts 225 passingTest: (GSPredicateBlock)predicate; 226 227 /** 228 * Returns the indexes of the objects in a collection that match the condition 229 * specified by the block. 230 */ 231 - (NSIndexSet*) indexesOfObjectsPassingTest: (GSPredicateBlock)predicate; 232 233 /** 234 * Returns the indexes of the objects in a collection that match the condition 235 * specified by the block and are in the range specified by the index set. 236 * 237 * The opts argument is a bitfield. Setting the NSNSEnumerationConcurrent flag 238 * specifies that it is thread-safe. The NSEnumerationReverse bit specifies 239 * that it should be enumerated in reverse order. 240 */ 241 - (NSIndexSet*) indexesOfObjectsAtIndexes: (NSIndexSet*)indexSet 242 options: (NSEnumerationOptions)opts 243 passingTest: (GSPredicateBlock)predicate; 244 245 /** 246 * Returns the index of the first object in the array that matches the 247 * condition specified by the block. 248 * 249 * The opts argument is a bitfield. Setting the NSNSEnumerationConcurrent flag 250 * specifies that it is thread-safe. The NSEnumerationReverse bit specifies 251 * that it should be enumerated in reverse order. 252 */ 253 - (NSUInteger) indexOfObjectWithOptions: (NSEnumerationOptions)opts 254 passingTest: (GSPredicateBlock)predicate; 255 256 /** 257 * Returns the index of the first object in the array that matches the 258 * condition specified by the block. 259 */ 260 - (NSUInteger) indexOfObjectPassingTest: (GSPredicateBlock)predicate; 261 262 /** 263 * Returns the index of the first object in the specified range in a collection 264 * that matches the condition specified by the block. 265 * 266 * The opts argument is a bitfield. Setting the NSNSEnumerationConcurrent flag 267 * specifies that it is thread-safe. The NSEnumerationReverse bit specifies 268 * that it should be enumerated in reverse order. 269 */ 270 - (NSUInteger) indexOfObjectAtIndexes: (NSIndexSet*)indexSet 271 options: (NSEnumerationOptions)opts 272 passingTest: (GSPredicateBlock)predicate; 273 274 /** Returns a sorted array using the comparator to determine the 275 * order of objects. 276 */ 277 - (GS_GENERIC_CLASS(NSArray, ElementT) *) sortedArrayUsingComparator: 278 (NSComparator)comparator; 279 280 /** Returns a sorted array using the block to determine the order of objects. 281 * 282 * The opts argument is a bitfield. Setting the NSSortConcurrent flag 283 * specifies that it is thread-safe. The NSSortStable bit specifies that 284 * it should keep equal objects in the same order. 285 */ 286 - (GS_GENERIC_CLASS(NSArray, ElementT) *) 287 sortedArrayWithOptions: (NSSortOptions)options 288 usingComparator: (NSComparator)comparator; 289 290 /** 291 * Performs a binary search of the array within the specified range for the 292 * index of an object equal to obj according to cmp. 293 * If NSBinarySearchingInsertionIndex is specified, searches for the index 294 * at which such an object should be inserted. 295 */ 296 - (NSUInteger) indexOfObject: (id)key 297 inSortedRange: (NSRange)range 298 options: (NSBinarySearchingOptions)options 299 usingComparator: (NSComparator)comparator; 300 #endif 301 #endif 302 /** 303 * Accessor for subscripting. This is called by the compiler when you write 304 * code like anArray[12]. It should not be called directly. 305 */ 306 - (GS_GENERIC_TYPE(ElementT)) objectAtIndexedSubscript: (NSUInteger)anIndex; 307 @end 308 309 310 @interface GS_GENERIC_CLASS(NSMutableArray, ElementT) : NSArray 311 312 + (instancetype) arrayWithCapacity: (NSUInteger)numItems; 313 314 /** <override-subclass /> 315 * Adds anObject at the end of the array, thus increasing the size of 316 * the array. The object is retained upon addition. 317 */ 318 - (void) addObject: (GS_GENERIC_TYPE(ElementT))anObject; 319 - (void) addObjectsFromArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)otherArray; 320 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST) 321 - (void) exchangeObjectAtIndex: (NSUInteger)i1 322 withObjectAtIndex: (NSUInteger)i2; 323 #endif 324 325 /** <init /> <override-subclass /> 326 * Initialise the array with the specified capacity ... this 327 * should ensure that the array can have numItems added efficiently.<br /> 328 * Calls -init (which does nothing but maintain MacOS-X compatibility), 329 * and needs to be re-implemented in subclasses in order to have all 330 * other initialisers work. 331 */ 332 - (instancetype) initWithCapacity: (NSUInteger)numItems; 333 334 /** <override-subclass /> 335 * Inserts an object into the receiver at the specified location.<br /> 336 * Raises an exception if given an array index which is too large.<br /> 337 * The size of the array increases by one.<br /> 338 * The object is retained by the array. 339 */ 340 - (void) insertObject: (GS_GENERIC_TYPE(ElementT))anObject 341 atIndex: (NSUInteger)index; 342 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST) 343 - (void) insertObjects: (GS_GENERIC_CLASS(NSArray, ElementT) *)objects 344 atIndexes: (NSIndexSet *)indexes; 345 #endif 346 347 /** <override-subclass /> 348 * Removes an object from the receiver at the specified location.<br /> 349 * The size of the array decreases by one.<br /> 350 * Raises an exception if given an array index which is too large.<br /> 351 */ 352 - (void) removeObjectAtIndex: (NSUInteger)index; 353 354 - (void) removeObjectsAtIndexes: (NSIndexSet *)indexes; 355 356 /** <override-subclass /> 357 * Places an object into the receiver at the specified location.<br /> 358 * Raises an exception if given an array index which is too large.<br /> 359 * The object is retained by the array. 360 */ 361 - (void) replaceObjectAtIndex: (NSUInteger)index 362 withObject: (GS_GENERIC_TYPE(ElementT))anObject; 363 364 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST) 365 - (void) replaceObjectsAtIndexes: (NSIndexSet *)indexes 366 withObjects: (GS_GENERIC_CLASS(NSArray, ElementT)*)objects; 367 #endif 368 369 - (void) replaceObjectsInRange: (NSRange)aRange 370 withObjectsFromArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)anArray; 371 372 - (void) replaceObjectsInRange: (NSRange)aRange 373 withObjectsFromArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)anArray 374 range: (NSRange)anotherRange; 375 376 - (void) setArray: (GS_GENERIC_CLASS(NSArray, ElementT) *)otherArray; 377 378 - (void) removeAllObjects; 379 - (void) removeLastObject; 380 - (void) removeObject: (GS_GENERIC_TYPE(ElementT))anObject; 381 - (void) removeObject: (GS_GENERIC_TYPE(ElementT))anObject 382 inRange: (NSRange)aRange; 383 - (void) removeObjectIdenticalTo: (GS_GENERIC_TYPE(ElementT))anObject; 384 - (void) removeObjectIdenticalTo: (GS_GENERIC_TYPE(ElementT))anObject 385 inRange: (NSRange)aRange; 386 - (void) removeObjectsInArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)otherArray; 387 - (void) removeObjectsInRange: (NSRange)aRange; 388 - (void) removeObjectsFromIndices: (NSUInteger*)indices 389 numIndices: (NSUInteger)count; 390 391 - (void) sortUsingFunction: 392 (NSComparisonResult (*)(GS_GENERIC_TYPE(ElementT), 393 GS_GENERIC_TYPE(ElementT),void*))compare 394 context: (void*)context; 395 - (void) sortUsingSelector: (SEL)comparator; 396 397 398 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) 399 #if __BLOCKS__ 400 /** 401 * Sorts the array using the specified comparator block. 402 */ 403 - (void) sortUsingComparator: (NSComparator)comparator; 404 405 /** 406 * Sorts the array using the specified comparator block and options. 407 */ 408 - (void) sortWithOptions: (NSSortOptions)options 409 usingComparator: (NSComparator)comparator; 410 #endif 411 #endif 412 #if OS_API_VERSION(MAC_OS_X_VERSION_10_8, GS_API_LATEST) 413 /** Set method called by the compiler with array subscripting.<br /> 414 * Replaces the object at anIndex or, if anIndex is the length of the array, 415 * this method appends abObject to the array. 416 */ 417 - (void) setObject: (GS_GENERIC_TYPE(ElementT))anObject 418 atIndexedSubscript: (NSUInteger)anIndex; 419 #endif 420 @end 421 422 #if defined(__cplusplus) 423 } 424 #endif 425 426 #if !NO_GNUSTEP && !defined(GNUSTEP_BASE_INTERNAL) 427 #import "../GNUstepBase/NSArray+GNUstepBase.h" 428 #endif 429 430 #endif /* __NSArray_h_GNUSTEP_BASE_INCLUDE */ 431