ObjFW
OFArray.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008-2024 Jonathan Schleifer <js@nil.im>
3  *
4  * All rights reserved.
5  *
6  * This program is free software: you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License version 3.0 only,
8  * as published by the Free Software Foundation.
9  *
10  * This program is distributed in the hope that it will be useful, but WITHOUT
11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
13  * version 3.0 for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * version 3.0 along with this program. If not, see
17  * <https://www.gnu.org/licenses/>.
18  */
19 
20 #ifndef __STDC_LIMIT_MACROS
21 # define __STDC_LIMIT_MACROS
22 #endif
23 #ifndef __STDC_CONSTANT_MACROS
24 # define __STDC_CONSTANT_MACROS
25 #endif
26 
27 #include <stdarg.h>
28 
29 #import "OFObject.h"
30 #import "OFCollection.h"
31 #import "OFEnumerator.h"
32 #import "OFJSONRepresentation.h"
33 #import "OFMessagePackRepresentation.h"
34 
35 OF_ASSUME_NONNULL_BEGIN
36 
39 @class OFString;
40 
46 typedef enum {
50 
56 typedef enum {
60 
61 #ifdef OF_HAVE_BLOCKS
62 
70 typedef void (^OFArrayEnumerationBlock)(id object, size_t index, bool *stop);
71 
79 typedef bool (^OFArrayFilterBlock)(id object, size_t index);
80 
88 typedef id _Nonnull (^OFArrayMapBlock)(id object, size_t index);
89 
97 typedef id _Nullable (^OFArrayFoldBlock)(id _Nullable left, id right);
98 #endif
99 
107 @interface OFArray OF_GENERIC(ObjectType): OFObject <OFCopying,
110 #if !defined(OF_HAVE_GENERICS) && !defined(DOXYGEN)
111 # define ObjectType id
112 #endif
113 
120 @property (readonly, nonatomic)
121  ObjectType const __unsafe_unretained _Nonnull *_Nonnull objects;
122 
129 @property OF_NULLABLE_PROPERTY (readonly, nonatomic) ObjectType firstObject;
130 
137 @property OF_NULLABLE_PROPERTY (readonly, nonatomic) ObjectType lastObject;
138 
142 @property (readonly, nonatomic) OFArray OF_GENERIC(ObjectType) *sortedArray;
143 
147 @property (readonly, nonatomic) OFArray OF_GENERIC(ObjectType) *reversedArray;
148 
154 + (instancetype)array;
155 
162 + (instancetype)arrayWithObject: (ObjectType)object;
163 
170 + (instancetype)arrayWithObjects: (ObjectType)firstObject, ... OF_SENTINEL;
171 
178 + (instancetype)arrayWithArray: (OFArray OF_GENERIC(ObjectType) *)array;
179 
188 + (instancetype)arrayWithObjects: (ObjectType const _Nonnull *_Nonnull)objects
189  count: (size_t)count;
190 
196 - (instancetype)init OF_DESIGNATED_INITIALIZER;
197 
204 - (instancetype)initWithObject: (ObjectType)object;
205 
212 - (instancetype)initWithObjects: (ObjectType)firstObject, ... OF_SENTINEL;
213 
221 - (instancetype)initWithObject: (ObjectType)firstObject
222  arguments: (va_list)arguments;
223 
230 - (instancetype)initWithArray: (OFArray OF_GENERIC(ObjectType) *)array;
231 
240 - (instancetype)initWithObjects: (ObjectType const _Nonnull *_Nonnull)objects
241  count: (size_t)count OF_DESIGNATED_INITIALIZER;
242 
248 - (OFEnumerator OF_GENERIC(ObjectType) *)objectEnumerator;
249 
259 - (ObjectType)objectAtIndex: (size_t)index;
260 - (ObjectType)objectAtIndexedSubscript: (size_t)index;
261 
275 - (nullable id)valueForKey: (OFString *)key;
276 
287 - (void)setValue: (nullable id)value forKey: (OFString *)key;
288 
295 - (void)getObjects: (ObjectType __unsafe_unretained _Nonnull *_Nonnull)buffer
296  inRange: (OFRange)range;
297 
306 - (size_t)indexOfObject: (ObjectType)object;
307 
316 - (size_t)indexOfObjectIdenticalTo: (ObjectType)object;
317 
325 - (bool)containsObject: (ObjectType)object;
326 
335 - (bool)containsObjectIdenticalTo: (ObjectType)object;
336 
343 - (OFArray OF_GENERIC(ObjectType) *)objectsInRange: (OFRange)range;
344 
351 - (OFString *)componentsJoinedByString: (OFString *)separator;
352 
360 - (OFString *)componentsJoinedByString: (OFString *)separator
361  options: (OFArrayJoinOptions)options;
362 
371 - (OFString *)componentsJoinedByString: (OFString *)separator
372  usingSelector: (SEL)selector;
373 
383 - (OFString *)componentsJoinedByString: (OFString *)separator
384  usingSelector: (SEL)selector
385  options: (OFArrayJoinOptions)options;
386 
392 - (void)makeObjectsPerformSelector: (SEL)selector;
393 
402 - (void)makeObjectsPerformSelector: (SEL)selector
403  withObject: (nullable id)object;
404 
414 - (OFArray OF_GENERIC(ObjectType) *)
415  sortedArrayUsingSelector: (SEL)selector
416  options: (OFArraySortOptions)options;
417 
427 - (OFArray OF_GENERIC(ObjectType) *)
428  sortedArrayUsingFunction: (OFCompareFunction)compare
429  context: (nullable void *)context
430  options: (OFArraySortOptions)options;
431 
432 #ifdef OF_HAVE_BLOCKS
433 
441 - (OFArray OF_GENERIC(ObjectType) *)
442  sortedArrayUsingComparator: (OFComparator)comparator
443  options: (OFArraySortOptions)options;
444 #endif
445 
452 - (OFArray OF_GENERIC(ObjectType) *)arrayByAddingObject: (ObjectType)object;
453 
460 - (OFArray OF_GENERIC(ObjectType) *)arrayByAddingObjectsFromArray:
461  (OFArray OF_GENERIC(ObjectType) *)array;
462 
463 #ifdef OF_HAVE_BLOCKS
464 
469 - (void)enumerateObjectsUsingBlock: (OFArrayEnumerationBlock)block;
470 
477 - (OFArray *)mappedArrayUsingBlock: (OFArrayMapBlock)block;
478 
487 - (OFArray OF_GENERIC(ObjectType) *)filteredArrayUsingBlock:
488  (OFArrayFilterBlock)block;
489 
506 - (nullable id)foldUsingBlock: (OFArrayFoldBlock)block;
507 #endif
508 #if !defined(OF_HAVE_GENERICS) && !defined(DOXYGEN)
509 # undef ObjectType
510 #endif
511 @end
512 
513 OF_ASSUME_NONNULL_END
514 
515 #import "OFMutableArray.h"
516 
517 #if !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
518 /* Required for array literals to work */
519 @compatibility_alias NSArray OFArray;
520 #endif
OFArray * reversedArray
The array with the order reversed.
Definition: OFArray.h:147
instancetype array()
Creates a new OFArray.
Definition: OFArray.m:120
An abstract class for storing objects in an array.
Definition: OFArray.h:107
OFArrayJoinOptions
Options for joining the objects of an array.
Definition: OFArray.h:46
OFArraySortOptions
Options for sorting an array.
Definition: OFArray.h:56
ObjectType firstObject
The first object of the array or nil.
Definition: OFArray.h:129
The root class for all other classes inside ObjFW.
Definition: OFObject.h:690
void(^ OFArrayEnumerationBlock)(id object, size_t index, bool *stop)
A block for enumerating an OFArray.
Definition: OFArray.h:70
A protocol implemented by classes that support encoding to a JSON representation. ...
Definition: OFJSONRepresentation.h:49
OFEnumerator * objectEnumerator()
Returns an OFEnumerator to enumerate through all objects of the array.
Definition: OFArray.m:797
A class for handling strings.
Definition: OFString.h:142
OFArray * sortedArray
The array sorted in ascending order.
Definition: OFArray.h:142
A protocol with methods common for all collections.
id(^ OFArrayMapBlock)(id object, size_t index)
A block for mapping objects to objects in an OFArray.
Definition: OFArray.h:88
ObjectType const __unsafe_unretained * objects
The objects of the array as a C array.
Definition: OFArray.h:121
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition: OFMessagePackRepresentation.h:33
bool(^ OFArrayFilterBlock)(id object, size_t index)
A block for filtering an OFArray.
Definition: OFArray.h:79
ObjectType lastObject
The last object of the array or nil.
Definition: OFArray.h:137
OFComparisonResult(^ OFComparator)(id left, id right)
A comparator to compare two objects.
Definition: OFObject.h:86
A protocol for the creation of mutable copies.
Definition: OFObject.h:1371
A protocol for the creation of copies.
Definition: OFObject.h:1350
instancetype init()
Initializes an OFArray with no objects.
Definition: OFArray.m:155
Definition: OFArray.h:48
A class which provides methods to enumerate through collections.
Definition: OFEnumerator.h:103
A range.
Definition: OFObject.h:110
id(^ OFArrayFoldBlock)(id left, id right)
A block for folding an OFArray.
Definition: OFArray.h:97
OFComparisonResult(* OFCompareFunction)(id left, id right, void *context)
A function to compare two objects.
Definition: OFObject.h:75
Definition: OFArray.h:58