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