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 file is part of ObjFW. It may be distributed under the terms of the
7  * Q Public License 1.0, which can be found in the file LICENSE.QPL included in
8  * the packaging of this file.
9  *
10  * Alternatively, it may be distributed under the terms of the GNU General
11  * Public License, either version 2 or 3, which can be found in the file
12  * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this
13  * file.
14  */
15 
16 #ifndef __STDC_LIMIT_MACROS
17 # define __STDC_LIMIT_MACROS
18 #endif
19 #ifndef __STDC_CONSTANT_MACROS
20 # define __STDC_CONSTANT_MACROS
21 #endif
22 
23 #include <stdarg.h>
24 
25 #import "OFObject.h"
26 #import "OFCollection.h"
27 #import "OFEnumerator.h"
28 #import "OFJSONRepresentation.h"
29 #import "OFMessagePackRepresentation.h"
30 
31 OF_ASSUME_NONNULL_BEGIN
32 
35 @class OFString;
36 
42 typedef enum {
46 
52 typedef enum {
56 
57 #ifdef OF_HAVE_BLOCKS
66 typedef void (^OFArrayEnumerationBlock)(id object, size_t index, bool *stop);
67 
75 typedef bool (^OFArrayFilterBlock)(id object, size_t index);
76 
84 typedef id _Nonnull (^OFArrayMapBlock)(id object, size_t index);
85 
93 typedef id _Nullable (^OFArrayFoldBlock)(id _Nullable left, id right);
94 #endif
95 
103 @interface OFArray OF_GENERIC(ObjectType): OFObject <OFCopying,
106 #if !defined(OF_HAVE_GENERICS) && !defined(DOXYGEN)
107 # define ObjectType id
108 #endif
116 @property (readonly, nonatomic)
117  ObjectType const __unsafe_unretained _Nonnull *_Nonnull objects;
118 
125 @property OF_NULLABLE_PROPERTY (readonly, nonatomic) ObjectType firstObject;
126 
133 @property OF_NULLABLE_PROPERTY (readonly, nonatomic) ObjectType lastObject;
134 
138 @property (readonly, nonatomic) OFArray OF_GENERIC(ObjectType) *sortedArray;
139 
143 @property (readonly, nonatomic) OFArray OF_GENERIC(ObjectType) *reversedArray;
144 
150 + (instancetype)array;
151 
158 + (instancetype)arrayWithObject: (ObjectType)object;
159 
166 + (instancetype)arrayWithObjects: (ObjectType)firstObject, ... OF_SENTINEL;
167 
174 + (instancetype)arrayWithArray: (OFArray OF_GENERIC(ObjectType) *)array;
175 
184 + (instancetype)arrayWithObjects: (ObjectType const _Nonnull *_Nonnull)objects
185  count: (size_t)count;
186 
192 - (instancetype)init OF_DESIGNATED_INITIALIZER;
193 
200 - (instancetype)initWithObject: (ObjectType)object;
201 
208 - (instancetype)initWithObjects: (ObjectType)firstObject, ... OF_SENTINEL;
209 
217 - (instancetype)initWithObject: (ObjectType)firstObject
218  arguments: (va_list)arguments;
219 
226 - (instancetype)initWithArray: (OFArray OF_GENERIC(ObjectType) *)array;
227 
236 - (instancetype)initWithObjects: (ObjectType const _Nonnull *_Nonnull)objects
237  count: (size_t)count OF_DESIGNATED_INITIALIZER;
238 
244 - (OFEnumerator OF_GENERIC(ObjectType) *)objectEnumerator;
245 
255 - (ObjectType)objectAtIndex: (size_t)index;
256 - (ObjectType)objectAtIndexedSubscript: (size_t)index;
257 
271 - (nullable id)valueForKey: (OFString *)key;
272 
283 - (void)setValue: (nullable id)value forKey: (OFString *)key;
284 
291 - (void)getObjects: (ObjectType __unsafe_unretained _Nonnull *_Nonnull)buffer
292  inRange: (OFRange)range;
293 
302 - (size_t)indexOfObject: (ObjectType)object;
303 
312 - (size_t)indexOfObjectIdenticalTo: (ObjectType)object;
313 
321 - (bool)containsObject: (ObjectType)object;
322 
331 - (bool)containsObjectIdenticalTo: (ObjectType)object;
332 
339 - (OFArray OF_GENERIC(ObjectType) *)objectsInRange: (OFRange)range;
340 
347 - (OFString *)componentsJoinedByString: (OFString *)separator;
348 
356 - (OFString *)componentsJoinedByString: (OFString *)separator
357  options: (OFArrayJoinOptions)options;
358 
367 - (OFString *)componentsJoinedByString: (OFString *)separator
368  usingSelector: (SEL)selector;
369 
379 - (OFString *)componentsJoinedByString: (OFString *)separator
380  usingSelector: (SEL)selector
381  options: (OFArrayJoinOptions)options;
382 
388 - (void)makeObjectsPerformSelector: (SEL)selector;
389 
398 - (void)makeObjectsPerformSelector: (SEL)selector
399  withObject: (nullable id)object;
400 
410 - (OFArray OF_GENERIC(ObjectType) *)
411  sortedArrayUsingSelector: (SEL)selector
412  options: (OFArraySortOptions)options;
413 
423 - (OFArray OF_GENERIC(ObjectType) *)
424  sortedArrayUsingFunction: (OFCompareFunction)compare
425  context: (nullable void *)context
426  options: (OFArraySortOptions)options;
427 
428 #ifdef OF_HAVE_BLOCKS
437 - (OFArray OF_GENERIC(ObjectType) *)
438  sortedArrayUsingComparator: (OFComparator)comparator
439  options: (OFArraySortOptions)options;
440 #endif
441 
448 - (OFArray OF_GENERIC(ObjectType) *)arrayByAddingObject: (ObjectType)object;
449 
456 - (OFArray OF_GENERIC(ObjectType) *)arrayByAddingObjectsFromArray:
457  (OFArray OF_GENERIC(ObjectType) *)array;
458 
459 #ifdef OF_HAVE_BLOCKS
465 - (void)enumerateObjectsUsingBlock: (OFArrayEnumerationBlock)block;
466 
473 - (OFArray *)mappedArrayUsingBlock: (OFArrayMapBlock)block;
474 
483 - (OFArray OF_GENERIC(ObjectType) *)filteredArrayUsingBlock:
484  (OFArrayFilterBlock)block;
485 
502 - (nullable id)foldUsingBlock: (OFArrayFoldBlock)block;
503 #endif
504 #if !defined(OF_HAVE_GENERICS) && !defined(DOXYGEN)
505 # undef ObjectType
506 #endif
507 @end
508 
509 OF_ASSUME_NONNULL_END
510 
511 #import "OFMutableArray.h"
512 
513 #if !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
514 /* Required for array literals to work */
515 @compatibility_alias NSArray OFArray;
516 #endif
bool(^ OFArrayFilterBlock)(id object, size_t index)
A block for filtering an OFArray.
Definition: OFArray.h:75
id(^ OFArrayFoldBlock)(id left, id right)
A block for folding an OFArray.
Definition: OFArray.h:93
OFArraySortOptions
Options for sorting an array.
Definition: OFArray.h:52
@ OFArraySortDescending
Definition: OFArray.h:54
void(^ OFArrayEnumerationBlock)(id object, size_t index, bool *stop)
A block for enumerating an OFArray.
Definition: OFArray.h:66
id(^ OFArrayMapBlock)(id object, size_t index)
A block for mapping objects to objects in an OFArray.
Definition: OFArray.h:84
OFArrayJoinOptions
Options for joining the objects of an array.
Definition: OFArray.h:42
@ OFArraySkipEmptyComponents
Definition: OFArray.h:44
OFComparisonResult(^ OFComparator)(id left, id right)
A comparator to compare two objects.
Definition: OFObject.h:82
OFComparisonResult(* OFCompareFunction)(id left, id right, void *context)
A function to compare two objects.
Definition: OFObject.h:71
An abstract class for storing objects in an array.
Definition: OFArray.h:105
ObjectType const __unsafe_unretained * objects
The objects of the array as a C array.
Definition: OFArray.h:117
instancetype init()
Initializes an OFArray with no objects.
Definition: OFArray.m:151
OFArray * sortedArray
The array sorted in ascending order.
Definition: OFArray.h:138
ObjectType lastObject
The last object of the array or nil.
Definition: OFArray.h:133
ObjectType firstObject
The first object of the array or nil.
Definition: OFArray.h:125
instancetype array()
Creates a new OFArray.
Definition: OFArray.m:116
OFEnumerator * objectEnumerator()
Returns an OFEnumerator to enumerate through all objects of the array.
Definition: OFArray.m:793
OFArray * reversedArray
The array with the order reversed.
Definition: OFArray.h:143
A class which provides methods to enumerate through collections.
Definition: OFEnumerator.h:99
The root class for all other classes inside ObjFW.
Definition: OFObject.h:688
A class for handling strings.
Definition: OFString.h:135
A protocol with methods common for all collections.
Definition: OFCollection.h:25
A protocol for the creation of copies.
Definition: OFObject.h:1346
A protocol implemented by classes that support encoding to a JSON representation.
Definition: OFJSONRepresentation.h:44
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition: OFMessagePackRepresentation.h:29
A protocol for the creation of mutable copies.
Definition: OFObject.h:1367
A range.
Definition: OFObject.h:106