ObjFW  Check-in [851e47d743]

Overview
Comment:Documentation improvements.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 851e47d743680c38b340ab11404f7b929de00991633feaf43f1900e3253b9fa4
User & Date: js on 2011-05-04 22:22:15
Other Links: manifest | tags
Context
2011-05-04
22:35
Improve Doxyfile. check-in: 8588bd03b2 user: js tags: trunk
22:22
Documentation improvements. check-in: 851e47d743 user: js tags: trunk
2011-05-02
20:46
Add +[OFString stringWithUnicodeString:length:]. check-in: 04ffb67949 user: js tags: trunk
Changes

Modified src/OFObject.h from [ae7d2dccfa] to [dcd1dc9c0c].

61
62
63
64
65
66
67


68
69
70
71
72


73
74
75
76
77
78



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146


147
148
149
150
151
152
153
154
155
156
157
158
159
160
161


162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177

178
179
180
181
182
183
184
185
186
187
188
189


190
191
192
193
194
195
196
197
198
199
200
201
202
203
204


205
206
207
208
209


210
211
212
213
214



215
216
217
218
219
220
221


222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243



244
245
246
247
248
249
250



251
252
253
254
255
256
257
258
259


260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284

285
286
287
288
289
290
291
292
293
294

295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314


315
316
317
318
319


320
321
322
323
324
325
326
327

328
329
330
331
332
333
334

335
336
337
338
339
340
341
342


343
344
345
346
347
348
349
350
351
352
353
354
355
356
357

358
359
360
361
362
363
364
365
366


367
368
369
370
371
372
373
374
375
376
377
378
379



380
381
382
383
384
385
386
387
388
389
390



391
392
393
394
395
396
397
398
399
400
401

402
403
404
405
406
407
408
409
410
411



412
413
414
415
416


417




418
419
420
421
422
423
424
425
426






427
428
429
430
431
432
433
434
435
436
437
438
439


440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
@class OFString;

/**
 * \brief The protocol which all root classes implement.
 */
@protocol OFObject
/**


 * \return The class of the object
 */
- (Class)class;

/**


 * \param class_ The class whose kind is checked
 * \return A boolean whether the object is of the specified kind
 */
- (BOOL)isKindOfClass: (Class)class_;

/**



 * \param selector The selector which should be checked for respondance
 * \return A boolean whether the objects responds to the specified selector
 */
- (BOOL)respondsToSelector: (SEL)selector;

/**
 * Performs the specified selector.
 *
 * \param selector The selector to perform
 * \return The object returned by the method specified by the selector
 */
- (id)performSelector: (SEL)selector;

/**
 * Performs the specified selector with the specified object.
 *
 * \param selector The selector to perform
 * \param object The object that is passed to the method specified by the
 *		 selector
 * \return The object returned by the method specified by the selector
 */
- (id)performSelector: (SEL)selector
	   withObject: (id)object;

/**
 * Performs the specified selector with the specified objects.
 *
 * \param selector The selector to perform
 * \param object The first object that is passed to the method specified by the
 *		 selector
 * \param otherObject The second object that is passed to the method specified
 *		      by the selector
 * \return The object returned by the method specified by the selector
 */
- (id)performSelector: (SEL)selector
	   withObject: (id)object
	   withObject: (id)otherObject;

/**
 * Checks two objects for equality.
 *
 * Classes containing data (like strings, arrays, lists etc.) should reimplement
 * this!
 *
 * \param object The object which should be tested for equality
 * \return A boolean whether the object is equal to the specified object
 */
- (BOOL)isEqual: (id)object;

/**
 * Calculates a hash for the object.
 *
 * Classes containing data (like strings, arrays, lists etc.) should reimplement
 * this!
 *
 * \return A 32 bit hash for the object
 */
- (uint32_t)hash;

/**
 * Increases the retain count.
 *
 * Each time an object is released, the retain count gets decreased and the
 * object deallocated if it reaches 0.
 */
- retain;

/**


 * \return The retain count
 */
- (unsigned int)retainCount;

/**
 * Decreases the retain count.
 *
 * Each time an object is released, the retain count gets decreased and the
 * object deallocated if it reaches 0.
 */
- (void)release;

/**
 * Adds the object to the topmost OFAutoreleasePool of the thread's release pool
 * stack.


 */
- autorelease;
@end

/**
 * \brief The root class for all other classes inside ObjFW.
 */
@interface OFObject <OFObject>
{
@public
	/// The class of the object
	Class isa;
}

/**
 * This code is executed once when the class is loaded into the runtime.

 *
 * Derived classes can overide this to execute their own code when the class is
 * loaded.
 */
+ (void)load;

/**
 * This code is executed once when a method of the class is called for the first
 * time.
 *
 * Derived classes can override this to execute their own code on
 * initialization.


 */
+ (void)initialize;

/**
 * Allocates memory for an instance of the class and sets up the memory pool for
 * the object.
 *
 * alloc will never return nil, instead, it will throw an
 * OFAllocFailedException.
 *
 * \return The allocated object.
 */
+ alloc;

/**


 * \return The class
 */
+ (Class)class;

/**


 * \return The name of the class as a C string
 */
+ (OFString*)className;

/**



 * \param class_ The class which is checked for being a superclass
 * \return A boolean whether the class class is a subclass of the specified
 *	   class
 */
+ (BOOL)isSubclassOfClass: (Class)class_;

/**


 * \return The superclass of the class
 */
+ (Class)superclass;

/**
 * Checks whether instances of the class respond to a given selector.
 *
 * \param selector The selector which should be checked for respondance
 * \return A boolean whether instances of the class respond to the specified
 *	   selector
 */
+ (BOOL)instancesRespondToSelector: (SEL)selector;

/**
 * Checks whether the class conforms to a given protocol.
 *
 * \param protocol The protocol which should be checked for conformance
 * \return A boolean whether the class conforms to the specified protocol
 */
+ (BOOL)conformsToProtocol: (Protocol*)protocol;

/**



 * \param selector The selector for which the method should be returned
 * \return The implementation of the instance method for the specified selector
 *	   or nil if it isn't implemented
 */
+ (IMP)instanceMethodForSelector: (SEL)selector;

/**



 * \param selector The selector for which the type encoding should be returned
 * \return The type encoding of the instance method for the specified selector
 */
+ (const char*)typeEncodingForInstanceSelector: (SEL)selector;

/**
 * Returns a description for the class, which is usually the class name.
 *
 * This is mostly for debugging purposes.


 */
+ (OFString*)description;

/**
 * Replaces a class method implementation with another implementation.
 *
 * \param newImp The new implementation for the class method
 * \param selector The selector of the class method to replace
 * \return The old implementation
 */
+ (IMP)setImplementation: (IMP)newImp
	  forClassMethod: (SEL)selector;

/**
 * Replaces a class method with a class method from another class.
 *
 * \param selector The selector of the class method to replace
 * \param class_ The class from which the new class method should be taken
 * \return The old implementation
 */
+ (IMP)replaceClassMethod: (SEL)selector
      withMethodFromClass: (Class)class_;

/**
 * Replaces an instance method implementation with another implementation.

 *
 * \param newImp The new implementation for the instance method
 * \param selector The selector of the instance method to replace
 * \return The old implementation
 */
+ (IMP)setImplementation: (IMP)newImp
       forInstanceMethod: (SEL)selector;

/**
 * Replaces an instance method with an instance method from another class.

 *
 * \param selector The selector of the instance method to replace
 * \param class_ The class from which the new instance method should be taken
 * \return The old implementation
 */
+ (IMP)replaceInstanceMethod: (SEL)selector
	 withMethodFromClass: (Class)class_;

/**
 * Initializes an already allocated object.
 *
 * Derived classes may override this, but need to do self = [super init] before
 * they do any initialization themselves. init may never return nil, instead
 * an exception (for example OFInitializationFailed) should be thrown.
 *
 * \return An initialized object
 */
- init;

/**


 * \return The name of the object's class.
 */
- (OFString*)className;

/**


 * \param protocol The protocol which should be checked for conformance
 * \return A boolean whether the objects conforms to the specified protocol
 */
- (BOOL)conformsToProtocol: (Protocol*)protocol;

/**
 * \param selector The selector for which the method should be returned
 *

 * \return The implementation for the specified selector
 */
- (IMP)methodForSelector: (SEL)selector;

/**
 * \param selector The selector for which the type encoding should be returned
 *

 * \return The type encoding for the specified selector
 */
- (const char*)typeEncodingForSelector: (SEL)selector;

/**
 * Returns a description for the object.
 *
 * This is mostly for debugging purposes.


 */
- (OFString*)description;

/**
 * Adds a pointer to the object's memory pool.
 *
 * This is useful to add memory allocated by functions such as asprintf to the
 * pool so it gets free'd automatically when the object is deallocated.
 *
 * \param ptr A pointer to add to the memory pool
 */
- (void)addMemoryToPool: (void*)ptr;

/**
 * Allocates memory and stores it in the object's memory pool so it can be

 * free'd automatically when the object is deallocated.
 *
 * \param size The size of the memory to allocate
 * \return A pointer to the allocated memory
 */
- (void*)allocMemoryWithSize: (size_t)size;

/**
 * Allocates memory for the specified number of items and stores it in the


 * object's memory pool so it can be free'd automatically when the object is
 * deallocated.
 *
 * \param nItems The number of items to allocate
 * \param size The size of each item to allocate
 * \return A pointer to the allocated memory
 */
- (void*)allocMemoryForNItems: (size_t)nItems
		     withSize: (size_t)size;

/**
 * Resizes memory in the object's memory pool to the specified size.
 *



 * \param ptr A pointer to the already allocated memory
 * \param size The new size for the memory chunk
 * \return A pointer to the resized memory chunk
 */
- (void*)resizeMemory: (void*)ptr
	       toSize: (size_t)size;

/**
 * Resizes memory in the object's memory pool to the specific number of items of
 * the specified size.
 *



 * \param ptr A pointer to the already allocated memory
 * \param nItems The number of items to resize to
 * \param size The size of each item to resize to
 * \return A pointer to the resized memory chunk
 */
- (void*)resizeMemory: (void*)ptr
	     toNItems: (size_t)nItems
	     withSize: (size_t)size;

/**
 * Frees allocated memory and removes it from the object's memory pool.

 * Does nothing if ptr is NULL.
 *
 * \param ptr A pointer to the allocated memory
 */
- (void)freeMemory: (void*)ptr;

/**
 * Deallocates the object and also frees all memory in its memory pool.
 *
 * It is also called when the retain count reaches zero.



 */
- (void)dealloc;

/**
 * If a garbage collector is added in the future, this method will be called


 * before it disposes of the object, for example to close files.




 */
- (void)finalize;
@end

/**
 * \brief A protocol for the creation of copies.
 */
@protocol OFCopying <OFObject>
/**






 * \return A copy of the object
 */
- copy;
@end

/**
 * \brief A protocol for the creation of mutable copies.
 *
 * This protocol is implemented by objects that can be mutable and immutable
 * and allows returning a mutable copy.
 */
@protocol OFMutableCopying <OFCopying>
/**


 * \return A mutable copy of the object
 */
- mutableCopy;
@end

/**
 * \brief A protocol for comparing objects.
 *
 * This protocol is implemented by objects that can be compared.
 */
@protocol OFComparing <OFObject>
/**
 * Compares the object with another object.
 *
 * \param object An object to compare the object to
 * \return The result of the comparison
 */
- (of_comparison_result_t)compare: (id)object;
@end








>
>





>
>






>
>
>






|







|










|













|










|









|







>
>





|







|
|
>
>















|
>







|
|


|
>
>




|
|

|







>
>





>
>
|




>
>
>

|
<




>
>





|








|







>
>
>







>
>
>






|


>
>




|









|









|
>









|
>









|










>
>
|




>
>

|




|

>





|

>





|


>
>




|




|

|


|
>
|







|
>
>
|
<









|

>
>
>
|



|



|
|

>
>
>
|




|




|
>
|

|

|


|

|
>
>
>




|
>
>
|
>
>
>
>









>
>
>
>
>
>













>
>












|







61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237

238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410

411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
@class OFString;

/**
 * \brief The protocol which all root classes implement.
 */
@protocol OFObject
/**
 * \brief Returns the class of the object.
 *
 * \return The class of the object
 */
- (Class)class;

/**
 * \brief Returns a boolean whether the object of the specified kind.
 *
 * \param class_ The class whose kind is checked
 * \return A boolean whether the object is of the specified kind
 */
- (BOOL)isKindOfClass: (Class)class_;

/**
 * \brief Returns a boolean whether the object responds to the specified
 *	  selector.
 *
 * \param selector The selector which should be checked for respondance
 * \return A boolean whether the objects responds to the specified selector
 */
- (BOOL)respondsToSelector: (SEL)selector;

/**
 * \brief Performs the specified selector.
 *
 * \param selector The selector to perform
 * \return The object returned by the method specified by the selector
 */
- (id)performSelector: (SEL)selector;

/**
 * \brief Performs the specified selector with the specified object.
 *
 * \param selector The selector to perform
 * \param object The object that is passed to the method specified by the
 *		 selector
 * \return The object returned by the method specified by the selector
 */
- (id)performSelector: (SEL)selector
	   withObject: (id)object;

/**
 * \brief Performs the specified selector with the specified objects.
 *
 * \param selector The selector to perform
 * \param object The first object that is passed to the method specified by the
 *		 selector
 * \param otherObject The second object that is passed to the method specified
 *		      by the selector
 * \return The object returned by the method specified by the selector
 */
- (id)performSelector: (SEL)selector
	   withObject: (id)object
	   withObject: (id)otherObject;

/**
 * \brief Checks two objects for equality.
 *
 * Classes containing data (like strings, arrays, lists etc.) should reimplement
 * this!
 *
 * \param object The object which should be tested for equality
 * \return A boolean whether the object is equal to the specified object
 */
- (BOOL)isEqual: (id)object;

/**
 * \brief Calculates a hash for the object.
 *
 * Classes containing data (like strings, arrays, lists etc.) should reimplement
 * this!
 *
 * \return A 32 bit hash for the object
 */
- (uint32_t)hash;

/**
 * \brief Increases the retain count.
 *
 * Each time an object is released, the retain count gets decreased and the
 * object deallocated if it reaches 0.
 */
- retain;

/**
 * \brief Returns the retain count.
 *
 * \return The retain count
 */
- (unsigned int)retainCount;

/**
 * \brief Decreases the retain count.
 *
 * Each time an object is released, the retain count gets decreased and the
 * object deallocated if it reaches 0.
 */
- (void)release;

/**
 * \brief Adds the object to the topmost OFAutoreleasePool of the thread's
 *	  autorelease pool stack.
 *
 * \return The object
 */
- autorelease;
@end

/**
 * \brief The root class for all other classes inside ObjFW.
 */
@interface OFObject <OFObject>
{
@public
	/// The class of the object
	Class isa;
}

/**
 * \brief A method which is called once when the class is loaded into the
 *	  runtime.
 *
 * Derived classes can overide this to execute their own code when the class is
 * loaded.
 */
+ (void)load;

/**
 * \brief A method which is called the moment before the first call to the class
 *	  is being made.
 *
 * Derived classes can override this to execute their own code on
 * initialization. They should make sure to not execute any code if self is not
 * the class itself, as it might happen that the method was called for a
 * subclass which did not override this method.
 */
+ (void)initialize;

/**
 * \brief Allocates memory for an instance of the class and sets up the memory
 *	  pool for the object.
 *
 * This method will never return nil, instead, it will throw an
 * OFAllocFailedException.
 *
 * \return The allocated object.
 */
+ alloc;

/**
 * \brief Returns the class.
 *
 * \return The class
 */
+ (Class)class;

/**
 * \brief Returns the name of the class as a string.
 *
 * \return The name of the class as a string
 */
+ (OFString*)className;

/**
 * \brief Returns a boolean whether the class is a subclass of the specified
 *	  class.
 *
 * \param class_ The class which is checked for being a superclass
 * \return A boolean whether the class is a subclass of the specified class

 */
+ (BOOL)isSubclassOfClass: (Class)class_;

/**
 * \brief Returns the superclass of the class.
 *
 * \return The superclass of the class
 */
+ (Class)superclass;

/**
 * \brief Checks whether instances of the class respond to a given selector.
 *
 * \param selector The selector which should be checked for respondance
 * \return A boolean whether instances of the class respond to the specified
 *	   selector
 */
+ (BOOL)instancesRespondToSelector: (SEL)selector;

/**
 * \brief Checks whether the class conforms to a given protocol.
 *
 * \param protocol The protocol which should be checked for conformance
 * \return A boolean whether the class conforms to the specified protocol
 */
+ (BOOL)conformsToProtocol: (Protocol*)protocol;

/**
 * \brief Returns the implementation of the instance method for the specified
 *	  selector.
 *
 * \param selector The selector for which the method should be returned
 * \return The implementation of the instance method for the specified selector
 *	   or nil if it isn't implemented
 */
+ (IMP)instanceMethodForSelector: (SEL)selector;

/**
 * \brief Returns the type encoding of the instance method for the specified
 *	  selector.
 *
 * \param selector The selector for which the type encoding should be returned
 * \return The type encoding of the instance method for the specified selector
 */
+ (const char*)typeEncodingForInstanceSelector: (SEL)selector;

/**
 * \brief Returns a description for the class, which is usually the class name.
 *
 * This is mostly for debugging purposes.
 *
 * \return A description for the class, which is usually the class name
 */
+ (OFString*)description;

/**
 * \brief Replaces a class method implementation with another implementation.
 *
 * \param newImp The new implementation for the class method
 * \param selector The selector of the class method to replace
 * \return The old implementation
 */
+ (IMP)setImplementation: (IMP)newImp
	  forClassMethod: (SEL)selector;

/**
 * \brief Replaces a class method with a class method from another class.
 *
 * \param selector The selector of the class method to replace
 * \param class_ The class from which the new class method should be taken
 * \return The old implementation
 */
+ (IMP)replaceClassMethod: (SEL)selector
      withMethodFromClass: (Class)class_;

/**
 * \brief Replaces an instance method implementation with another
 *	  implementation.
 *
 * \param newImp The new implementation for the instance method
 * \param selector The selector of the instance method to replace
 * \return The old implementation
 */
+ (IMP)setImplementation: (IMP)newImp
       forInstanceMethod: (SEL)selector;

/**
 * \brief Replaces an instance method with an instance method from another
 *	  class.
 *
 * \param selector The selector of the instance method to replace
 * \param class_ The class from which the new instance method should be taken
 * \return The old implementation
 */
+ (IMP)replaceInstanceMethod: (SEL)selector
	 withMethodFromClass: (Class)class_;

/**
 * \brief Initializes an already allocated object.
 *
 * Derived classes may override this, but need to do self = [super init] before
 * they do any initialization themselves. init may never return nil, instead
 * an exception (for example OFInitializationFailed) should be thrown.
 *
 * \return An initialized object
 */
- init;

/**
 * \brief Returns the name of the object's class.
 *
 * \return The name of the object's class
 */
- (OFString*)className;

/**
 * \brief Checks whether the object conforms to the specified protocol.
 *
 * \param protocol The protocol which should be checked for conformance
 * \return A boolean whether the object conforms to the specified protocol
 */
- (BOOL)conformsToProtocol: (Protocol*)protocol;

/**
 * \brief Returns the implementation for the specified selector.
 *
 * \param selector The selector for which the method should be returned
 * \return The implementation for the specified selector
 */
- (IMP)methodForSelector: (SEL)selector;

/**
 * \brief Returns the type encoding for the specified selector.
 *
 * \param selector The selector for which the type encoding should be returned
 * \return The type encoding for the specified selector
 */
- (const char*)typeEncodingForSelector: (SEL)selector;

/**
 * \brief Returns a description for the object.
 *
 * This is mostly for debugging purposes.
 *
 * \return A description for the object
 */
- (OFString*)description;

/**
 * \brief Adds a pointer to the object's memory pool.
 *
 * This is useful to add memory allocated by functions such as asprintf to the
 * pool so it gets free'd automatically when the object is deallocated.
 *
 * \param pointer A pointer to add to the memory pool
 */
- (void)addMemoryToPool: (void*)pointer;

/**
 * \brief Allocates memory and stores it in the object's memory pool.
 *
 * It will be free'd automatically when the object is deallocated.
 *
 * \param size The size of the memory to allocate
 * \return A pointer to the allocated memory
 */
- (void*)allocMemoryWithSize: (size_t)size;

/**
 * \brief Allocates memory for the specified number of items and stores it in
 *	  the object's memory pool.
 *
 * It will be free'd automatically when the object is deallocated.

 *
 * \param nItems The number of items to allocate
 * \param size The size of each item to allocate
 * \return A pointer to the allocated memory
 */
- (void*)allocMemoryForNItems: (size_t)nItems
		     withSize: (size_t)size;

/**
 * \brief Resizes memory in the object's memory pool to the specified size.
 *
 * If the pointer is NULL, this is equivalent to allocating memory.
 * If the size is 0, this is equivalent to freeing memory.
 *
 * \param pointer A pointer to the already allocated memory
 * \param size The new size for the memory chunk
 * \return A pointer to the resized memory chunk
 */
- (void*)resizeMemory: (void*)pointer
	       toSize: (size_t)size;

/**
 * \brief Resizes memory in the object's memory pool to the specific number of
 *	  items of the specified size.
 *
 * If the pointer is NULL, this is equivalent to allocating memory.
 * If the size or number of items is 0, this is equivalent to freeing memory.
 *
 * \param pointer A pointer to the already allocated memory
 * \param nItems The number of items to resize to
 * \param size The size of each item to resize to
 * \return A pointer to the resized memory chunk
 */
- (void*)resizeMemory: (void*)pointer
	     toNItems: (size_t)nItems
	     withSize: (size_t)size;

/**
 * \brief Frees allocated memory and removes it from the object's memory pool.
 *
 * Does nothing if the pointer is NULL.
 *
 * \param pointer A pointer to the allocated memory
 */
- (void)freeMemory: (void*)pointer;

/**
 * \brief Deallocates the object.
 *
 * It is automatically called when the retain count reaches zero, but not when
 * the garbage collector disposes of the object (see finalize).
 *
 * This also frees all memory in its memory pool.
 */
- (void)dealloc;

/**
 * \brief A method which is called before the garbage collector disposes of the
 *	  object.
 *
 * This is useful for example to close files if they haven't been closed by the
 * user yet.
 *
 * Note: Currently, there is no garbage collector. This method only exists to
 *	 make it easy to add support for a garbage collector later.
 */
- (void)finalize;
@end

/**
 * \brief A protocol for the creation of copies.
 */
@protocol OFCopying <OFObject>
/**
 * \brief Copies the object.
 *
 * For classes which can be immutable or mutable, this returns an immutable
 * copy. If only a mutable version of the class exists, it creates a mutable
 * copy.
 *
 * \return A copy of the object
 */
- copy;
@end

/**
 * \brief A protocol for the creation of mutable copies.
 *
 * This protocol is implemented by objects that can be mutable and immutable
 * and allows returning a mutable copy.
 */
@protocol OFMutableCopying <OFCopying>
/**
 * \brief Creates a mutable copy of the object.
 *
 * \return A mutable copy of the object
 */
- mutableCopy;
@end

/**
 * \brief A protocol for comparing objects.
 *
 * This protocol is implemented by objects that can be compared.
 */
@protocol OFComparing <OFObject>
/**
 * \brief Compares the object with another object.
 *
 * \param object An object to compare the object to
 * \return The result of the comparison
 */
- (of_comparison_result_t)compare: (id)object;
@end

Modified src/OFObject.m from [e69c1ca6c9] to [78d403774f].

567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655

656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744

- (OFString*)description
{
	/* Classes containing data should reimplement this! */
	return [OFString stringWithFormat: @"<%@: %p>", [self className], self];
}

- (void)addMemoryToPool: (void*)ptr
{
	void **memoryChunks;
	size_t memoryChunksSize;

	memoryChunksSize = PRE_IVAR->memoryChunksSize + 1;

	if (SIZE_MAX - PRE_IVAR->memoryChunksSize < 1 ||
	    memoryChunksSize > SIZE_MAX / sizeof(void*))
		@throw [OFOutOfRangeException newWithClass: isa];

	if ((memoryChunks = realloc(PRE_IVAR->memoryChunks,
	    memoryChunksSize * sizeof(void*))) == NULL)
		@throw [OFOutOfMemoryException newWithClass: isa
					      requestedSize: memoryChunksSize];

	PRE_IVAR->memoryChunks = memoryChunks;
	PRE_IVAR->memoryChunks[PRE_IVAR->memoryChunksSize] = ptr;
	PRE_IVAR->memoryChunksSize = memoryChunksSize;
}

- (void*)allocMemoryWithSize: (size_t)size
{
	void *ptr, **memoryChunks;
	size_t memoryChunksSize;

	if (size == 0)
		return NULL;

	memoryChunksSize = PRE_IVAR->memoryChunksSize + 1;

	if (SIZE_MAX - PRE_IVAR->memoryChunksSize == 0 ||
	    memoryChunksSize > SIZE_MAX / sizeof(void*))
		@throw [OFOutOfRangeException newWithClass: isa];

	if ((ptr = malloc(size)) == NULL)
		@throw [OFOutOfMemoryException newWithClass: isa
					      requestedSize: size];

	if ((memoryChunks = realloc(PRE_IVAR->memoryChunks,
	    memoryChunksSize * sizeof(void*))) == NULL) {
		free(ptr);
		@throw [OFOutOfMemoryException newWithClass: isa
					      requestedSize: memoryChunksSize];
	}

	PRE_IVAR->memoryChunks = memoryChunks;
	PRE_IVAR->memoryChunks[PRE_IVAR->memoryChunksSize] = ptr;
	PRE_IVAR->memoryChunksSize = memoryChunksSize;

	return ptr;
}

- (void*)allocMemoryForNItems: (size_t)nItems
		     withSize: (size_t)size
{
	if (nItems == 0 || size == 0)
		return NULL;

	if (nItems > SIZE_MAX / size)
		@throw [OFOutOfRangeException newWithClass: isa];

	return [self allocMemoryWithSize: nItems * size];
}

- (void*)resizeMemory: (void*)ptr
	       toSize: (size_t)size
{
	void **iter;

	if (ptr == NULL)
		return [self allocMemoryWithSize: size];

	if (size == 0) {
		[self freeMemory: ptr];
		return NULL;
	}

	iter = PRE_IVAR->memoryChunks + PRE_IVAR->memoryChunksSize;

	while (iter-- > PRE_IVAR->memoryChunks) {
		if (OF_UNLIKELY(*iter == ptr)) {

			if (OF_UNLIKELY((ptr = realloc(ptr, size)) == NULL))
				@throw [OFOutOfMemoryException
				     newWithClass: isa
				    requestedSize: size];

			*iter = ptr;
			return ptr;
		}
	}

	@throw [OFMemoryNotPartOfObjectException newWithClass: isa
						      pointer: ptr];
}

- (void*)resizeMemory: (void*)ptr
	     toNItems: (size_t)nItems
	     withSize: (size_t)size
{
	if (ptr == NULL)
		return [self allocMemoryForNItems: nItems
					 withSize: size];

	if (nItems == 0 || size == 0) {
		[self freeMemory: ptr];
		return NULL;
	}

	if (nItems > SIZE_MAX / size)
		@throw [OFOutOfRangeException newWithClass: isa];

	return [self resizeMemory: ptr
			   toSize: nItems * size];
}

- (void)freeMemory: (void*)ptr;
{
	void **iter, *last, **memoryChunks;
	size_t i, memoryChunksSize;

	if (ptr == NULL)
		return;

	iter = PRE_IVAR->memoryChunks + PRE_IVAR->memoryChunksSize;
	i = PRE_IVAR->memoryChunksSize;

	while (iter-- > PRE_IVAR->memoryChunks) {
		i--;

		if (OF_UNLIKELY(*iter == ptr)) {
			memoryChunksSize = PRE_IVAR->memoryChunksSize - 1;
			last = PRE_IVAR->memoryChunks[memoryChunksSize];

			assert(PRE_IVAR->memoryChunksSize != 0 &&
			    memoryChunksSize <= SIZE_MAX / sizeof(void*));

			if (OF_UNLIKELY(memoryChunksSize == 0)) {
				free(ptr);
				free(PRE_IVAR->memoryChunks);

				PRE_IVAR->memoryChunks = NULL;
				PRE_IVAR->memoryChunksSize = 0;

				return;
			}

			free(ptr);
			PRE_IVAR->memoryChunks[i] = last;
			PRE_IVAR->memoryChunksSize = memoryChunksSize;

			if (OF_UNLIKELY((memoryChunks = realloc(
			    PRE_IVAR->memoryChunks, memoryChunksSize *
			    sizeof(void*))) == NULL))
				return;

			PRE_IVAR->memoryChunks = memoryChunks;

			return;
		}
	}

	@throw [OFMemoryNotPartOfObjectException newWithClass: isa
						      pointer: ptr];
}

- retain
{
#if defined(OF_ATOMIC_OPS)
	of_atomic_inc_32(&PRE_IVAR->retainCount);
#else







|
















|





|











|





|





|


|














|




|



|






|
>
|




|
|




|


|



|




|






|



|




|








|







|








|















|







567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745

- (OFString*)description
{
	/* Classes containing data should reimplement this! */
	return [OFString stringWithFormat: @"<%@: %p>", [self className], self];
}

- (void)addMemoryToPool: (void*)pointer
{
	void **memoryChunks;
	size_t memoryChunksSize;

	memoryChunksSize = PRE_IVAR->memoryChunksSize + 1;

	if (SIZE_MAX - PRE_IVAR->memoryChunksSize < 1 ||
	    memoryChunksSize > SIZE_MAX / sizeof(void*))
		@throw [OFOutOfRangeException newWithClass: isa];

	if ((memoryChunks = realloc(PRE_IVAR->memoryChunks,
	    memoryChunksSize * sizeof(void*))) == NULL)
		@throw [OFOutOfMemoryException newWithClass: isa
					      requestedSize: memoryChunksSize];

	PRE_IVAR->memoryChunks = memoryChunks;
	PRE_IVAR->memoryChunks[PRE_IVAR->memoryChunksSize] = pointer;
	PRE_IVAR->memoryChunksSize = memoryChunksSize;
}

- (void*)allocMemoryWithSize: (size_t)size
{
	void *pointer, **memoryChunks;
	size_t memoryChunksSize;

	if (size == 0)
		return NULL;

	memoryChunksSize = PRE_IVAR->memoryChunksSize + 1;

	if (SIZE_MAX - PRE_IVAR->memoryChunksSize == 0 ||
	    memoryChunksSize > SIZE_MAX / sizeof(void*))
		@throw [OFOutOfRangeException newWithClass: isa];

	if ((pointer = malloc(size)) == NULL)
		@throw [OFOutOfMemoryException newWithClass: isa
					      requestedSize: size];

	if ((memoryChunks = realloc(PRE_IVAR->memoryChunks,
	    memoryChunksSize * sizeof(void*))) == NULL) {
		free(pointer);
		@throw [OFOutOfMemoryException newWithClass: isa
					      requestedSize: memoryChunksSize];
	}

	PRE_IVAR->memoryChunks = memoryChunks;
	PRE_IVAR->memoryChunks[PRE_IVAR->memoryChunksSize] = pointer;
	PRE_IVAR->memoryChunksSize = memoryChunksSize;

	return pointer;
}

- (void*)allocMemoryForNItems: (size_t)nItems
		     withSize: (size_t)size
{
	if (nItems == 0 || size == 0)
		return NULL;

	if (nItems > SIZE_MAX / size)
		@throw [OFOutOfRangeException newWithClass: isa];

	return [self allocMemoryWithSize: nItems * size];
}

- (void*)resizeMemory: (void*)pointer
	       toSize: (size_t)size
{
	void **iter;

	if (pointer == NULL)
		return [self allocMemoryWithSize: size];

	if (size == 0) {
		[self freeMemory: pointer];
		return NULL;
	}

	iter = PRE_IVAR->memoryChunks + PRE_IVAR->memoryChunksSize;

	while (iter-- > PRE_IVAR->memoryChunks) {
		if (OF_UNLIKELY(*iter == pointer)) {
			if (OF_UNLIKELY((pointer = realloc(pointer,
			    size)) == NULL))
				@throw [OFOutOfMemoryException
				     newWithClass: isa
				    requestedSize: size];

			*iter = pointer;
			return pointer;
		}
	}

	@throw [OFMemoryNotPartOfObjectException newWithClass: isa
						      pointer: pointer];
}

- (void*)resizeMemory: (void*)pointer
	     toNItems: (size_t)nItems
	     withSize: (size_t)size
{
	if (pointer == NULL)
		return [self allocMemoryForNItems: nItems
					 withSize: size];

	if (nItems == 0 || size == 0) {
		[self freeMemory: pointer];
		return NULL;
	}

	if (nItems > SIZE_MAX / size)
		@throw [OFOutOfRangeException newWithClass: isa];

	return [self resizeMemory: pointer
			   toSize: nItems * size];
}

- (void)freeMemory: (void*)pointer;
{
	void **iter, *last, **memoryChunks;
	size_t i, memoryChunksSize;

	if (pointer == NULL)
		return;

	iter = PRE_IVAR->memoryChunks + PRE_IVAR->memoryChunksSize;
	i = PRE_IVAR->memoryChunksSize;

	while (iter-- > PRE_IVAR->memoryChunks) {
		i--;

		if (OF_UNLIKELY(*iter == pointer)) {
			memoryChunksSize = PRE_IVAR->memoryChunksSize - 1;
			last = PRE_IVAR->memoryChunks[memoryChunksSize];

			assert(PRE_IVAR->memoryChunksSize != 0 &&
			    memoryChunksSize <= SIZE_MAX / sizeof(void*));

			if (OF_UNLIKELY(memoryChunksSize == 0)) {
				free(pointer);
				free(PRE_IVAR->memoryChunks);

				PRE_IVAR->memoryChunks = NULL;
				PRE_IVAR->memoryChunksSize = 0;

				return;
			}

			free(pointer);
			PRE_IVAR->memoryChunks[i] = last;
			PRE_IVAR->memoryChunksSize = memoryChunksSize;

			if (OF_UNLIKELY((memoryChunks = realloc(
			    PRE_IVAR->memoryChunks, memoryChunksSize *
			    sizeof(void*))) == NULL))
				return;

			PRE_IVAR->memoryChunks = memoryChunks;

			return;
		}
	}

	@throw [OFMemoryNotPartOfObjectException newWithClass: isa
						      pointer: pointer];
}

- retain
{
#if defined(OF_ATOMIC_OPS)
	of_atomic_inc_32(&PRE_IVAR->retainCount);
#else
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
	return [(id)self mutableCopy];
}

/*
 * Those are needed as the root class is the superclass of the root class's
 * metaclass and thus instance methods can be sent to class objects as well.
 */
+ (void)addMemoryToPool: (void*)ptr
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)allocMemoryWithSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)allocMemoryForNItems: (size_t)nItems
                     withSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)resizeMemory: (void*)ptr
	       toSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)resizeMemory: (void*)ptr
	     toNItems: (size_t)nItems
	     withSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void)freeMemory: (void*)ptr
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ retain
{







|


















|






|







|







863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
	return [(id)self mutableCopy];
}

/*
 * Those are needed as the root class is the superclass of the root class's
 * metaclass and thus instance methods can be sent to class objects as well.
 */
+ (void)addMemoryToPool: (void*)pointer
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)allocMemoryWithSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)allocMemoryForNItems: (size_t)nItems
                     withSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)resizeMemory: (void*)pointer
	       toSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void*)resizeMemory: (void*)pointer
	     toNItems: (size_t)nItems
	     withSize: (size_t)size
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ (void)freeMemory: (void*)pointer
{
	@throw [OFNotImplementedException newWithClass: self
					      selector: _cmd];
}

+ retain
{