ObjFW
OFDictionary.h
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 
37 @class OFArray OF_GENERIC(ObjectType);
38 
39 #ifdef OF_HAVE_BLOCKS
40 
48 typedef void (^OFDictionaryEnumerationBlock)(id key, id object, bool *stop);
49 
57 typedef bool (^OFDictionaryFilterBlock)(id key, id object);
58 
66 typedef id _Nonnull (^OFDictionaryMapBlock)(id key, id object);
67 #endif
68 
82 @interface OFDictionary OF_GENERIC(KeyType, ObjectType): OFObject <OFCopying,
85 #if !defined(OF_HAVE_GENERICS) && !defined(DOXYGEN)
86 # define KeyType id
87 # define ObjectType id
88 #endif
89 
92 @property (readonly, nonatomic) OFArray OF_GENERIC(KeyType) *allKeys;
93 
97 @property (readonly, nonatomic) OFArray OF_GENERIC(ObjectType) *allObjects;
98 
104 + (instancetype)dictionary;
105 
112 + (instancetype)dictionaryWithDictionary:
113  (OFDictionary OF_GENERIC(KeyType, ObjectType) *)dictionary;
114 
122 + (instancetype)dictionaryWithObject: (ObjectType)object forKey: (KeyType)key;
123 
131 + (instancetype)dictionaryWithObjects: (OFArray OF_GENERIC(ObjectType) *)objects
132  forKeys: (OFArray OF_GENERIC(KeyType) *)keys;
133 
142 + (instancetype)
143  dictionaryWithObjects: (ObjectType const _Nonnull *_Nonnull)objects
144  forKeys: (KeyType const _Nonnull *_Nonnull)keys
145  count: (size_t)count;
146 
153 + (instancetype)dictionaryWithKeysAndObjects: (KeyType)firstKey, ...
154  OF_SENTINEL;
155 
161 - (instancetype)init OF_DESIGNATED_INITIALIZER;
162 
170 - (instancetype)initWithDictionary:
171  (OFDictionary OF_GENERIC(KeyType, ObjectType) *)dictionary;
172 
181 - (instancetype)initWithObject: (ObjectType)object forKey: (KeyType)key;
182 
191 - (instancetype)initWithObjects: (OFArray OF_GENERIC(ObjectType) *)objects
192  forKeys: (OFArray OF_GENERIC(KeyType) *)keys;
193 
203 - (instancetype)initWithObjects: (ObjectType const _Nonnull *_Nonnull)objects
204  forKeys: (KeyType const _Nonnull *_Nonnull)keys
205  count: (size_t)count OF_DESIGNATED_INITIALIZER;
206 
214 - (instancetype)initWithKeysAndObjects: (KeyType)firstKey, ... OF_SENTINEL;
215 
224 - (instancetype)initWithKey: (KeyType)firstKey arguments: (va_list)arguments;
225 
236 - (nullable ObjectType)objectForKey: (KeyType)key;
237 - (nullable ObjectType)objectForKeyedSubscript: (KeyType)key;
238 
250 - (nullable id)valueForKey: (OFString *)key;
251 
261 - (void)setValue: (nullable id)value forKey: (OFString *)key;
262 
270 - (bool)containsObject: (ObjectType)object;
271 
280 - (bool)containsObjectIdenticalTo: (ObjectType)object;
281 
287 - (OFEnumerator OF_GENERIC(KeyType) *)keyEnumerator;
288 
294 - (OFEnumerator OF_GENERIC(ObjectType) *)objectEnumerator;
295 
296 #ifdef OF_HAVE_BLOCKS
297 
302 - (void)enumerateKeysAndObjectsUsingBlock: (OFDictionaryEnumerationBlock)block;
303 
311 - (OFDictionary OF_GENERIC(KeyType, id) *)
312  mappedDictionaryUsingBlock: (OFDictionaryMapBlock)block;
313 
322 - (OFDictionary OF_GENERIC(KeyType, ObjectType) *)
323  filteredDictionaryUsingBlock: (OFDictionaryFilterBlock)block;
324 #endif
325 #if !defined(OF_HAVE_GENERICS) && !defined(DOXYGEN)
326 # undef KeyType
327 # undef ObjectType
328 #endif
329 @end
330 
331 OF_ASSUME_NONNULL_END
332 
333 #import "OFMutableDictionary.h"
334 
335 #if !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
336 /* Required for dictionary literals to work */
337 @compatibility_alias NSDictionary OFDictionary;
338 #endif
An abstract class for storing objects in an array.
Definition: OFArray.h:107
OFArray * allObjects
An array of all objects.
Definition: OFDictionary.h:97
instancetype dictionary()
Creates a new OFDictionary.
Definition: OFDictionary.m:140
The root class for all other classes inside ObjFW.
Definition: OFObject.h:690
A protocol implemented by classes that support encoding to a JSON representation. ...
Definition: OFJSONRepresentation.h:49
A class for handling strings.
Definition: OFString.h:142
OFEnumerator * keyEnumerator()
Returns an OFEnumerator to enumerate through the dictionary&#39;s keys.
Definition: OFDictionary.m:521
instancetype init()
Initializes an already allocated OFDictionary to be empty.
Definition: OFDictionary.m:185
An abstract class for storing objects in a dictionary.
Definition: OFDictionary.h:82
A protocol with methods common for all collections.
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition: OFMessagePackRepresentation.h:33
OFArray * allKeys
An array of all keys.
Definition: OFDictionary.h:92
A protocol for the creation of mutable copies.
Definition: OFObject.h:1371
A protocol for the creation of copies.
Definition: OFObject.h:1350
A class which provides methods to enumerate through collections.
Definition: OFEnumerator.h:103
OFEnumerator * objectEnumerator()
Returns an OFEnumerator to enumerate through the dictionary&#39;s objects.
Definition: OFDictionary.m:526