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 */