2
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
3
<gsdoc base="NSObject" prev="NSNumberFormatter" next="NSPipe" up="Base">
5
<title>NSObject</title>
6
<author name="Richard Frith-Macdonald">
7
<email address="rfm@gnu.org"/>
8
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
10
<author name="Nicola Pero">
11
<email address="n.pero@mi.flashnet.it"/>
12
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
14
<version>$Revision: 1.13 $</version>
15
<date>$Date: 2001/11/13 17:37:13 $</date>
19
<heading>NSObject</heading>
20
<class name="NSObject">
21
<declared>Foundation/NSObject.h</declared>
22
<conform>NSObject</conform>
25
<code>NSObject</code> is the root class (a root class is
26
a class with no superclass) of the gnustep base library
27
class hierarchy, so all classes normally inherit from
28
<code>NSObject</code>. There is an exception though:
29
<code>NSProxy</code> (which is used for remote messaging)
30
does not inherit from <code>NSObject</code>.
33
Unless you are really sure of what you are doing, all
34
your own classes should inherit (directly or indirectly)
35
from <code>NSObject</code> (or in special cases from
36
<code>NSProxy</code>). <code>NSObject</code> provides
37
the basic common functionality shared by all gnustep
41
The essential methods which must be implemented by all
42
classes for their instances to be usable within gnustep
43
are declared in a separate protocol, which is the
44
<code>NSObject</code> protocol. Both
45
<code>NSObject</code> and <code>NSProxy</code> conform to
46
this protocol, which means all objects in a gnustep
47
application will conform to this protocol (btw, if you
48
don't find a method of <code>NSObject</code> you are
49
looking for in this documentation, make sure you also
50
look into the documentation for the <code>NSObject</code>
54
Theoretically, in special cases you might need to
55
implement a new root class. If you do, you need to make
56
sure that your root class conforms (at least) to the
57
<code>NSObject</code> protocol, otherwise it will not
58
interact correctly with the gnustep framework. Said
59
that, I must note that I have never seen a case in which
60
a new root class is needed.
63
<code>NSObject</code> is a root class, which implies that
64
instance methods of <code>NSObject</code> are treated in
65
a special way by the Objective-C runtime. This is an
66
exception to the normal way messaging works with class
67
and instance methods: if the Objective-C runtime can't
68
find a class method for a class object, as a last resort
69
it looks for an instance method of the root class with
70
the same name, and executes it if it finds it. This
71
means that instance methods of the root class (such as
72
<code>NSObject</code>) can be performed by class objects
73
which inherit from that root class ! This can only
74
happen if the class doesn't have a class method with the
75
same name, otherwise that method - of course - takes the
76
precedence. Because of this exception,
77
<code>NSObject</code>'s instance methods are written in
78
such a way that they work both on <code>NSObject</code>'s
79
instances and on class objects.
82
<method type="id" factory="yes">
85
Allocates a new instance of the receiver from the default
86
zone, by invoking <code>allocWithZone:</code> with
87
<code>NSDefaultMallocZone()</code> as the zone argument.
88
Returns the created instance.
91
<method type="id" factory="yes">
92
<sel>allocWithZone:</sel>
93
<arg type="NSZone*">zone</arg>
95
This is the basic method to create a new instance. It
96
allocates a new instance of the receiver from the specified
99
Memory for an instance of the receiver is allocated; a
100
pointer to this newly created instance is returned. All
101
instance variables are set to 0 except the
102
<code>isa</code> pointer which is set to point to the
103
object class. No initialization of the instance is
104
performed: it is your responsibility to initialize the
105
instance by calling an appropriate <code>init</code>
106
method. If you are not using the garbage collector, it is
107
also your responsibility to make sure the returned
108
instance is destroyed when you finish using it, by calling
109
the <code>release</code> method to destroy the instance
110
directly, or by using <code>autorelease</code> and
114
You do not normally need to override this method in
115
subclasses, unless you are implementing a class which for
116
some reasons silently allocates instances of another class
117
(this is typically needed to implement class clusters and
118
similar design schemes).
121
If you have turned on debugging of object allocation (by
122
calling the <code>GSDebugAllocationActive</code>
123
function), this method will also update the various
124
debugging counts and monitors of allocated objects, which
125
you can access using the <code>GSDebugAllocation...</code>
130
<method type="void" factory="yes">
131
<sel>cancelPreviousPerformRequestsWithTarget:</sel>
132
<arg type="id">aTarget</arg>
134
<arg type="SEL">aSelector</arg>
138
<method type="Class" factory="yes">
141
Returns the receiver.
144
<method type="BOOL" factory="yes">
145
<sel>conformsToProtocol:</sel>
146
<arg type="Protocol*">aProtocol</arg>
150
<method type="id" factory="yes">
151
<sel>copyWithZone:</sel>
152
<arg type="NSZone*">zone</arg>
156
<method type="NSString*" factory="yes">
157
<sel>description</sel>
159
The <code>description</code> factory method describes the class
160
of the receiver. In the default GNUstep implementation, this
161
simply returns the name of the class as an NSString object.
164
<method type="NSString*" factory="yes">
165
<sel>descriptionWithLocale:</sel>
166
<arg type="NSDictionary*">aLocale</arg>
168
The default (NSOBject) implementation of this method simply calls
169
the <code>description</code> method and discards the locale
172
<standards><GNUstep/></standards>
174
<method type="NSString*" factory="yes">
175
<sel>descriptionWithLocale:</sel>
176
<arg type="NSDictionary*">aLocale</arg>
178
<arg type="unsigned int">level</arg>
180
The default (NSObject) implementation of this method simply calls
181
the <code>descriptionWithLocale:</code> method and discards the
184
<standards><GNUstep/></standards>
186
<method type="NSString*" factory="yes">
187
<sel>descriptionWithLocale:</sel>
188
<arg type="NSDictionary*">aLocale</arg>
190
<arg type="unsigned int">level</arg>
192
<arg type="id<GNUDescriptionDestination>">output</arg>
194
The default (NSObject) implementation of this method simply calls
195
the <code>descriptionWithLocale:indent:</code> method and appends
196
the value returned by that method to the output object.
198
<standards><GNUstep/></standards>
200
<method type="void" factory="yes">
201
<sel>initialize</sel>
205
<method type="IMP" factory="yes">
206
<sel>instanceMethodForSelector:</sel>
207
<arg type="SEL">aSelector</arg>
211
<method type="NSMethodSignature*" factory="yes">
212
<sel>instanceMethodSignatureForSelector:</sel>
213
<arg type="SEL">aSelector</arg>
215
Returns a method signature object representing the
216
method implemented for instsances of this class which
217
corresponds to the supplied selector.
220
<method type="BOOL" factory="yes">
221
<sel>instancesRespondToSelector:</sel>
222
<arg type="SEL">aSelector</arg>
226
<method type="void" factory="yes">
231
<method type="id" factory="yes">
232
<sel>mutableCopyWithZone:</sel>
233
<arg type="NSZone*">zone</arg>
237
<method type="id" factory="yes">
240
This method is a short-hand for alloc followed by init, that is,
242
NSObject *object = [NSObject new];
244
is exactly the same as
246
NSObject *object = [[NSObject alloc] init];
249
This is a general convention: all <code>new...</code>
250
methods are supposed to return a newly allocated and
251
initialized instance, as would be generated by an
252
<code>alloc</code> method followed by a corresponding
253
<code>init...</code> method. Please note that if you are
254
not using a garbage collector, this means that instances
255
generated by the <code>new...</code> methods are not
256
autoreleased, that is, you are responsible for releasing
257
(autoreleasing) the instances yourself. So when you use
258
<code>new</code> you typically do something like:
262
NSMutableArray *array = AUTORELEASE ([NSMutableArray new]);
266
You do no normally need to override <code>new</code> in
267
subclasses, because if you override <code>init</code> (and
268
optionally <code>allocWithZone:</code> if you really
269
need), <code>new</code> will automatically use your
273
You might need instead to define new <code>new...</code>
274
methods specific to your subclass to match any
275
<code>init...</code> specific to your subclass. For
276
example, if your subclass defines
279
<code>-initWithName:</code>
282
it might be handy for you to have a
285
<code>+newWithName:</code>
288
which combines <code>alloc</code> and
289
<code>initWithName:</code>. You would implement it as follows:
293
+ (id) newWithName: (NSString *)aName
295
return [[self alloc] initWithName: aName];
301
<method type="void" factory="yes">
302
<sel>poseAsClass:</sel>
303
<arg type="Class">aClass</arg>
307
<method type="void" factory="yes">
308
<sel>setVersion:</sel>
309
<arg type="int">aVersion</arg>
313
<method type="Class" factory="yes">
314
<sel>superclass</sel>
318
<method type="int" factory="yes">
324
<sel>awakeAfterUsingCoder:</sel>
325
<arg type="NSCoder*">aDecoder</arg>
329
<method type="Class">
330
<sel>classForArchiver</sel>
334
<method type="Class">
335
<sel>classForCoder</sel>
339
<method type="Class">
340
<sel>classForPortCoder</sel>
345
<sel>connection:</sel>
346
<arg type="NSConnection*">connection</arg>
347
<sel>handleRequest:</sel>
348
<arg type="NSDistantObjectRequest*">doreq</arg>
361
<code>NSObject</code>'s implementation of this method
362
destroys the receiver, by returning the memory allocated
363
to the receiver to the system. After this method has been
364
called on an instance, you must not refer the instance in
365
any way, because it does not exist any longer. If you do,
366
it is a bug and your program might even crash with a
370
If you have turned on the debugging facilities for
371
instance allocation, <code>NSObject</code>'s
372
implementation of this method will also update the various
373
counts and monitors of allocated instances (see the
374
<code>GSDebugAllocation...</code> functions for more
378
Normally you are supposed to manage the memory taken by
379
objects by using the high level interface provided by the
380
<code>retain</code>, <code>release</code> and
381
<code>autorelease</code> methods (or better by the
382
corresponding macros <code>RETAIN</code>,
383
<code>RELEASE</code> and <code>AUTORELEASE</code>), and by
384
autorelease pools and such; whenever the
385
release/autorelease mechanism determines that an object is
386
no longer needed (which happens when its retain count
387
reaches 0), it will call the <code>dealloc</code> method
388
to actually deallocate the object. This means that normally,
389
you should not need to call <code>dealloc</code> directly as
390
the gnustep base library automatically calls it for you when
391
the retain count of an object reaches 0.
394
Because the <code>dealloc</code> method will be called
395
when an instance is being destroyed, if instances of your
396
subclass use objects or resources (as it happens for most
397
useful classes), you must override <code>dealloc</code> in
398
subclasses to release all objects and resources which are
399
used by the instance, otherwise these objects and
400
resources would be leaked. In the subclass
401
implementation, you should first release all your subclass
402
specific objects and resources, and then invoke super's
403
implementation (which will do the same, and so on up in
404
the class hierarchy to <code>NSObject</code>'s
405
implementation, which finally destroys the object). Here
406
is an example of the implementation of
407
<code>dealloc</code> for a subclass whose instances have a
408
single instance variable <code>name</code> which needs to
409
be released when an instance is deallocated:
421
<code>dealloc</code> might contain code to release not
422
only objects, but also other resources, such as open
423
files, network connections, raw memory allocated in other
428
<method type="NSString*">
429
<sel>description</sel>
432
The <code>description</code> method describes the reciever.
433
In the default GNUstep implementation, this returns an NSString
434
object giving the name of the class of the receiver and the
435
hexadecimal representation of the recievers address enclosed
439
Generally, classes other than NSObject will override this method
440
to provide a more informative description of their instances.
444
<method type="NSString*">
445
<sel>descriptionWithLocale:</sel>
446
<arg type="NSDictionary*">aLocale</arg>
448
The default (NSOBject) implementation of this method simply calls
449
the <code>description</code> method and discards the locale
452
<standards><GNUstep/></standards>
454
<method type="NSString*">
455
<sel>descriptionWithLocale:</sel>
456
<arg type="NSDictionary*">aLocale</arg>
458
<arg type="unsigned int">level</arg>
460
The default (NSObject) implementation of this method simply calls
461
the <code>descriptionWithLocale:</code> method and discards the
464
<standards><GNUstep/></standards>
466
<method type="NSString*">
467
<sel>descriptionWithLocale:</sel>
468
<arg type="NSDictionary*">aLocale</arg>
470
<arg type="unsigned int">level</arg>
472
<arg type="id<GNUDescriptionDestination>">output</arg>
474
The default (NSObject) implementation of this method simply calls
475
the <code>descriptionWithLocale:indent:</code> method and appends
476
the value returned by that method to the output object.
478
Property-list classes (NSString, NSArray, NSDictionary and
479
NSData) will override this method in order to efficiently
480
write descriptions of themselves into property lists.
483
<standards><GNUstep/></standards>
486
<sel>doesNotRecognizeSelector:</sel>
487
<arg type="SEL">aSelector</arg>
492
<sel>forwardInvocation:</sel>
493
<arg type="NSInvocation*">anInvocation</arg>
497
<method type="unsigned int">
509
<arg type="id">anObject</arg>
514
<sel>methodForSelector:</sel>
515
<arg type="SEL">aSelector</arg>
519
<method type="NSMethodSignature*">
520
<sel>methodSignatureForSelector:</sel>
521
<arg type="SEL">aSelector</arg>
523
Returns a method signature object representing the
524
method implemented in this object which corresponds to
525
the supplied selector.
529
<sel>mutableCopy</sel>
534
<sel>performSelector:</sel>
535
<arg type="SEL">aSelector</arg>
536
<sel>withObject:</sel>
537
<arg type="id">anArgument</arg>
542
<sel>performSelector:</sel>
543
<arg type="SEL">aSelector</arg>
544
<sel>withObject:</sel>
545
<arg type="id">anArgument</arg>
546
<sel>afterDelay:</sel>
547
<arg type="NSTimeInterval">delay</arg>
549
<arg type="NSArray*">modes</arg>
554
<sel>replacementObjectForArchiver:</sel>
555
<arg type="NSArchiver*">anArchiver</arg>
560
<sel>replacementObjectForCoder:</sel>
561
<arg type="NSCoder*">aCoder</arg>
566
<sel>replacementObjectForPortCoder:</sel>
567
<arg type="NSPortCoder*">aCoder</arg>
572
<sel>deallocNotificationsActive</sel>
575
Returns a boolean indicating whether deallocation notification
579
If deallocation notification is turned on, whenever an objects
580
retain count reaches zero (and it would normally be deallocated)
581
the <em>_dealloc</em> methiod is called and the object is only
582
deallocated if that method returns YES.
587
<sel>setDeallocNotificationsActive:</sel>
588
<arg type="BOOL">flag</arg>
591
Turns on (or off) deallocation notification.
594
If deallocation notification is turned on, whenever an objects
595
retain count reaches zero (and it would normally be deallocated)
596
the <em>_dealloc</em> methiod is called and the object is only
597
deallocated if that method returns YES.
605
Returns a boolean indicating whether the receiver should be
606
deallocated or not. The default implementation returns YES.
609
This method is called when an objects retain count reaches
610
zero (if deallocation notifications are active).
613
This method is provided so that you can take some sort of
614
action when objects are deallocated ... normally you would
615
override this method in your classes, but you could also
616
override it in a category of NSObject - and perform some
617
action whenever <em>any</em> object is deallocated.
added
removed
Documentation/gsdoc/NSObject.gsdoc
